Open Codex UI

A remote-friendly web workspace for continuing Codex sessions from desktop and mobile browsers.

[!IMPORTANT] Non-commercial use only. This project is provided solely for learning, research, personal use, and other non-commercial purposes. Commercial use requires prior written permission from the copyright holder.

Preview

Quick Start

Run the packaged application through Node.js:

npx open-codex-ui

The npm launcher reuses an existing uvx, or installs uv from Astral's official installer into its own cache. You can also run the Python package directly with uv:

uvx open-codex-ui

Open http://127.0.0.1:13140. The wheel already contains the compiled frontend. To accept connections from other devices, bind explicitly to the network:

uvx open-codex-ui serve --host 0.0.0.0 --port 13140

Codex WebSocket subscriptions use turn, item, and streaming-text deltas, latest-state coalescing, and negotiated gzip binary frames for larger messages. Clients that do not request gzip continue to receive regular JSON frames.

Background Service

Install the command persistently and register login startup:

npx open-codex-ui daemon install
# or
uvx open-codex-ui daemon install

This installs open-codex-ui into uv's user bin directory and uses the native service manager for the current platform:

After opening a new shell, manage the service directly:

open-codex-ui daemon status
open-codex-ui daemon stop
open-codex-ui daemon start
open-codex-ui daemon uninstall

The service starts when the user logs in. Runtime state, retained environment, and logs live under ~/.yier/web/. Run daemon install again to update its host, port, or captured environment; use update for application versions.

Cloudflare Tunnel

Start Open Codex UI first, then expose the default local address with an ephemeral Quick Tunnel:

open-codex-ui tunnel start
open-codex-ui tunnel status
open-codex-ui tunnel stop

For a tunnel already configured in the Cloudflare dashboard, provide an API token that can read the account's tunnel configuration and connector token:

export CF_TOKEN='your-cloudflare-api-token'
open-codex-ui tunnel start --mode managed-remote --name my-tunnel

The named-tunnel flow discovers its public hostname and local origin from Cloudflare. Set CF_ACCOUNT_ID or pass --account-id when account discovery is unavailable. You can bypass the API with an existing connector token file:

open-codex-ui tunnel start --mode managed-remote \
  --token-file ~/.cloudflared/my-tunnel.token \
  --hostname codex.example.com

Locally managed cloudflared configurations are also supported:

open-codex-ui tunnel start --mode managed-local
open-codex-ui tunnel start --mode managed-local --config ~/.cloudflared/config.yml

Tunnel state and logs are stored under ~/.yier/web/. API and connector tokens are never persisted there or included in the cloudflared command line. Tunnel processes are independent from the login service, and tunnel stop only stops the cloudflared process started by Open Codex UI.

[!WARNING] A tunnel exposes Open Codex UI to the public Internet. Configure application authentication or Cloudflare Access before sharing the public URL.

Updating

Update a persistent installation to the latest stable release:

open-codex-ui update
# or
npx open-codex-ui update

If the login service is running, it is restarted after the update. Plain uvx and npx runs resolve their release when launched, so the command makes no persistent changes when no uv tool installation exists.

Authentication

Authentication is disabled unless a password variable is configured:

export YIER_AUTH_PASSWORD='change-this-password'
uvx open-codex-ui daemon install --host 0.0.0.0

For a hashed password:

uv run --with open-codex-ui python -c "from yier_web.auth import hash_password; print(hash_password('change-this-password'))"
export YIER_AUTH_PASSWORD_HASH='paste-generated-hash-here'

daemon install retains HOME, PATH, CODEX_HOME, and current YIER_* variables in a user-only environment file so they remain available after login.

Voice Input

The Codex composer can stream microphone audio to a local sherpa-onnx transducer model. The default model directory is ~/.yier/models/sherpa-onnx. A bilingual Chinese-English streaming Zipformer can be installed with:

open-codex-ui speech install

The installer supports interrupted-download resumption, verifies the archive, extracts it safely, and atomically activates the model. Standard HTTPS_PROXY and ALL_PROXY environment variables are honored:

HTTPS_PROXY=http://127.0.0.1:7890 open-codex-ui speech install
open-codex-ui speech status
open-codex-ui speech install --force
open-codex-ui speech remove

The model is stored outside the Python environment, so it remains available after uv tool upgrades or reinstalls. The directory must contain tokens.txt, encoder*.onnx, decoder*.onnx, and joiner*.onnx.

Override the runtime configuration when needed:

Remote mobile browsers require HTTPS for microphone permission. Localhost is also treated as a secure context by modern browsers.

Development

Source development requires Python 3.12+, Node.js 20+, uv, and pnpm:

uv sync
pnpm --dir web install

Start the frontend and backend in separate terminals:

pnpm --dir web dev
uv run python main.py --debug --reload --host 127.0.0.1 --port 13140

The application remains at http://127.0.0.1:13140; the backend proxies frontend traffic to the Vite server on port 5173.

To test the production build from source:

pnpm --dir web build
uv run open-codex-ui

Codex integration is provided by the published open-codex-bridge package.

Iframe Embedding

See IFRAME.md for iframe authentication, setup, and the postMessage API.

License

Copyright 2026 Sube (zhangluguang). Licensed under the PolyForm Noncommercial License 1.0.0. Commercial use is not permitted without separate written authorization from the copyright holder.