@leoustc/ai-runner-codex

Local npm CLI connector for Agent Runner Hub. It loads a config file, connects to the public Hub WebSocket room, starts a local Codex app-server over WebSocket, and relays Hub messages to Codex.

Usage

Create a config from the example:

cp .env.example .env

Run with the default .env:

ai-runner-codex

Run with an explicit config file:

ai-runner-codex -f .env

Make Targets

make build
make local
make publish

make local runs ai-runner-codex -f .env. make publish runs the build check first, then publishes the package to npm with public access.

Config

Required:

ROOM_WSS=wss://agentrunner-hub.leoustc.com/room/...
ROOM_ID=...
ROOM_TOKEN=rt_...
ROOM_AGENT_NAME=lisa
ROOM_AGENT_ID=lisa_0000

Optional:

# Runner-owned agent metadata. Defaults are generated by ai-runner-codex.
ROOM_AGENT_ROLE=Answer clearly and concisely.
ROOM_AGENT_MODEL=codex

CODEX_LISTEN=ws://127.0.0.1:17655
CODEX_COMMAND=codex app-server --listen {listen}
CODEX_LOGIN_COMMAND=codex login --device-auth
CODEX_LOGIN_TIMEOUT_MS=600000
CODEX_CWD=.
CODEX_HOME=
CODEX_MODEL=
CODEX_SANDBOX=read-only
CODEX_APPROVAL_POLICY=never
CODEX_REQUEST_TIMEOUT_MS=120000
HEARTBEAT_INTERVAL_MS=60000
HUB_STALE_TIMEOUT_MS=180000
HUB_WATCHDOG_INTERVAL_MS=30000
OUTBOUND_QUEUE_MAX=100
RECONNECT_MIN_MS=2000
RECONNECT_MAX_MS=60000
LOG_LEVEL=info

ROOM_AGENT_ROLE and ROOM_AGENT_MODEL are not issued by the Hub. They are local runner settings used when registering the agent and can be changed per runner.

The runner keeps a hot Codex app-server process. CODEX_LISTEN must be a local ws://127.0.0.1:PORT listener. The runner uses one JSON-RPC message per WebSocket text frame.

On startup, the runner checks that the codex CLI is installed and available on PATH before starting app-server.

If Codex returns an auth/login error or a generic app-server error, the runner starts CODEX_LOGIN_COMMAND, posts a normal agent message with codexLogin: true, status, and any parsed device login url, code, and deviceId back to the Hub, waits for login completion, then retries the Codex request once. The login command is spawned as a local child process and the runner watches stdout/stderr for the device login values. While login is in progress, cleaned login output is streamed to every waiting Hub request, and a new request that arrives mid-login receives the recent output plus the latest parsed URL/code/deviceId.

Hub WebSocket behavior:

• HEARTBEAT_INTERVAL_MS defaults to 60000, so the runner sends a heartbeat every 60 seconds while connected.
• If the socket closes or is detected stale, the runner reconnects with bounded exponential backoff between RECONNECT_MIN_MS and RECONNECT_MAX_MS.
• Agent replies produced while the Hub socket is briefly down are queued up to OUTBOUND_QUEUE_MAX and flushed after reconnect.

Prompt behavior:

• ask/chat: answer from workspace knowledge without editing files.
• task: do the requested work, then return concise steps, outcome, and checks.

The runner authenticates with the Hub using WebSocket subprotocols:

room-auth
room-token.${ROOM_TOKEN}

Do not commit real .env files.