codex-relay

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.
• Choose separate turn-complete and action-required push notifications.
• 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.

3. Optional: share a live session with your terminal

The default relay uses its own Codex app-server process. To make mobile and a terminal TUI use the same shared app-server, start the relay with:

npx codex-relay@latest --shared-app-server

When a shared app-server is already running, the relay attaches to it instead of starting another one. If the relay’s own socket connection resets, it reconnects without deliberately stopping the shared app-server.

Then attach a new terminal TUI. On macOS, Linux, or WSL:

codex resume --remote unix://

On native Windows:

codex resume --remote ws://127.0.0.1:8788

An already-running standalone TUI cannot be converted in place. Exit it and reconnect with --remote. Shared mode requires a recent Codex CLI with app-server and remote-resume support. It uses a Unix socket on macOS, Linux, and WSL, or a loopback-only WebSocket on Windows.

Shared mode uses Codex’s experimental app-server transport. A directly connected terminal TUI has its own WebSocket connection, which the relay cannot observe or reconnect. If that terminal reports a socket reset while the thread continues on mobile, reconnect it with the matching remote endpoint above and append the thread ID if needed.

Push notifications

After pairing, open Settings > Notifications in the mobile app and enable either or both alerts:

• Turn complete for completed or failed Codex turns
• Remaining usage to include the lowest remaining Codex limit in turn-complete alerts
• Action required for approval and input requests

The relay uses the thread title as the notification title so you can identify the conversation. When Remaining usage is enabled, a turn-complete alert also includes the most constrained percentage reported by Codex. It does not send prompts, responses, commands, or approval text through the push service. Push support requires a native mobile build that includes expo-notifications; an OTA update alone cannot add that native module.

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.

Changes to the published codex-relay package should include a changeset:

pnpm changeset

Commit the generated file with the change. The release workflow maintains a release pull request and publishes it after that pull request is merged. See the Changesets guide for the release process.

Common Commands

Configuration

The relay listens on 0.0.0.0:8787 by default.

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.