codexui-server-bridge

OpenAI Codex web UI and browser bridge for Windows, Linux, Android, Termux, and Windows Server

Browser-accessible OpenAI Codex UI with the simplest deploy path: give Codex this repo URL and one prompt.

This fork exposes Codex app-server through a stable web UI for Windows desktops, Windows Server, Linux hosts, Android browsers, and remote development boxes.

This fork focuses on Windows server deployment, LAN access, stable browser entry points, and config-driven self-hosting.

• English README: README.md
• 中文说明: README.zh-CN.md
• Codex deploy prompt: docs/deploy-with-codex.en.md
• 中文部署提示词: docs/deploy-with-codex.zh-CN.md

Fastest Deploy

Use this if Codex already has terminal access on the target machine.

1. Open Codex on the target machine.
2. Tell it to inspect this repository:

https://github.com/Qjzn/codexui-server-bridge

3. Paste this prompt:

Open and inspect https://github.com/Qjzn/codexui-server-bridge.
Deploy this project on this machine using the simplest supported path.

Requirements:
- create a stable Codex web UI service on port 7420
- prefer the repo's built-in bootstrap or setup scripts when possible
- preserve existing Codex login if it is already configured
- enable local browser access and LAN access when possible
- configure auto-start if the machine allows it
- when finished, print the local URL, LAN URL, password, and restart command

Do the work directly instead of only describing the steps.

If you want the Chinese version of the same prompt, use docs/deploy-with-codex.zh-CN.md.

What This Repo Gives You

• OpenAI Codex in a browser
• a stable 7420 entry point on Windows or Windows Server
• LAN and phone access without building your own bridge
• health checks and config-driven startup
• local file browse and edit endpoints from Codex replies
• desktop-app refresh support for mixed web and Windows desktop workflows

Manual Install

If you want to install it yourself on Windows, run:

Set-ExecutionPolicy Bypass -Scope Process -Force; irm https://raw.githubusercontent.com/Qjzn/codexui-server-bridge/main/scripts/bootstrap-windows.ps1 | iex

Prefer a ZIP release?

If you would rather download a bundle instead of using the one-liner, use the latest asset from Releases and then run:

.\setup.ps1

Need custom port or password?

If you want to customize the default port or password, use the scriptblock form:

& ([scriptblock]::Create((irm 'https://raw.githubusercontent.com/Qjzn/codexui-server-bridge/main/scripts/bootstrap-windows.ps1'))) `
  -Port 7420 `
  -Password 'change-me'

⚡ Quick Start

npx codexapp

Then open:

http://localhost:18923

Linux 🐧

node -v   # should be 18+
npx codexapp

Windows 🪟 (PowerShell)

node -v   # 18+
npx codexapp

You can also pin the bind address and skip the default tunnel:

npx codexapp --host 0.0.0.0 --port 7420 --no-tunnel --password "change-me"

Termux (Android) 🤖

pkg update && pkg upgrade -y
pkg install nodejs -y
npx codexapp

Android background requirements:

1. Keep codexapp running in the current Termux session (do not close it).
2. In Android settings, disable battery optimization for Termux.
3. Keep the persistent Termux notification enabled so Android is less likely to kill it.
4. Optional but recommended in Termux:

termux-wake-lock

5. Open the shown URL in your Android browser. If the app is killed, return to Termux and run npx codexapp again.

---

⚙️ Config File Support

codexapp can now load launch options from JSON so Windows servers and long-running setups do not need hard-coded batch files.

Search order:

1. --config <path>
2. CODEXUI_CONFIG
3. ./codexui.config.json
4. ~/.codexui/config.json

Example:

{
  "host": "0.0.0.0",
  "port": 7420,
  "password": "replace-with-your-password",
  "tunnel": false,
  "open": false,
  "projectPath": "C:\\Users\\your-user\\Documents\\Playground"
}

Tracked example file:

• codexui.config.example.json

---

🪟 Windows Server Install

For source-based Windows deployments, the repo now includes a helper script that installs dependencies, builds the project, writes a stable config file, creates a launcher, and can optionally open the firewall port:

