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.

Install from an immutable Git revision

The canonical repository is https://git.bodicsek.host/bodicsek/codex-app-server-bridge.git. Git access and any required trust or authentication configuration are host prerequisites; keep credentials out of package URLs and command output. Preflight the exact release tag before installation:

git ls-remote --exit-code \
  https://git.bodicsek.host/bodicsek/codex-app-server-bridge.git \
  refs/tags/v0.1.1

Install only an immutable release tag or full 40-character commit. Do not use #main for a reproducible installation. The repository contains the compiled runtime, so lifecycle scripts are disabled and no TypeScript toolchain is needed on the consumer machine:

npm run verify:git-package -- \
  'git+https://git.bodicsek.host/bodicsek/codex-app-server-bridge.git#v0.1.1'
npm install --global \
  --ignore-scripts \
  --cache /private/tmp/codex-app-server-bridge-npm-cache \
  'git+https://git.bodicsek.host/bodicsek/codex-app-server-bridge.git#v0.1.1'
command -v codex-app-server-bridge
npm list --global --depth=0 codex-app-server-bridge
codex-app-server-bridge --unsupported

For a commit pin, replace v0.1.1 in both commands with the full commit reported by git ls-remote; abbreviated commits and branches are rejected by the verifier. The verifier uses a temporary global prefix and never contacts a Codex App Server. The end-user install intentionally omits --prefix so the executable is placed on the normal global PATH used to launch Emacs.

Installing v0.1.1 upgrades the existing 0.1.0 local-tarball installation in place. The package name, executable, and CODEX_PATH value do not change. Existing bridge processes continue using the version with which they started; new agent-shell launches discover the replacement PATH executable.

To roll back, reinstall the verified 0.1.0 tarball or a previously verified immutable Git revision:

npm install --global \
  --ignore-scripts \
  --cache /private/tmp/codex-app-server-bridge-npm-cache \
  /Users/dnabracz/Work/packages/codex-app-server-bridge-0.1.0.tgz
npm install --global \
  --ignore-scripts \
  --cache /private/tmp/codex-app-server-bridge-npm-cache \
  'git+https://git.bodicsek.host/bodicsek/codex-app-server-bridge.git#v0.1.1'

Remove the globally installed package without changing Emacs configuration:

npm uninstall --global codex-app-server-bridge

Build and verify a local npm package

No registry publication is used. The package remains private. Maintainers use the explicit pack:verified workflow, which compiles, tests, checks committed runtime freshness, and invokes npm pack --ignore-scripts. A raw npm pack does not run those release gates.

mkdir -p /Users/dnabracz/Work/packages
npm run pack:verified -- \
  --pack-destination /Users/dnabracz/Work/packages \
  --cache /private/tmp/codex-app-server-bridge-npm-cache
npm run verify:package -- \
  /Users/dnabracz/Work/packages/codex-app-server-bridge-0.1.1.tgz

The artifact contains only package metadata, README.md, LICENSE, the launcher under bin/, and the two compiled runtime files under dist/. TypeScript source, tests, credentials, caches, and local artifacts are excluded. The verifier installs the tarball in a temporary prefix and exercises the installed launcher without connecting to the shared App Server.

Development

npm ci
npm run typecheck
npm run compile
npm test
npm run verify:runtime

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. When source changes, commit the matching dist/cli.js and dist/config.js output; npm run verify:runtime fails when those files are stale.