codex-server

Run Codex Desktop on any machine and access it from the browser.

Highlights

• Launch Codex from a local or remote machine and use the desktop web frontend in your browser.
• Package the Codex Desktop webview, preload bridge, app server integration, and Codex CLI into one runnable artifact.
• Use built-in password auth, TLS flags, config files, and environment overrides.
• Run on Bun or Node, with runtime shims for Electron and sqlite.
• Keep the published package version identical to the wrapped Codex Desktop build version.

Requirements

TL;DR: Linux machine with WebSockets enabled, Bun or Node 22+, and access to the Codex CLI credentials you want the app server to use.

The published npm package includes the prepared Codex Desktop assets.

Getting started

npx @coder/codex-server@latest

The executable installed by the package is named codex-server.

On first start, codex-server writes:

~/.config/codex-server/config.yaml

The default config is:

bind-addr: 127.0.0.1:8080
auth: password
password: <generated>
cert: false
log: info

Then open:

http://127.0.0.1:8080

Authentication

Supported modes:

auth: password

auth: none

For password auth, hashed-password takes precedence over password and accepts Argon2 hashes:

echo -n "thisismypassword" | npx argon2-cli -e

Then put the generated hash in the config:

auth: password
hashed-password: "$argon2i$v=19$m=4096,t=3,p=1$..."

Environment overrides are supported:

PASSWORD=secret npx @coder/codex-server

Failed login attempts are rate-limited to 2 per minute plus 12 per hour. /healthz, /readyz, and bundled static assets do not require authentication. The app shell, local file routes, uploads, and IPC websocket remain protected.

TLS

TLS options:

codex-server --cert
codex-server --cert-host codex.example.test
codex-server --cert /path/to/cert.pem --cert-key /path/to/key.pem

Config file keys map directly to those flags:

cert: true
cert-host: codex.example.test

cert: /path/to/cert.pem
cert-key: /path/to/key.pem

cert: true generates a host-specific self-signed certificate under ~/.local/share/codex-server/, for example localhost.crt and localhost.key. When running with Node, plain HTTP requests on the same port are redirected to HTTPS; Bun serves HTTPS directly.

Codex App Server

codex-server starts the HTTP server first, then loads the packaged Codex Desktop main bundle. That bundle owns the local Codex app-server lifecycle: it spawns codex app-server --listen <url> --analytics-default-enabled, performs the initialize handshake, restarts it when the desktop app decides to reconnect, and sends app-server state changes through the Electron IPC bridge.

The default app-server transport is stdio://. To change it:

codex-server --app-server-listen ws://127.0.0.1:5678

Building

Use Nix for the full package build:

nix build

Run from this checkout:

nix run

For local TypeScript work, use Bun:

nix develop
bun install
bun run build
bun run server

bun run build expects HOSTED_CODEX_APP_ZIP to point at a Codex Desktop zip. The dev shell sets this from the Nix-pinned input.

Testing

Fast checks use Bun:

bun run lint
bun run format:check
bun test

Full packaging validation uses Nix:

nix flake check --show-trace
nix build .#codex-server --print-build-logs

End-to-end smoke tests run the Nix-built package in Docker containers:

bun run smoke

By default this builds .#codex-server, then starts the package in ubuntu:24.04, debian:12, and alpine:3.20. Use CODEX_SERVER_SMOKE_IMAGES or scripts/smoke.sh --image <image> to adjust the matrix.

Releases

The package is published as @coder/codex-server. Release tags should match the package version, for example 26.519.41501, v26.519.41501, or v26.519.41501-2.

Publishing a GitHub release runs the release workflow. It checks the tag against package.json, installs dependencies, runs checks, builds the Nix package, runs the Docker smoke suite, packs the Nix-built npm package, publishes it to npm, and uploads the tarball to the release.

Questions?

Open a GitHub discussion or issue in coder/codex-server.

Want to help?

Run the checks above, keep changes scoped, and include the relevant smoke-test output when packaging behavior changes.

Security

Keep the default loopback listener unless you put a trusted tunnel, VPN, or authenticated reverse proxy in front. Anyone who can reach an authenticated session can operate Codex as the user running codex-server.

Maintenance

See AGENTS.md for the Codex Desktop version, CLI version, Nix hash, and release maintenance workflow.