Codex Relay Agent

Connect a macOS or Linux machine running Codex CLI to your self-hosted Codex Relay. The connection is outbound-only, so the machine does not need a public IP or an open inbound port.

The Agent also provides workspace helpers for directory browsing, Git branch discovery, isolated worktree creation, and authenticated streaming of local artifacts referenced by Codex Markdown.

Artifact serving is constrained to regular files inside workspaces already opened by the active Codex app-server session. Files are streamed on demand through Relay with HTTP Range support and are not stored on the Relay host.

Requirements

• macOS or Linux
• Node.js 20 or newer
• Codex CLI installed and already authenticated for the current user
• A Relay URL, machine ID, and matching agent token

Verify Codex first:

codex --version
codex app-server --help

Install as a user service

Run this as the same OS user that is logged in to Codex:

npx codex-relay-agent install \
  --relay https://relay.example.com \
  --token 'your-machine-token' \
  --machine-id work-mac \
  --name 'Work Mac'

To avoid putting the token in shell history, set AGENT_TOKEN in the environment and omit --token.

The installer creates a per-user service:

• macOS: ~/Library/LaunchAgents/com.codex-relay.agent.plist
• Linux: ~/.config/systemd/user/codex-relay-agent.service

No sudo is required or recommended. Keeping the service under the current user ensures it can access that user's Codex authentication and workspaces.

Commands

npx codex-relay-agent doctor
npx codex-relay-agent status
npx codex-relay-agent@latest restart
npx codex-relay-agent uninstall

Run in the foreground without installing a service:

npx codex-relay-agent run --relay https://relay.example.com --token 'your-machine-token'

Use npx codex-relay-agent --help for all options, including proxy and private CA configuration.

Automatic updates

Services installed by version 0.5.2 or newer check npm after connecting and then about every six hours. The Agent verifies npm's integrity hash, syntax-checks the downloaded runtime, atomically replaces it, and lets launchd/systemd restart the process. If the replacement fails to become healthy three times, the previous runtime is restored automatically. Update progress and errors appear beside the machine in Relay.

Set --auto-update false (or AUTO_UPDATE=false) to opt out. A private npm-compatible registry can be selected with --update-registry <url>.

Linux notes

The installer uses a systemd user service. On a desktop it runs while the user session is active. To keep it running after logout, an administrator may enable lingering for that user:

sudo loginctl enable-linger "$USER"

Upgrade

Upgrade the Codex CLI used by the installed service, then restart that service:

npx codex-relay-agent@latest upgrade-codex --dry-run
npx codex-relay-agent@latest upgrade-codex
# npm installations can also select an exact Codex version:
npx codex-relay-agent@latest upgrade-codex --version 0.111.0

Run as the service owner, without sudo. Supports global npm installations (including custom Node prefixes) and Homebrew on macOS. The command reads the existing service configuration, preserves the machine ID, token and workspace settings, and verifies codex --version and codex app-server --help before restarting. Upgrade or verification failure prevents the restart; custom/manual Codex installations are rejected with instructions rather than silently replaced. A failed package-manager operation may still have changed the installation; inspect its output before retrying.

Restarting interrupts active tasks and reconnects the machine. Run it after tasks finish. This upgrades Codex only, not the Agent runtime; Agent automatic updates remain separate. restart can also be used after manually upgrading Codex.

Agents older than 0.5.2 need one final manual install with the same machine ID and configuration. After that, verified stable releases are installed automatically unless automatic updates are disabled.