Codex Relay

Use Codex on your Linux machine from the ChatGPT mobile app.

Codex Relay runs the official Codex remote-control host as a resilient Linux user service. It lets the Remote view in the ChatGPT Android or iOS app start and continue Codex chats on this machine, send prompts, review diffs and terminal output, and approve actions.

The relay uses Codex's outbound connection to OpenAI's managed relay. It does not open an inbound port, implement a private protocol, or copy ChatGPT credentials into this project.

Why this exists

OpenAI's desktop application provides a convenient always-on Remote host on macOS and Windows. Current Codex CLI releases also contain an experimental remote-control host, but Linux does not have the desktop application to supervise it. Codex Relay supplies that missing lifecycle layer with systemd, health checks, pairing commands, logs, and automatic recovery.

Features

• Native ChatGPT mobile Remote experience; no separate phone app
• Official Codex authentication and managed relay protocol
• No inbound listener, port forwarding, VPN, or firewall rule
• Starts at boot with systemd user lingering
• Restarts after a daemon crash or transient failure
• Short-lived manual pairing codes for mobile setup
• Built-in status, diagnostics, and journal commands
• Zero language-package dependencies

Quick start

git clone https://github.com/Dospacite/CodexRelay.git
cd CodexRelay
./install.sh
codex-relay pair

Open Remote in ChatGPT mobile, add a computer, and enter the setup code. The phone and Linux host must use the same ChatGPT account and workspace.

Requirements

• Linux with a systemd user session
• A current Codex CLI containing the experimental codex remote-control command
• Codex authenticated with ChatGPT (codex login status)
• The current ChatGPT Android app, signed in to the same account and workspace
• Remote Control permission if the ChatGPT workspace is managed

Codex Relay has no package or language runtime dependencies beyond Bash, systemd, and the Codex CLI.

Tested with Codex CLI 0.147.0 and systemd 261 on x86-64 Linux. Other distributions with a working systemd user manager should work as well.

Install

./install.sh

This installs only two user-owned files:

• ~/.local/bin/codex-relay
• ~/.config/systemd/user/codex-relay.service

It then enables and starts the service. Root access is not needed.

To keep the service running when you log out of Linux, enable systemd user lingering once:

loginctl enable-linger "$USER"

Pair Android

Generate a short-lived setup code:

codex-relay pair

In the ChatGPT Android app, open Remote, add a computer, and choose the option to enter a setup code manually. Use the same ChatGPT account and workspace as codex login status on Linux. The computer should then appear under Remote.

If your app offers only QR scanning, run the JSON form and use the value or link provided by the current pairing flow:

codex-relay pair --json

Pairing codes expire quickly. Generate a fresh one instead of saving or sharing it.

Operate

codex-relay status       # service state plus recent connection output
codex-relay doctor       # auth, CLI, systemd, and linger checks
codex-relay logs -f      # follow the service journal
codex-relay restart      # reconnect after a Codex CLI update
codex-relay stop
codex-relay start

The wrapper keeps Codex's managed app-server daemon inside the systemd service, watches its private control socket, and restarts it if the daemon exits. It starts with the systemd user manager. Its working directory is your home directory; project selection and filesystem approvals remain controlled by Codex.

Security model

• The service runs as your unprivileged Linux user.
• Network traffic is outbound; no public listener or firewall rule is created.
• Authentication stays in Codex's normal credential store.
• Mobile actions keep the configured Codex sandbox and approval policy.
• The systemd unit applies NoNewPrivileges and a private file-creation mask.

A paired phone can ask Codex to act with your account's configured permissions. Keep the phone locked, review approval prompts, and unpair devices you no longer trust.

How it works

codex-relay.service starts the wrapper as your normal user. The wrapper launches Codex's managed remote-control app server, waits for its private Unix control socket, and keeps supervising it. Codex makes the authenticated outbound connection to OpenAI. If the daemon disappears, the wrapper exits and systemd restarts the complete relay.

Pairing is delegated directly to codex remote-control pair; Codex Relay never reads or persists the generated code.

Troubleshooting

Run:

codex-relay doctor
codex-relay logs -n 100

Common fixes:

• Update Codex if remote-control is missing.
• Run codex login if the ChatGPT session expired, then restart the relay.
• Confirm Android and Linux use the same ChatGPT account and workspace.
• Ask a workspace administrator to allow Remote Control if it is managed.
• Prevent the Linux host from suspending; no background service can remain connected while the computer sleeps.

The remote-control CLI is currently marked experimental, so its command shape can change in a later Codex release. codex-relay doctor detects when the installed CLI no longer exposes it.

When reporting a problem, include the output of codex-relay doctor and a redacted excerpt from codex-relay logs -n 100. Never publish pairing codes or Codex credential files.

Remove

./uninstall.sh

Uninstalling leaves Codex credentials, configuration, chats, projects, and device pairings untouched.

Upstream documentation

• Codex developer commands
• Remote connections

License

MIT © Dospacite