codex-relay: driving a Codex CLI session from your phone

A relay on your machine, an app on your phone

The premise is one sentence: use Codex from your phone while the real work stays on your computer. The mechanics follow from that. 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. What it does is listed as streaming Codex output from a local workspace to a paired mobile app, sending prompts and continuing threads and responding when Codex needs input, reviewing active threads and queued inputs and approvals and workspace state, and previewing git changes, local web output, files and terminal surfaces from mobile. Push notifications can be configured separately for a completed turn and for an action required, and pairing and session data stay under the local relay state. The project is explicit that it is an independent project, not affiliated with, endorsed by, or sponsored by OpenAI or the OpenAI Codex team, and it is deliberately local-first: your code, shell, git state and Codex CLI session stay on your computer, and the phone talks to the relay that you run.

Starting the relay and pairing by QR code

The requirements are short: Node.js 22.14 or newer, the Codex CLI installed and signed in, Codex Relay on your phone, and a network path from your phone to your computer. The first step is to 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. You then open the mobile app and scan the QR code, or, if scanning is not available, paste the full pairing link into the app. Pairing is not complete on the phone alone. When the app shows an approval code, you approve it from your computer:

npx codex-relay@latest approve XXXX-XXXX

That second step is the security model in miniature. The phone cannot connect to your machine until a human at the keyboard approves a code that the app displays, which is a sensible defence against a stray QR code being photographed. The project publishes to npm as codex-relay and the mobile app is distributed through the App Store.

Shared app-server mode and its constraints

By default the relay runs its own Codex app-server process. If you want the mobile app and a terminal TUI to drive the same session, you 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, and if the relay's own socket connection resets it reconnects without deliberately stopping the shared app-server. You then attach a new terminal TUI, and the command differs by platform. On macOS, Linux or WSL it is a Unix socket:

codex resume --remote unix://

On native Windows the relay uses a loopback-only WebSocket on port 8788. An already-running standalone TUI cannot be converted in place, so you exit it and reconnect with --remote. The constraints are stated just as plainly. Shared mode requires a recent Codex CLI with app-server and remote-resume support, and it uses Codex's experimental app-server transport. A directly connected terminal TUI has its own WebSocket connection which the relay cannot observe or reconnect, so if that terminal reports a socket reset while the thread continues on mobile, you reconnect it with the matching remote endpoint and append the thread ID if needed.

Network reachability is two separate problems

Your phone must be able to open the Mobile: URL printed by Codex Relay. The same Wi-Fi usually works, and Tailscale is described as a good default when the devices are on different networks. But 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, which is a second path to open. The recommended fix is Tailscale Serve, which exposes a preview port over HTTPS so the iOS WebView loads it properly:

tailscale serve 3000

Tailscale then prints an https://<machine>.<tailnet>.ts.net URL, and you open that HTTPS URL in the mobile Web preview instead of the plain http://100.x.y.z:3000 address. The symptom of getting this wrong is named too: if the Web preview says App Transport Security requires a secure connection, the app is trying to load a plain HTTP URL. The mobile Web preview also detects http://100.x.y.z:<port> and http://<machine>.<tailnet>.ts.net:<port> URLs, and when it detects them you can 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.

Push notifications, and what they do not carry

After pairing, you open Settings > Notifications in the mobile app and enable either or both alerts. Turn complete fires for completed or failed Codex turns, Remaining usage includes the lowest remaining Codex limit in turn-complete alerts, and Action required fires for approval and input requests. Two design details are worth knowing. The relay uses the thread title as the notification title so you can identify the conversation, and when Remaining usage is enabled a turn-complete alert also includes the most constrained percentage reported by Codex. The privacy boundary is stated in the negative: the relay does not send prompts, responses, commands or approval text through the push service. So a push tells you that something needs attention, and the content stays behind the relay. There is one build constraint. Push support requires a native mobile build that includes expo-notifications, and an OTA update alone cannot add that native module, so push is a decision you make when a build is cut rather than something you can toggle on later.

How the codebase is put together

The repository is a pnpm workspace with a monorepo layout. The root package is codex-relay-workspace, marked private, and the scripts show the structure: dev:mobile filters to a package named @codex-relay/mobile, dev:server filters to codex-relay, and there are separate android and ios targets for the mobile app. The apps, packages, deployments, docs and scripts directories sit at the top level, alongside a.changeset directory and a pnpm-workspace.yaml. Two entries in the tree are unusual and informative. DESIGN.md suggests there is an architecture document for the project rather than a purely emergent structure, and hermes-v1-async-await-root-cause.md is a written post-mortem about a specific async/await problem, which is a good sign about how the project records its own problems. The release process uses changesets, with version-packages:npm and version-packages:mobile scripts that version the npm and mobile packages separately, and a release script that runs changeset publish. There is also a TRADEMARKS.md at the root, and a test:live:mobile-stream script that runs the live mobile stream contract test against a real app server behind an environment flag.

What the project does not claim

The boundaries are set by the local-first claim and by the app's own scope. It is a companion for the Codex CLI, not a replacement for it, and it does not run Codex in the cloud. The phone is a second surface onto a session that lives on your computer, and anything the relay does not expose stays unreachable from the phone, which is the point but also the limit: git changes, local web output, files and terminal surfaces are previewable, but the project does not describe arbitrary shell access from the phone. The version history reflects a young project with a single recorded release, [email protected] on 2026-07-18, and the last push to the repository was on 2026-10-20. The licence is Apache-2.0, declared in the root manifest and covered by a LICENSE file, and the package requires Node.js 22.14 or newer. For anyone considering adoption, the honest first step is to check that their Codex CLI is recent enough for the shared mode they want, since without that feature the project still works but only in its own-app-server configuration.

Editorial conclusion

codex-relay suits a developer who runs long Codex CLI sessions and wants to read output, answer approval prompts and queue input from a phone while the work continues on the workstation, and the local-first design means the relay is the only thing that has to be reachable. It is the wrong tool if you need the phone to reach anything beyond the relay, since a local web preview needs its port exposed separately, and it is the wrong tool for a shared app-server session where the terminal TUI and the phone must see the same socket, because that path depends on Codex's experimental app-server transport. Verify first that your Codex CLI has app-server and remote-resume support before planning to share a session, then check the network path, since the same Wi-Fi usually works and Tailscale is the recommended default for different networks.

Frequently asked questions

Official sources

1. gronxb/codex-relay on GitHub
2. Issues
3. License: Apache-2.0
4. README
5. Releases