# 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:

```sh
codex-app-server-bridge app-server
```

Configure `codex-acp` with both of these environment variables:

```sh
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:

```text
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:

```sh
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

```sh
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.