powershell -ExecutionPolicy Bypass -File .\scripts\install-windows-server.ps1 `
  -ProjectPath "C:\Users\SW\Documents\Playground" `
  -Port 7420 `
  -Password "change-me" `
  -OpenFirewall `
  -StartNow

More details:

• docs/windows-server.md
• RELEASE.md

The installer defaults to server-friendly settings:

• tunnel disabled
• browser auto-open disabled

Health endpoints:

• GET /health
• GET /codex-api/health

---

iPhone / iPad via Tailscale Serve

If you want to use codexUI from iPhone or iPad Safari, serving it over HTTPS is recommended.

A practical private setup is to run codexUI locally and publish it inside your tailnet with Tailscale Serve:

npx codexapp --no-tunnel --port 5999
tailscale serve --bg 5999

Then open:

https://<your-machine>.<your-tailnet>.ts.net

This setup worked well in practice for:

• iPhone Safari access
• Add to Home Screen
• the built-in dictation / transcription feature in the app
• viewing the same projects and conversations from the Windows host

Notes:

• Tailscale Serve keeps access private to your tailnet
• on iOS, HTTPS / secure context appears to be important for mobile browser access and dictation
• some minor mobile Safari CSS issues may still exist, but they do not prevent normal use
• depending on proxying details, authentication behavior may differ from direct remote access
• if conversations created in the web UI do not immediately appear in the Windows app, restarting the Windows app may refresh them

---

✨ Features

• 🚀 One-command launch with npx codexapp
• 🌍 Cross-platform support for Linux, Windows, and Termux on Android
• 🖥️ Browser-first Codex UI flow on http://localhost:18923
• 🌐 LAN-friendly access from other devices on the same network
• 🧪 Remote/headless-friendly setup for server-based Codex usage
• 🔌 Works with reverse proxies and tunneling setups
• ⚡ No global install required for quick experimentation
• ⚙️ Config-driven startup with --config and default config discovery
• ❤️ Lightweight health endpoints for process managers and reverse proxies
• 🎙️ Built-in hold-to-dictate voice input with transcription to composer draft
• 🤖 Optional Telegram bot bridge: send messages to bot, forward into mapped thread, send assistant reply back to Telegram

Telegram Bot Bridge (Optional)

Set these environment variables before starting codexapp:

export TELEGRAM_BOT_TOKEN="<your-telegram-bot-token>"
export TELEGRAM_DEFAULT_CWD="$PWD" # optional, defaults to current working directory
npx codexapp

Bot commands:

• /newthread create and map a new Codex thread for this Telegram chat
• /thread <threadId> map current Telegram chat to an existing thread
• Any other text message is forwarded to the mapped thread

---

🧩 Recent Product Features (from main commits)

Not just launch. Actual UX upgrades.

• ⬇️ Conversation view no longer yanks you to the bottom while you are reading history; auto-follow now resumes only when you are already at the latest output
• 🛟 Floating "back to latest output" button appears when you scroll up, with a visual cue when fresh output arrives below the fold
• ⏳ Thread loading is less disruptive: existing messages stay visible and a lightweight inline sync bar replaces the old blocking-only loading state
• 🔄 Thread status tracking is more robust during long-running tasks, with background reconciliation to reduce false "completed" states in the sidebar
• 📡 Notification transport is more resilient now, with client-side reconnect handling and server-side WebSocket heartbeats to recover from stale streams
• 🔗 Web messages now handle local Windows file links and common external hyperlink formats more reliably from the browser UI
• ⚠️ Refreshing the official desktop app now warns when the current thread still looks busy, to reduce accidental task interruption
• 🗂️ Searchable project picker in new-thread flow
• ➕ Inline "Add new project" input inside picker (no browser prompt)
• 📌 New projects get pinned to top automatically
• 🧠 Smart default new-project name suggestion via server-side free-directory scan (New Project (N))
• 🔄 Project order persisted globally to workspace roots state
• 🧵 Optimistic in-progress threads preserved during refresh/poll cycles
• 📱 Mobile drawer sidebar in desktop layout (teleported overlay + swipe-friendly structure)
• 🎛️ Skills Hub mobile-friendly spacing/toolbar layout improvements
• 🪟 Skill detail modal tuned for mobile sheet-style behavior
• 🧪 Skills Hub event typing fix for SkillCard select emit compatibility
• 🎙️ Voice dictation flow in composer (hold to dictate -> transcribe -> append text)

---

🌍 What Can You Do With This?

🔥 Use Case	💥 What You Get
💻 Linux workstation	Run Codex UI in browser without depending on desktop shell
🪟 Windows machine	Launch web UI and access from Chrome/Edge quickly
📱 Termux on Android	Start service in Termux and control from mobile browser
🧪 Remote dev box	Keep Codex process on server, view UI from client device
🌐 LAN sharing	Open UI from another device on same network
🧰 Headless workflows	Keep terminal + browser split for productivity
🔌 Custom routing	Put behind reverse proxy/tunnel if needed
⚡ Fast experiments	npx run without full global setup

---

🖼️ Screenshots

Skills Hub

Chat

Mobile UI

---

🏗️ Architecture

┌─────────────────────────────┐
│  Browser (Desktop/Mobile)   │
└──────────────┬──────────────┘
               │ HTTP/WebSocket
┌──────────────▼──────────────┐
│         codexapp            │
│  (Express + Vue UI bridge)  │
└──────────────┬──────────────┘
               │ RPC/Bridge calls
┌──────────────▼──────────────┐
│      Codex App Server       │
└─────────────────────────────┘

---

🎯 Requirements

• ✅ Node.js 18+
• ✅ Codex app-server environment available
• ✅ Browser access to host/port
• ✅ Microphone permission (only for voice dictation)

---

🐛 Troubleshooting

❌ Problem	✅ Fix
Port already in use	Run on a free port or stop old process
npx fails	Update npm/node, then retry
Termux install fails	pkg update && pkg upgrade then reinstall nodejs
Build from source fails on Windows	Run npm install then npm run build; build no longer requires pnpm
Can’t open from other device	Check firewall, bind address, and LAN routing

---

🤝 Contributing

Issues and PRs are welcome.
Bring bug reports, platform notes, and setup improvements.

---

⭐ Star This Repo

If you believe Codex UI should be accessible from any machine, any OS, any screen, star this project and share it. ⭐

Built for speed, portability, and a little bit of chaos 😏

---

Fork lineage: pavel-voronin/codex-web-local -> friuns2/codexui -> Qjzn/codexui-server-bridge.