Web UI Port — Configuration and Conflict Handling#

How OpenProgram chooses, configures, and defends the port its web UI runs on: the configuration surface (openprogram ports) and what happens when the port is occupied. The runtime that makes one port sufficient is described in single-port.md.

The port at a glance#

The browser, the TUI and the CLI all talk to this one port. There is no proxy hop and no second process.

Why 18100#

A fixed, uncommon, 5-digit value chosen so it almost never collides with something already running:

• In the registered-port range (< 49152), so it never clashes with the OS ephemeral range the kernel hands out to outbound sockets.
• The 18xxx block is rarely used by mainstream dev tooling — unlike 3000 / 5173 / 8000 / 8080, which any other project may already hold.

A fixed port also means a stable, bookmarkable URL and a browser session (localStorage, service worker scope) that survives restarts.

Configuration surface#

explicit flag / arg  >  environment variable  >  stored pref  >  built-in default

openprogram ports#

openprogram ports                 # show the current port
openprogram ports --port 9100     # set + persist

Writes to ~/.openprogram/config.json under ui.web_port. Nothing live is rebound — the change takes effect on the next openprogram web / openprogram worker start.

openprogram setup ui#

The interactive wizard asks for the port (and the auto-open-browser pref) and validates range 1–65535.

Environment override (single run, not persisted)#

• OPENPROGRAM_WEB_PORT — the port for this process.

Per-launch flag#

openprogram web --web-port <p> overrides for that run without persisting.

Where each entry point reads from#

resolve_worker_port() in openprogram/worker/lifecycle.py is the one resolution path: OPENPROGRAM_WEB_PORT → pref ui.web_port → 18100. read_ui_prefs() / set_ui_ports() in openprogram/setup.py are the one read/write path for the persisted pref.

Conflict handling#

The port is pinned on purpose — a stable UI URL is worth more than "start no matter what". So the policy is reuse if it's ours, report and refuse if it's not — never kill the holder, never silently drift to a random port. This mirrors openclaw. All probing lives in one module, openprogram/_ports.py:

• liveness — port_in_use(port): a bare TCP connect.
• identity — backend_is_ours(port) first checks the managed worker PID and port files plus the active profile's owner-only web/access.json snapshot, then sends a fresh random nonce to /api/auth/challenge and verifies the returned token-HMAC proof locally. The probe never sends the owner token or a Bearer header to the listener; a foreign process on the port cannot obtain the credential. An optional expected_revision binds the proof to the revision served by an upgrade target.
• ownership — describe_port_owner(port) / port_owner_hint(port): lsof / netstat + /proc / ps / wmic to name the holding PID and command line, classified ours-vs-foreign. This is what lets a "port in use" error say who holds it.

Behavior by case#

The one deliberate asymmetry: openprogram web is a foreground UI command, so a foreign squatter is a hard stop. The worker is a long-running host for channels and the webui, so it stays up, falling back to another port with a diagnostic message, rather than refusing entirely.

Relationship to openclaw#

openclaw pins its gateway to 18789 and handles conflicts in three layers; OpenProgram's equivalents:

Notably, openclaw's lsof diagnostic is not on its main gateway-start path (only on the SSH-tunnel path), so its gateway-start "port in use" error can't name the holder. OpenProgram wires the owner diagnostic into the actual start path.