Remodex: A local-first bridge for driving Codex from an iPhone

What Remodex actually solves

Remodex targets a specific gap: Codex runs as a CLI on a Mac, and the official mobile story is thin. You can SSH into the Mac, but that is awkward on a phone. Remodex gives you a SwiftUI iOS app that talks to a Node.js bridge on the Mac, which in turn talks to the codex app-server over stdin/stdout. The selling point is local-first: the Codex runtime, the session state, and the git operations all stay on your Mac. The phone is a remote control, not a remote compute node. The intended user is a developer who wants to queue prompts, run git commit and push, or switch branches from a couch or a commute, without carrying a laptop. The README is explicit that the project is very early and expects bugs, so this is for the tolerant tinkerer, not the enterprise team.

The bridge architecture: WebSocket, JSON-RPC, and a QR handshake

The architecture diagram in the README shows three components. The iOS app connects to the Mac bridge over a WebSocket, and the bridge connects to codex app-server over stdin/stdout using JSON-RPC. The bridge also reads the local Codex IPC bus for live state and writes JSONL rollout history. The pairing flow is a one-time QR bootstrap. You run remodex up on the Mac, it prints a QR, and you scan it with the iOS app. After that handshake, the iPhone trusts that Mac and can reconnect automatically through a configured relay. The bridge keeps its identity locally on the Mac. The transport layer is meant to be inspectable, and the repo does not embed a public hosted endpoint in the iOS app source. That is a deliberate design choice for self-hosting, though it means you must understand the relay configuration yourself. The README warns that if you scan the QR with a generic camera app, the payload may be treated as plain text and open a web search instead of pairing, so the app must be installed first.

Installation and the macOS launchd path

The bridge installs from npm. The README says to use npm install -g remodex@latest to get the newest fixes, and to run remodex restart after updating if the macOS background service is installed. The quick start is remodex up on the Mac, which installs and starts a lightweight background bridge service on macOS and prints a QR. The iOS app is built from source in Xcode 16+; you need a signed build on your device. The prerequisites are Node.js v18+, Codex CLI installed and in PATH, and Codex CLI authenticated on the Mac. The bridge does not manage OpenAI credentials. It expects codex login status to succeed. If you get the error Missing environment variable: CODEX_API_KEY, the README says that error comes from your Codex CLI configuration, not from Remodex, and the recovery is codex login then remodex restart. For API-key auth, you configure Codex itself, for example printenv OPENAI_API_KEY | codex login --with-api-key. The README explicitly warns not to put live OpenAI API keys into the Remodex launchd plist or relay configuration.

What the app can do from your phone

The feature list in the README is concrete. You get end-to-end encrypted pairing and chats, fast mode for lower-latency turns, plan mode for structured planning, subagents via the /subagents command, the ability to steer active runs without restarting, and queueing follow-up prompts while a turn is running. There are in-app notifications when turns finish or need attention. Git actions from the phone include commit, push, pull, and branch switching. Reasoning controls tune how much thinking Codex uses. Photo attachments come from the camera or library. Access controls offer On-Request or Full access. Live streaming shows output on the phone while Codex runs on the Mac. Shared thread history with Codex on the Mac means you can see the same conversation in the desktop app or VSCode. The bridge handles git operations and local session persistence on the Mac. When the local Codex IPC bus is available, Remodex broadcasts live conversation state to Codex Desktop or VSCode, with persisted JSONL history and the optional refresh workaround as fallbacks. These are real capabilities, not marketing fluff.

Limitations: macOS-only daemon, relay dependency, and early-stage bugs

The README is honest about limits. The background daemon and trusted auto-reconnect flow are implemented only for macOS. On Linux or Windows, self-hosted relay setups still work, but the bridge runs in the foreground, so you lose the launchd service and automatic reconnect. The README also says the project is very early and expects bugs. Another constraint is that the iOS app source does not embed a public hosted endpoint, so you must set up your own relay or use the default one, which is not described in detail in the provided material. The pairing depends on scanning a QR from inside the app; a generic scanner breaks the flow. The bridge expects Codex CLI to be authenticated, and the error handling around CODEX_API_KEY is delegated to Codex, not Remodex. If you are on a non-macOS machine and need a persistent background service, this is the wrong tool today. Also, the repo is not accepting contributions yet, so you cannot easily fix bugs upstream.

Alternatives and the difference in approach

The obvious alternative is to use SSH from a phone, with a terminal app like Termius or Blink. That approach gives you full shell access to the Mac, including the Codex CLI, but it is not Codex-aware: you get raw terminal output, no structured live streaming, no git command shortcuts, and no push notifications. Remodex wraps the Codex runtime with a JSON-RPC protocol and a SwiftUI client, so you get features like plan mode, subagents, and thread history that a plain SSH session cannot offer without extra scripting. Another alternative is the Codex desktop app itself, but that runs on the Mac, not on your phone. The difference is that Remodex is a purpose-built mobile client, while SSH is a general-purpose remote shell. If you only need occasional remote control and are comfortable with the terminal, SSH is simpler and has no extra bridge to maintain. If you want a tailored Codex experience, Remodex is the only open-source option described here.

Maintenance, licensing, and upgrade cost

The project is Apache-2.0 licensed, which is permissive for commercial use, but the README says the author is not actively accepting contributions yet. That means you cannot rely on community fixes. Upgrades come from npm: you run npm install -g remodex@latest, then remodex restart to refresh the saved Node and CLI paths and the LaunchAgent policy. The README says this does not replace your pairing state, which is a good sign for upgrade cost. However, the iOS app must be built and signed by you unless you use the App Store version, which is listed. The App Store version may lag behind the source, but the README does not specify. The bridge depends on the Codex CLI version, so when Codex changes its IPC or JSON-RPC, Remodex may break and require an update. There is no mention of automated tests beyond the repository structure listing tests, but no details are given. The maintenance burden is on you: you must keep Node.js, Codex CLI, and the bridge in sync, and you must understand the relay configuration if you self-host. The license allows modification, which is helpful if you need to fix a bug yourself.

Editorial conclusion

Adopt Remodex if you are a macOS user who already has Codex CLI authenticated and wants a self-hosted, inspectable way to steer coding sessions from an iPhone. Do not adopt it if you need a production-grade tool, if you are on Linux or Windows and expect the background service, or if you cannot tolerate early bugs. Before relying on it, verify that your Codex CLI login works, that you can build and sign the iOS app yourself, and that your relay setup supports trusted reconnect; otherwise you will be stuck with the foreground bridge and manual QR pairing.

Official sources

1. Official documentation
2. Official README
3. Project repository