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
  -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

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.

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