OpenProgram Docs

Overview#

OpenProgram's Web UI, TUI, and CLI all sit on top of one resident local service, called the worker in code and logs. This page covers how it starts, how to check its status, and where the ports and logs are.

Starting#

No manual start is needed. Running openprogram (the terminal UI) automatically launches a background worker and connects to it if none is running. To disable the auto-launch, set OPENPROGRAM_NO_AUTO_WORKER=1; the TUI then only connects to an existing worker.

For manual control, use the openprogram worker subcommands:

openprogram worker start     # start a worker in the background and return
openprogram worker run       # run in the foreground (blocking), for debugging; Ctrl-C to stop
openprogram worker status    # running or not, PID, port, uptime
openprogram worker stop      # stop (SIGTERM, escalating to SIGKILL if needed)
openprogram worker restart   # stop and start a fresh one

openprogram web starts the service in the current terminal and opens the browser UI (http://localhost:18100).

status / stop / restart#

Three shortcut commands also exist at the top level:

openprogram status     # is the background service running (PID, port, uptime, log path)
openprogram stop       # stop the background service
openprogram restart    # restart (after code or config changes)

Example output of openprogram status:

openprogram: running (PID 82472, port 18100, up 48m)
  logs: ~/.openprogram/worker.log

Port#

The worker listens on a single port (default 18100) that serves everything: the API, the WebSocket (both the TUI and the Web UI connect to it), and the web UI itself — the address you open in the browser.

Persistent change:

openprogram ports --port 8101

One-off override: the environment variable OPENPROGRAM_WEB_PORT, or openprogram web --web-port <p>. Precedence: explicit flag → environment variable → persisted preference → default.

Logs#

openprogram logs list           # all log files (size, last updated)
openprogram logs tail [name]    # last N lines (default 50); -n line count, -f follow
openprogram logs path [name]    # print the log file's absolute path

There are three log names: worker (the default, ~/.openprogram/worker.log), runtime (~/.openprogram/logs/runtime.log), and ink-startup (TUI startup log, ~/.openprogram/logs/ink-startup.log). Prefixes match, so openprogram logs tail ink works.

Running as a login service#

openprogram worker install      # install as a system service
openprogram worker uninstall    # remove it

macOS uses launchd (~/Library/LaunchAgents/ai.openprogram.worker.plist); Linux uses systemd --user. Once installed, the worker starts automatically at login and restarts after a crash. openprogram status shows whether the service is installed.

Last updated · 2026-08-13
PreviousChat ChannelsNextConfiguration