@codexhost/cli
Run Pi and Claude Code as first-class external harnesses inside Codex Desktop.
Install
npm install -g @codexhost/[email protected]
npm automatically installs the matching macOS, Windows, or Linux platform package. Node.js 22.19.0 or later, except 23.x is required. Official ChatGPT/Codex Desktop is only required for the Desktop interface; Web is included and works without it.
Usage
codexhost --version
codexhost
codexhost web
codexhost status
codexhost autostart on
codexhost autostart status
codexhost stop
codexhost remote install
codexhost remote status
The codexhost command starts Codex Desktop and background Web; without Desktop installed it opens Web instead. On macOS and Linux it returns immediately while the packaged Launcher keeps supervising in the background. On Windows, the command remains attached until Codex Desktop exits so shells that clean up process trees of completed commands cannot discard the supervisor. Re-running codexhost attaches to the same controlled instance.
codexhost web ensures Host and Web run in the background, prints a local login link and opens a browser. Over SSH or without a graphical session it only prints the link. Closing the terminal, Desktop or browser leaves Host and Web running; the computer must stay awake and connected. CODEXHOST_WEB_SERVICE=0 disables Web startup alongside codexhost.
Web initially listens on 127.0.0.1:4400. Use the local Connect devices page for LAN access and Tailscale Serve, or run codexhost web --host 0.0.0.0 --port 4500. The options --host, --port, --public-url and --trusted-proxy are validated and saved for later starts; an empty value clears an option. Changing them restarts only Web, disconnecting Web terminals but not Host tasks. An occupied port fails without killing its owner or selecting another port. LAN HTTP is unencrypted.
Matching services are reused. A different version or installation replaces the running services; replacing Host interrupts tasks without confirmation. codexhost status is read-only and shows Host/Web versions, the token-free Web address, the last Web failure and autostart status. codexhost stop stops managed Desktop, Web, Host, remote services, Broker and Console in that order, reports interrupted Host tasks, and preserves session data and configuration. A Desktop opened independently is not closed. Remote services return when another computer reconnects; interrupted tasks do not resume automatically.
Autostart is off by default. codexhost autostart on|off|status manages current-user login startup; it starts Host and Web without opening a browser. Linux requires systemd user services; linger is user-managed. Running codexhost refreshes enabled autostart with the current Node and CLI paths.
Office preview components are downloaded from the npm registry on first use on the Web computer, not the phone. No documents are uploaded for conversion. Download failure affects only Office previews; retry after checking the computer's network.
Uninstall or downgrade
Before removing this package or switching to a version without background Web support:
codexhost stop
codexhost autostart off
npm uninstall -g @codexhost/cli
Tailscale Serve configuration remains after stopping or uninstalling. Check tailscale serve status; only if the HTTPS 443 root path still points to this Web, remove it with tailscale serve --https=443 --set-path=/ off (substitute the actual HTTPS port). This leaves other paths intact. While Web is running, the local Connect devices page can also disable Serve after confirmation.
Notes
On macOS, remote install installs a current-user Aqua Harness broker so Background SSH Hosts can use native Claude Code login without reading, copying, or unlocking Keychain credentials.
If installation used --omit=optional, reinstall without that option so npm can select the native package for the current architecture.
If startup reports a platform package version mismatch, close Codex Desktop and run the exact reinstall command in the error. This installs both the CLI and its platform package at the same version, replacing stale independently installed payloads. codexhost --version reports the CLI package version; startup also validates the platform payload before launching it.