codex-route

Use a second machine on your LAN as a remote backend for AI coding CLIs:

• codex-route — swap Claude Code's codex MCP server between local and an SSH host. Lets one machine borrow another's ChatGPT account/quota.
• claude-ssh — launch a Claude Code session on a remote machine from your local terminal. Useful for running two concurrent Claude Code sessions on different machines, or sharing a vault across them.
• Thunderbolt Bridge setup notes — optional, for when both machines are next to each other and you want a ~9× faster link than 1GbE.

Why

Claude Code can be configured to use OpenAI Codex as an MCP tool. When Codex authenticates via ChatGPT, it consumes that account's tokens. If you exhaust the quota on one machine but have a second machine on your LAN signed in to a different ChatGPT account, you can route Codex calls from the first machine to the second one over SSH instead of waiting for the quota to reset.

The Codex CLI's mcp-server mode communicates over stdio, which SSH forwards transparently. codex-route just rewrites the mcpServers.codex entry in ~/.claude.json so that Claude Code spawns ssh user@host codex mcp-server ... instead of codex mcp-server ....

The same trick doesn't quite work for Claude Code itself (no public stdio MCP server mode for it), so claude-ssh instead launches a remote interactive session via ssh -t. You drive it from your local terminal but it runs on the remote machine.

Requirements

• Both machines: Codex CLI installed and authenticated.
• The remote machine: SSH access from the local machine via key auth (no interactive password prompts — Claude Code will hang otherwise).
• Local machine: Claude Code with a working codex entry in ~/.claude.json.

Install

git clone https://github.com/sunjinpak/codex-route.git
cd codex-route
install -m 0755 codex-route ~/.local/bin/codex-route   # or anywhere on $PATH
install -m 0755 claude-ssh  ~/.local/bin/claude-ssh    # optional, for remote Claude Code sessions

Single-file scripts — codex-route needs Python 3, claude-ssh is plain bash. No other dependencies.

Quickstart

# 1. Register your remote machine (one-time)
codex-route add lab-mac user@192.168.1.42

# 2. Check the current mode
codex-route status

# 3. Switch Claude Code's codex MCP server to the remote
codex-route use lab-mac

# 4. Restart Claude Code (or run /mcp to reconnect) so the new MCP server is spawned

# 5. When you want to go back to local
codex-route local

Each switch creates a timestamped backup of ~/.claude.json next to the file.

Verifying SSH works

Before registering a route, confirm key-auth SSH and that Codex is on the remote PATH for non-interactive shells:

ssh user@host '/opt/homebrew/bin/codex --version'

Non-interactive SSH on macOS often skips ~/.zshrc, so Homebrew's codex may not be on $PATH. Pass the absolute path via --codex-path:

codex-route add lab-mac user@host --codex-path /opt/homebrew/bin/codex

You can sanity-check the MCP handshake before switching:

printf '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}\n' \
  | ssh user@host '/opt/homebrew/bin/codex mcp-server -c sandbox_mode=\"danger-full-access\" -c approval_policy=\"never\"'

A JSON-RPC result with protocolVersion confirms Codex is launching cleanly over SSH.

Commands

Command	Description
codex-route add <name> <user@host> [--codex-path PATH]	Register a named remote route.
codex-route remove <name>	Unregister a route.
codex-route list	Show registered routes.
codex-route use <name>	Switch the codex MCP server to a named route.
codex-route local	Revert to local codex.
codex-route status	Show current routing.

Config

~/.config/codex-route/routes.json (created on first run). Override claude_config_path, the local codex command name, MCP args, or the default remote codex path here if you need to.

---

claude-ssh: launch Claude Code on a remote machine

A thin wrapper around ssh -t that launches an interactive Claude Code session on a remote host. The session is driven from your local terminal but runs on the remote (using the remote's Anthropic auth, files, environment).

claude-ssh <ssh-host> [args]

claude-ssh m1                   # interactive session on host 'm1'
claude-ssh m1 --resume          # forward args to the remote claude
CLAUDE_REMOTE_PATH=/usr/local/bin/claude claude-ssh other-mac

Defaults the remote claude binary to ~/.local/bin/claude (the standard Claude Code install location). Override with CLAUDE_REMOTE_PATH if your remote is elsewhere.

Typical workflow

1. Set up an SSH alias in ~/.ssh/config for the remote (key-auth, no password):

   Host m1
       HostName 192.168.1.42
       User you
       ServerAliveInterval 30

2. Verify: ssh m1 'ls ~/.local/bin/claude' should print the binary path.
3. From your local terminal: claude-ssh m1.

The local Claude Code session and the remote one are independent — separate quotas, separate conversation state — but if both machines share a file path (Obsidian vault, git repo, etc.) the edits are coherent.

Why not "claude-route" (mirror of codex-route)?

Claude Code has no documented stdio MCP server mode, so you can't proxy it the same way as Codex. claude-ssh instead just opens an interactive session on the remote and lets you use it directly. If/when Claude Code grows an MCP server interface, a claude-route analog becomes possible.

---

Optional: Thunderbolt Bridge for two adjacent Macs

If both machines are physically next to each other and connected by a Thunderbolt cable (or daisy-chained through a TB dock), Thunderbolt Bridge gives you a ~9× faster link than 1GbE. Useful for large file sync; minimal effect on SSH/MCP latency (both are sub-millisecond on either link).

Setup

On each machine, assign a static IP on the Thunderbolt Bridge interface:

# Machine A
networksetup -setmanual "Thunderbolt Bridge" 10.10.0.1 255.255.255.0 ""

# Machine B
networksetup -setmanual "Thunderbolt Bridge" 10.10.0.2 255.255.255.0 ""

No sudo needed; persists across reboots. Verify:

ifconfig bridge0 | grep -E 'inet |status'
# expect: inet 10.10.0.1 ... status: active
ping -c 2 10.10.0.2

If status: inactive, the OS isn't seeing the TB link — reseat the cable, make sure it's a TB-rated cable (not a plain USB-C), and confirm system_profiler SPThunderboltDataType shows the peer as Device connected.

Then add SSH aliases that prefer TB and fall back to LAN:

Host m1
    HostName 10.10.0.2          # TB
    User you
    ServerAliveInterval 30
    ConnectTimeout 5

Host m1-lan
    HostName 192.168.1.42       # LAN fallback
    User you
    ServerAliveInterval 30

codex-route and claude-ssh both accept SSH aliases, so codex-route add m1 m1 and claude-ssh m1 will use TB by default.

Measured (M4 Pro Mac mini ↔ M1 Mac mini, TS3 Plus dock daisy-chain)

TB Bridge: 1047 MB/s  (8.4 Gbps)   ping 0.59 ms
1GbE LAN:   115 MB/s  (0.92 Gbps)  ping 0.64 ms

→ ~9× throughput, ~equal latency. Means TB is a clear win for rsync/scp of large files, but doesn't speed up SSH commands or MCP stdio meaningfully (those are latency-bound, not throughput-bound).

Caveats

• Each switch requires restarting the Claude Code session (or /mcp reconnect) so the new MCP server is spawned. The script can't trigger that for you.
• Latency is added by SSH; for short Codex calls this is fine, for long streaming responses you may notice it.
• If you switch to a remote whose ChatGPT account is also rate-limited, you get the same error you'd get locally.
• This swaps only the codex MCP entry. Other MCP servers are untouched.
• Tokens are not shared or copied between machines; the remote uses its own auth.

License

MIT. See LICENSE.