Language: English | 简体中文

npx @leibnizhu/codex-web-local

A lightweight web interface for Codex that replicates the desktop UI and runs on top of the Codex app-server. It exposes Codex through a web application, allowing you to access your local Codex instance remotely from any browser.

Prerequisites

• Codex CLI installed and available in your PATH

Installation

# Run directly with npx (no install required)
npx @leibnizhu/codex-web-local

# Or install globally
npm install -g @leibnizhu/codex-web-local

Usage

Usage: codex-web-local [options]

Web interface for Codex app-server

Options:
  -p, --port <port>    port to listen on (default: "3000")
  --host <host>        host to bind (e.g. 127.0.0.1 / 0.0.0.0 / 100.x.x.x)
  -d, --daemon         run in background (daemon mode)
  --password <pass>    set a specific password
  --no-password        disable password protection
  -V, --version        output the version number
  -h, --help           display help for command

Examples

Runtime Commands (production/daily usage)

# Start with auto-generated password on default port 3000
codex-web-local

# Start on a custom port
codex-web-local --port 8080

# Start with a specific password
codex-web-local --password my-secret

# Start without password protection (use only on trusted networks)
codex-web-local --no-password

# Start in daemon mode (run in background)
codex-web-local --daemon

# Start with an explicit bind host (listen on all interfaces)
codex-web-local --host 0.0.0.0

# Tailscale setup in daemon mode (background)
codex-web-local --host "$(tailscale ip -4)" --port 3000 --daemon

# Show current CLI version
codex-web-local --version

Dev Commands (Vite)

# Dev mode, expose to LAN
npm run dev -- --host 0.0.0.0

# Dev mode, bind to this machine's Tailscale IPv4
npm run dev -- --host "$(tailscale ip -4)"

# Dev mode in daemon (background)
npm run dev -- --host 0.0.0.0 --daemon

When started with password protection (default), the server prints the password to the console. Open the URL in your browser, enter the password, and you're in. The CLI also checks npm for new versions automatically at startup (at most once every 12 hours).

UI Highlights

• Composer status bar now shows:
  • current git branch
  • context window usage ring with detailed hover info
  • remaining quota hover card
• Context hover card supports manual compaction via "Compact Now" (calls thread/compact/start).
• Thread list uses name as the primary title. preview is shown in tooltip, not inline on hover.
• You can continue typing while the model is still responding. New sends are queued and auto-sent after the current turn finishes.

Daemon Notes

• codex-web-local --daemon runs the CLI server in background and prints PID.
• npm run dev -- --daemon runs the Vite dev server in background and prints PID.
• To stop a daemon process:

kill <PID>

Documentation

• Docs index: docs/README.md
• Contracts guide: docs/contracts/README.md
• Chinese app-server doc: docs/contracts/APP_SERVER_DOCUMENTATION.zh-CN.md

Contributing

Issues and pull requests are welcome! If you have ideas, suggestions, or found a bug, please open an issue on the GitHub repository.

License

MIT