Your Codex fleet, on iPhone. A self-hosted control plane for observing, controlling and continuing Codex sessions across multiple machines.

Quick Start · Documentation · Architecture · Current status

Why Codex Relay

• Know what is happening now: live Fleet rows stand out from Recent; execution state stays separate from current activity.
• Respond when needed: canonical decisions and clearly separate transient live questions.
• Continue work: send a Follow-up, then tap its Steer action to use it in the current turn; attach photos or screenshots with +.
• Trust the state: explicit Online, Syncing, Degraded and Offline; last-known work stays visibly stale.
• Understand your fleet: machines, runtime account usage, controllers and redacted diagnostics.
• Stay informed: native local alerts while connected; remote APNs with your Apple setup.
• Keep control: your Hub, your machines, local Codex login, no Relay cloud account.

Watch the short native walkthrough — actual simulator recording with sanitized example content.

Activity list · Changed files · Partial-height live question

How it works

The Hub owns Relay access and routing. Codex owns threads, conversation, running turns and the Follow-up queue. Agents use the existing local shared Codex daemon; Relay does not expose that daemon over the network. Conversation and outbox content are bounded and ephemeral, not a Relay transcript database.

Architecture · Protocol · Synchronization

Quick Start

You need an always-on Linux Hub host with HTTPS/WSS, a machine with an existing signed-in Codex runtime, and a Mac with Xcode to install the iPhone development build. Use the Go version in go.mod to build the current candidate.

1. Install the Hub

Choose an always-on Linux host as the coordinator. On that host, build the current candidate:

git clone https://github.com/mothx9/codex-relay.git
cd codex-relay
make build

Set RELAY_HUB_URL to your actual HTTPS origin and install the user service. HTTPS/proxy configuration remains yours; Relay does not configure your network.

./scripts/install.sh hub --binary ./bin/codex-relay \
  --public-url "$RELAY_HUB_URL"

Expected: the Hub service is running and reachable at your HTTPS origin. Follow the Hub guide for TLS, cross-builds, service lifetime and advanced installation.

2. Pair the iPhone

Build and install the native app through Xcode using your own signing team. On the Hub host, generate a one-time controller code:

~/.local/bin/codex-relay pair --hub-url "$RELAY_HUB_URL" \
  --data-dir "$HOME/.local/share/codex-relay/hub" --name iPhone

Enter the Hub URL and code in the app. The code expires in five minutes; the bootstrap/admin credential stays on the Hub host.

Expected: Fleet opens. Pairing walkthrough and screenshot.

3. Add a machine

On iPhone, open Relay menu → Machines → Add a machine to mint a one-time Agent code. On the Codex-running machine, install its matching candidate binary:

./scripts/install.sh agent --binary ./bin/codex-relay \
  --hub-url "$RELAY_HUB_URL" --machine workstation --pair

Enter the code at the prompt. The Agent connects outbound and progresses through Syncing to Online after a fresh Codex snapshot. Existing enrollment is never silently replaced. Linux guide · macOS guide.

Expected: the machine appears Online in Relay menu → Machines. Its local Codex login and work stay on that machine.

4. Run Codex normally

Keep using Codex on each enrolled machine. Fleet shows active work and requests; All Sessions provides on-demand historical navigation. A machine going offline does not mean its previous work completed.

5. Control it remotely

Open a session, answer a current request, or send a message. Ready sends a New Turn; Working queues a Follow-up. Steer and Interrupt stay separate advanced current-turn actions. Acknowledgement is not completion, and an uncertain outcome is never automatically resent.

Documentation and support

• Documentation index
• Upgrading and troubleshooting
• Controllers and recovery
• Account data and notifications
• Native development, testing, releases
• Contributing and changelog

Security and compatibility

Relay can control Codex with the local user's privileges. Use trusted HTTPS, protect controller/machine credentials, and read SECURITY.md. OpenAI authentication stays on the worker. Native notifications identify their source machine/session/turn; a privacy setting hides that metadata. Message and command contents are never included. Notification taps navigate and never approve work.

Current status and distribution

The native app is an Xcode development build. The project remains an explicit release candidate, with physical push acceptance outstanding. See the canonical current status and compatibility for validated Codex versions, iOS distribution, APNs requirements and the distinction between supported pending RPCs and transient async assistant questions. Pairing and ordinary control work without APNs. Public screenshots use sanitized production-view fixtures.

Native iOS 17+ supports English and Italian, semantic typography, Dynamic Type, Reduce Motion, and material fallback where Liquid Glass is unavailable. The embedded PWA remains a fallback/debug client.

License

Apache-2.0 for Relay source. Codex Relay is an independent project, not an official OpenAI application. The native Codex icon is attributed separately in product assets.