Custom editors and desktop clients need a way to exchange conversations, approvals, and streamed events with Codex. The Codex app server provides that interface, and a local WebSocket listener lets a client connect to an already running process.
The default transport uses standard input and output for clients that launch their own server. A WebSocket listener instead stays open in one terminal while the Codex terminal interface or another compatible client connects from a separate process.
The app server and its WebSocket transport are experimental and unsupported for production workloads. Model-backed turns need a supported provider configured in the server's environment, with a Codex login or API key when that provider requires one.
An unauthenticated WebSocket listener exposes agent control to any client that can reach it. Keep ws:// bound to 127.0.0.1 for local use or SSH port forwarding; direct remote access requires WebSocket authentication and TLS.
Steps to start the Codex app server locally:
- Start a loopback WebSocket listener in the terminal that will run the server.
$ codex app-server --listen ws://127.0.0.1:4500 codex app-server (WebSockets) listening on: ws://127.0.0.1:4500 readyz: http://127.0.0.1:4500/readyz healthz: http://127.0.0.1:4500/healthz note: binds localhost only (use SSH port-forwarding for remote access)
The server runs in the foreground, so this terminal stays open while clients use it. If port 4500 is already in use, choose an unused port and substitute it in both commands.
- Connect the Codex terminal interface from another terminal on the same computer.
$ codex --remote ws://127.0.0.1:4500
The interface finishes loading and displays an input prompt such as Ask Codex to do anything when the connection succeeds. A connection error means the client has not reached the listener. The terminal client handles the protocol handshake; custom WebSocket clients must send initialize, then initialized, before thread or turn requests. Sign-in prompts concern the server's model provider rather than listener startup.
Related: How to check Codex login status
The server terminal stays open while clients use the listener. After testing, Ctrl-C in that terminal stops this foreground instance.