codex-remote

codex-remote is a small monorepo for using Codex from a phone through a mobile-friendly web UI and a local gateway process.

It is aimed at two audiences:

• contributors who need to run and develop the repo locally
• end users who want to start a session on their machine and continue from a phone on the same network

Repo Layout

• apps/mobile-web: React 19 + TanStack Start mobile web UI
• apps/codex-gateway: Node HTTP gateway for auth, project discovery, session state, approvals, diffs, and terminal proxying
• packages/shared-types: shared TypeScript contracts used by both apps

Quick Start

Install dependencies:

npm install

Start the gateway:

npm run dev --workspace @codex-remote/gateway

Start the mobile web app:

npm run dev --workspace @codex-remote/mobile-web

Then open the frontend in a browser:

• local machine: http://127.0.0.1:3000
• phone on the same LAN: http://<your-machine-ip>:3000

The mobile app talks to the gateway after login. By default:

• mobile web runs on port 3000
• gateway runs on port 3101
• project discovery uses ~/Project unless CODEX_REMOTE_PROJECT_ROOT is set

Using It From Your Phone

1. Run both the gateway and the mobile web app on the machine where you use Codex.
2. Open http://<your-machine-ip>:3000 on your phone.
3. Enter the shared password generated by the gateway.
4. Pick a project under the configured project root.
5. Create a new session or resume an existing one.
6. Use the UI to send prompts, review diffs, respond to approvals, and open the terminal fallback when needed.

Notes:

• your phone must be able to reach the machine over the local network
• the gateway binds to 127.0.0.1 and detected private LAN IPv4 addresses by default
• the gateway creates the shared password automatically and stores it under .omx/state/; it also logs a password hint on startup

Development Commands

Repo-wide commands:

npm run build
npm run test
npm run lint

Workspace commands:

npm run dev --workspace @codex-remote/gateway
npm run dev --workspace @codex-remote/mobile-web
npm run preview --workspace @codex-remote/mobile-web
npm run test --workspace @codex-remote/gateway
npm run test --workspace @codex-remote/mobile-web

Environment Variables

The current codebase supports these main gateway settings:

• CODEX_REMOTE_PROJECT_ROOT: override the default project directory root
• CODEX_REMOTE_BIND_HOST: bind the gateway to a specific RFC1918 IPv4 address or 127.0.0.1
• CODEX_REMOTE_GATEWAY_PORT: override the gateway port, default 3101
• CODEX_REMOTE_APP_SERVER_PORT: override the internal Codex app server port, default 3210
• VITE_GATEWAY_URL: optional frontend override for the gateway origin
• VITE_GATEWAY_PORT: optional frontend default port override

Architecture

The runtime flow is straightforward:

1. apps/mobile-web renders the phone-friendly UI and sends HTTP requests to the gateway.
2. apps/codex-gateway authenticates requests, lists projects, creates or resumes sessions, streams events, and handles approvals and terminal traffic.
3. packages/shared-types keeps request and session contracts aligned between the frontend and gateway.

Current State

This repository currently has an app-level scaffold README under apps/mobile-web/README.md. The root README is intended to be the main entry point for understanding and running the full project.