codex-app-server-bridge

codex-app-server-bridge

codex-app-server-bridge lets stock codex-acp use an already-running Codex App Server. It adapts the child-process transport expected by codex-acp (newline-delimited messages on stdio) to the App Server WebSocket transport (one text frame per message).

The bridge is deliberately only a transport adapter. It does not discover, start, stop, restart, supervise, or reconnect to a Codex App Server, and it never falls back to a private server.

Prerequisites

• Node.js 24 or newer. Release packaging compiles the TypeScript source to ESM JavaScript; the installed executable runs only that build output.
• A separately managed Codex App Server listening on an accepted loopback URL.
• Stock codex-acp. Version 1.6.2 was used for the 0.1.0 validation.

The 0.1.0 release was validated with Node.js 24.19.0, codex-acp 1.6.2, and Codex CLI 0.149.0.

Invocation and environment

The executable accepts exactly one command:

codex-app-server-bridge app-server

Configure codex-acp with both of these environment variables:

CODEX_PATH=/absolute/path/to/codex-app-server-bridge
CODEX_APP_SERVER_URL=ws://127.0.0.1:4500

CODEX_PATH tells codex-acp which executable to invoke with app-server. CODEX_APP_SERVER_URL is required by the bridge and must be a root-path URL in exactly one of these forms, with an explicit port from 1 through 65535:

ws://127.0.0.1:<port>
ws://[::1]:<port>

localhost, non-loopback addresses, credentials, TLS, paths, query strings, and fragments are rejected before a socket is opened. If the configured shared server is absent, the bridge exits nonzero within the five-second startup deadline. It does not start another server.

Each bridge process creates at most one WebSocket connection and never reconnects. Blank input records are ignored. Other records and server text frames are relayed in order without parsing their JSON-RPC content. Binary frames are rejected. Normal relay is silent on stderr, and failure diagnostics never include JSON-RPC payloads.

Stdin EOF, SIGINT, and SIGTERM close only the bridge connection and exit successfully. They do not stop or otherwise manage the shared App Server.

Authentication scope

Authentication belongs to the shared App Server, not to the bridge. Requests such as account/logout are forwarded unchanged. Logging out through any connected client therefore logs out the shared server and affects every client using that server.

Source-based release and installation

No registry publication is used. From a clean source checkout:

npm ci
npm run typecheck
npm run build
npm test
npm pack --dry-run
npm pack
npm install --global ./codex-app-server-bridge-0.1.0.tgz
command -v codex-app-server-bridge
codex-app-server-bridge --unsupported

The dry-run file list is the review boundary for the installable unit. It should contain only package.json, README.md, LICENSE, bin/, and the generated dist/ JavaScript. TypeScript source, tests, credentials, and local artifacts are excluded. The generated build output is reproducible and remains uncommitted.

Development

npm ci
npm run typecheck
npm run build
npm test

Tests use only node:test and a loopback WebSocket peer built from Node core APIs. They do not require Codex, credentials, or external network access.