Codex Relay Setup

Set up the Mac once. Then drive Codex from the phone.

This page is the Mac-side onboarding companion for Codex Relay. It explains the order clearly, gives you the exact install command, and includes the helper endpoint if you want the phone to trigger setup later.

Required first Tailscale on both devices, same account, both showing Connected.
Bootstrap relay Isolated onboarding relay runs on ws://<mac-host>:4615.
Setup helper Optional helper listens on http://<mac-host>:4616.
Project edits Codex edits the project folder you later choose, typically under ~/src/<project>.
Setup Steps
1

Install Tailscale

Do this before anything else. If the phone and Mac are not connected on the same tailnet, every Codex setup step after this is pointless.

  • Create or sign in with the same Tailscale account on iPad or iPhone and Mac.
  • Install Tailscale on both devices.
  • Approve the VPN permission on iOS or iPadOS if Tailscale asks.
  • Confirm both devices show Connected.
Open Tailscale Downloads Create Tailscale Account
2

Find the Mac address

The phone should not guess the Mac host. Enter the Mac Tailscale IP or MagicDNS hostname manually in Setup Mode.

  • In the Tailscale app on the Mac, find the device address.
  • Use either a 100.x.x.x IP or a MagicDNS hostname such as macbook-air.tailnet.ts.net.
  • Enter that value into the app’s Mac Tailscale IP or hostname field.
Examples 100.101.102.103 macbook-air.tailnet.ts.net
3

Install DexRelay on your Mac

Use the direct installer first on clean Macs. Use npm only when npm is already installed and writable.

Phone-triggered setup only works after a trusted helper already exists on the Mac.
  • Helper status endpoint: http://<mac-host>:4616/api/helper/status
  • Helper install trigger: POST http://<mac-host>:4616/api/helper/setup
  • Preferred first install for clean Macs:
curl -fsSL https://assets.dexrelay.app/install.sh | bash
Open Raw Install Script
npm i -g dexrelay
The installer sets up Codex CLI, Node, Python, the isolated bridge on port 4615, and the setup helper on port 4616.
4

Connect and log in

Once the Mac runtime exists, the phone connects to the bootstrap relay and starts OpenAI login. The authenticated runtime stays on the Mac.

  • Connect the phone to ws://<mac-host>:4615 in Setup Mode.
  • Tap Start OpenAI Login on the phone.
  • Finish the device login flow using the account you want the Mac runtime to own.
5

Permissions and projects

Keep permissions narrow. The phone needs network access and Tailscale approval; the Mac runtime needs install and file execution permission during setup.

  • Phone: approve Tailscale VPN access if prompted.
  • Mac: approve Homebrew, Node, Python, Codex, and launchd installation steps if macOS asks.
  • After login, choose the project folder Codex should work in, usually under ~/src.
Useful Endpoints

Bootstrap Relay

After install, the isolated onboarding relay listens here:

ws://<mac-host>:4615

Setup Helper

If present, the phone can query or trigger setup through:

GET http://<mac-host>:4616/api/helper/status POST http://<mac-host>:4616/api/helper/setup

Cloudflare Assets

These are the exact public files the onboarding runtime uses:

https://assets.dexrelay.app/install.sh https://assets.dexrelay.app/bridge.js https://assets.dexrelay.app/package.json https://assets.dexrelay.app/helper.py https://assets.dexrelay.app/create-mac-project.sh https://assets.dexrelay.app/git-project-automation.sh https://assets.dexrelay.app/governancectl.py https://assets.dexrelay.app/services.registry.json https://assets.dexrelay.app/setup-guide.html https://assets.dexrelay.app/dexrelay-skill.md
FAQ

Why did the phone not ask me to log in before?

Because the Mac runtime owns the login. If the Mac was already authenticated, a phone that reaches the relay can use that existing session immediately.

Why can’t the phone always run setup by itself?

A blank Mac has nothing trustworthy listening yet. The helper solves this later, but the first install still needs one approved bootstrap command or another preinstalled helper.

Where does Codex edit files?

The phone sends the chosen working directory to the Mac-hosted runtime. Codex then edits that project folder on the Mac, not the bootstrap runtime folder itself.

Can this live as a static page?

Yes. This file is fully self-contained and can be uploaded as a static Cloudflare page or opened directly on the MacBook in a browser.

Internal source of truth: public/dexrelay-runtime/setup-guide.html and scripts/onboarding/install-codex-relay-mac.sh.