Codex Relay

Project status: This project is no longer needed. ChatGPT added mobile support. :party:

Codex Relay is a local command bridge for controlling Codex from a paired Android phone. It includes a Node.js app-server, a polished local web pairing screen, and a native Android client.

Security note: this project can start Codex and send commands on your Mac. Keep the server on localhost by default, pair only on trusted Wi-Fi, and use HTTPS for any remote access.

Screenshots

Android connect	Android dashboard

What You Get

• Local web pairing screen with one-time 8-digit pairing codes.
• Native Android app, not a WebView shell.
• Paired-device token auth for future reconnects.
• Project picker, slash commands, file mentions, image attachment upload, and Codex result rendering.
• Browser live terminal for interactive Codex controls such as model switching, approvals, MCP inspection, compacting, and raw slash commands.
• Safe open-source defaults: localhost server binding, ignored .env, HTTPS-required remote mode, and no auto-installed APK updates.

Requirements

• macOS or Linux host with Node.js 20+.
• Codex CLI installed and available as codex.
• Android Studio, or JDK plus Gradle, to build the Android app locally.
• Phone and computer on the same trusted Wi-Fi for first pairing.

Quick Start

1. Install dependencies:

   npm install

2. Generate a private local .env:

   npm run setup

3. For browser-only local testing, start the server:

   npm start

   Open http://localhost:8787.

   The browser app includes both the chat surface and a live Codex terminal. Use the terminal button after pairing to access the full interactive Codex CLI from the selected project.

4. To pair an Android phone on trusted Wi-Fi, edit .env and set:

   HOST=0.0.0.0

   Then restart:

   npm start

5. Build and install the Android app:

   cd android-native
   ./build-apk.sh

   The local debug APK is created at android-native/app/build/outputs/apk/debug/app-debug.apk.

6. Open the Android app and tap Continue.

7. Confirm the pairing request on the web screen on your Mac, then enter the 8-digit code shown there.

After pairing, the phone stores an encrypted paired-device token and reconnects automatically while the server is reachable.

Remote Access

Do not port-forward this server directly from your router.

For away-from-home use, pair once nearby first, then expose the server through a trusted HTTPS tunnel or reverse proxy:

cloudflared tunnel --url http://localhost:8787

Set these values in .env:

TRUST_PROXY=true
PUBLIC_URL=https://your-secure-tunnel.example

Remote HTTP URLs are rejected by the Android app. HTTPS is required outside private local-network addresses.

Configuration

Copy .env.example or run npm run setup.

Variable	Default	Purpose
REMOTE_TOKEN	generated	Private legacy token. Device tokens are preferred.
PORT	8787	App-server port.
HOST	127.0.0.1	Bind address. Use 0.0.0.0 only for trusted Wi-Fi pairing.
CODEX_COMMAND	/Applications/Codex.app/Contents/Resources/codex on macOS when installed, otherwise codex	Codex app bundle command used for desktop-app-native sync.
CODEX_WORKDIR	current folder	Default workspace.
CODEX_PROJECT_ROOTS	parent folder	Folders exposed in the project picker.
TRUST_PROXY	false	Trust X-Forwarded-Proto only behind your HTTPS proxy.
PUBLIC_URL	empty	Optional HTTPS tunnel URL for QR output.

GitHub Actions

The Build Android APK workflow is manual. By default it uploads the APK artifact and publishes a GitHub release that the Android app can discover from Settings → Check updates.

For installable in-app updates, configure these GitHub Actions secrets so every release APK is signed with the same private key:

• ANDROID_KEYSTORE_BASE64
• ANDROID_KEYSTORE_PASSWORD
• ANDROID_KEYSTORE_TYPE
• ANDROID_KEY_ALIAS
• ANDROID_KEY_PASSWORD

Keep signing keys out of the repo. If the signing secrets are missing, the workflow still builds an unsigned APK artifact, but Android will not install it as an update over an existing signed app.

Security Model

• .env is ignored and should never be committed.
• Pairing codes are one-time, short-lived, and visible only from the Mac web UI.
• First pairing must start from the same local network.
• Android stores paired-device tokens with AndroidX encrypted preferences.
• Project chat history is project-scoped and redacts common token, private-key, bearer-token, and env-secret formats before sending transcript text to the phone.
• Remote access requires HTTPS.
• The Android app checks the latest GitHub release and opens the release page for updates; Android still handles APK installation approval.

Development

Check the server syntax:

npm run check

Audit production dependencies:

npm audit --omit=dev

Regenerate icon PNGs after editing SVG assets:

npm run build:icons

License

MIT