open-codex-ui 0.1.7

Remote-friendly web workspace for Codex sessions

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

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:

Platform	Service
macOS	LaunchAgent in ~/Library/LaunchAgents
Linux	systemd --user service
Windows	Current-user Task Scheduler task

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.

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'

Variable	Purpose
YIER_AUTH_PASSWORD	Plain login password
YIER_AUTH_PASSWORD_HASH	Hashed login password
YIER_AUTH_SECRET	Additional session-cookie signing secret
YIER_AUTH_SESSION_TTL_HOURS	Session lifetime; defaults to 168 hours
YIER_CODEX_EMBED_TOKEN	Token for unauthenticated iframe access

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

Development

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

uv sync
pnpm --dir web install
uv run dev

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

Command	Purpose
uv run dev	Start frontend and backend with reload
uv run dev-web	Start Vite only
uv run dev-backend	Start the backend only
uv run publish	Type-check and build frontend assets into yier_web/static
uv run open-codex-ui	Run the source checkout in production mode
uv run pytest	Run backend tests
uv run python -m compileall yier_web	Check Python compilation
pnpm --dir web test:unit	Run frontend unit tests
pnpm --dir web type-check	Run frontend type checking

To test the production build from source:

uv run publish
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.