codex-xremote

codex-xremote is a lightweight browser UI for Codex app-server workflows. It starts a local HTTP/WebSocket bridge, serves a Vue frontend, and lets you use Codex from a desktop browser, a mobile browser, a LAN device, or a remote development box.

The project is useful when Codex is running somewhere other than the device where you want to interact with it: a Linux workstation, a Windows machine, a VPS, or Termux on Android.

Quick Start

npx codex-xremote

Then open the local URL printed by the command, usually:

http://localhost:5999

codex-xremote checks for the Codex CLI and starts codex login when local Codex auth is missing.

Security Defaults

• Password protection is enabled by default.
• A random password is generated at startup and printed in the terminal.
• Use --password <value> to set your own password.
• Use --no-password only on a trusted local machine.
• --tunnel is enabled by default and starts cloudflared tunnel when available.
• Use --no-tunnel when you only want local or LAN access.

If you expose the server through a tunnel, reverse proxy, or public network, keep password protection enabled.

Commands

npx codex-xremote --port 5999
npx codex-xremote --no-tunnel
npx codex-xremote --password "change-me"
npx codex-xremote login
npx codex-xremote help

Platform Notes

Linux

node -v
npx codex-xremote

Node.js 18 or newer is required.

Windows

Run from PowerShell:

node -v
npx codex-xremote

The CLI resolves the Codex binary through the normal PATH and common npm install locations.

Termux on Android

pkg update && pkg upgrade -y
pkg install nodejs -y
npx codex-xremote

Keep Termux running while the server is active. For longer sessions, disable battery optimization for Termux and consider running termux-wake-lock.

Features

• Browser UI for Codex app-server workflows.
• HTTP/WebSocket bridge between the browser and Codex.
• Desktop and mobile layouts.
• Searchable project picker.
• Skills hub UI.
• Voice dictation into the composer when browser microphone permission is granted.
• Optional Cloudflare quick tunnel startup.
• Optional Android shell through Capacitor.

Screenshots

Skills Hub

Chat

Mobile UI

Architecture

Browser
  |
  | HTTP/WebSocket
  v
codex-xremote
  |
  | Codex app-server bridge
  v
Codex CLI / app-server runtime

The CLI serves the built frontend from dist/ and the Node bridge from dist-cli/.

Development

npm ci
npm run build
npm run test:smoke

Useful scripts:

npm run dev
npm run build:frontend
npm run build:cli
npm run changelog:update
npm run changelog:check

Release Checklist

Before publishing a release:

1. Run a full secret scan on the working tree and Git history.
2. Run npm audit --omit=dev.
3. Run npm ci.
4. Run npm run build.
5. Run npm pack --dry-run.
6. Create a GitHub release from a clean tag.
7. Publish to npm with npm publish --access public.

Status

This is an early public release. It is intended for developers already comfortable with Codex, local CLIs, tunnels, and browser-based development workflows.

License

MIT. See LICENSE.