Codex Relay

Use Codex from your phone while the real work stays on your computer.

Codex Relay is a mobile companion for the Codex CLI. It runs a local relay server in your workspace, pairs with the mobile app over your own network, and lets you follow or steer Codex sessions from your phone.

Codex Relay is an independent project. It is not affiliated with, endorsed by, or sponsored by OpenAI or the OpenAI Codex team.

The project is intentionally local-first. Your code, shell, git state, and Codex CLI session stay on your computer; the phone talks to the relay that you run.

What It Does

• Stream Codex output from a local workspace to a paired mobile app.
• Send prompts, continue threads, and respond when Codex needs input.
• Review active threads, queued inputs, approvals, and workspace state.
• Preview git changes, local web output, files, and terminal surfaces from mobile.
• Keep pairing and session data under your local relay state.

Quick Start

Requirements

• Node.js 22.14 or newer
• Codex CLI installed and signed in
• Codex Relay on your phone
• A network path from your phone to your computer

1. Start the relay

From the workspace where you want Codex to work:

npx codex-relay@latest

The relay prints a QR code, a mobile URL, and a codex-relay://pair... pairing link.

2. Pair the app

Open the mobile app and scan the QR code printed by the relay. If scanning is not available, paste the full codex-relay://pair... link into the app.

When the app shows an approval code, approve it from your computer:

npx codex-relay@latest approve XXXX-XXXX

Your phone can now talk to your local Codex session.

Network Setup

Your phone must be able to open the Mobile: URL printed by Codex Relay.

• Same Wi-Fi usually works.
• Tailscale is a good default when the devices are on different networks.

Tailscale and Web Previews

Pairing only makes the Codex Relay server reachable. If you open a local web app from the mobile Web preview, that app's port must also be reachable from the phone.

When using Tailscale, prefer Tailscale Serve for preview ports so the iOS WebView loads the site over HTTPS. For example, if your local app runs on http://127.0.0.1:3000:

tailscale serve 3000

Tailscale prints an https://<machine>.<tailnet>.ts.net URL. Open that HTTPS URL in the mobile Web preview instead of http://100.x.y.z:3000. If the Web preview says App Transport Security requires a secure connection, the app is trying to load a plain HTTP URL; expose that same port with tailscale serve or another HTTPS tunnel and retry.

The mobile Web preview also detects http://100.x.y.z:<port> and http://<machine>.<tailnet>.ts.net:<port> URLs. When detected, tap Serve in the Tailscale row to run Tailscale Serve for that port from the relay machine and switch the preview to the returned HTTPS URL automatically.

Contributing

Please use English as the default language for GitHub issues, pull requests, and maintainer-facing discussions. If English is difficult, start with a short English summary and then include the rest in the language you are most comfortable using.

Before opening a connection issue, confirm the network checklist in the issue template. Most pairing failures happen because the phone cannot reach the relay URL printed by the computer.

Common Commands

Command	What it does
npx codex-relay@latest	Start the relay and print a pairing QR.
npx codex-relay@latest --bg	Keep the relay running in the background.
npx codex-relay@latest qr	Print the current pairing QR for an existing relay.
npx codex-relay@latest approve XXXX-XXXX	Approve a pending mobile pairing request.
npx codex-relay@latest clear	Sign out every paired mobile app.

Configuration

The relay listens on 0.0.0.0:8787 by default.

Variable	Purpose
PORT	Server port. Defaults to 8787.
HOST	Listen host. Defaults to 0.0.0.0.
CODEX_RELAY_WORKSPACE_PATH	Workspace path Codex should use. Defaults to the current directory.
CODEX_RELAY_AUTH_DB_PATH	Pairing and session database path.
CODEX_BIN	Codex CLI executable path.
CODEX_HOME	Codex home directory for reading local session metadata.

Background mode writes runtime files under .codex-relay/ in the current workspace, including server logs, process state, and pairing data.

Troubleshooting

If qr cannot find a server, start one first:

npx codex-relay@latest

If another process is using the local pairing database, use the existing server:

npx codex-relay@latest qr

If the mobile app cannot connect, confirm that the phone can reach the printed Mobile: URL and that your firewall allows traffic on the relay port.

Connection checklist:

• Are the phone and computer on the same Wi-Fi or LAN?
• If keeping the same network is difficult, are both devices connected through Tailscale or another reachable private network?
• Can the phone open the exact Mobile: URL printed by the relay?
• Does the computer firewall allow inbound traffic on the relay port, usually 8787?

License

Codex Relay is licensed under the Apache License 2.0. See LICENSE.

The Codex Relay name, logos, app icons, screenshots, and other brand assets are not licensed under Apache-2.0. See TRADEMARKS.md.