Documentation · Multi-machine

Cloudflare Tunnels & Pairing

Pair remote Linux build servers or secondary Macs with your primary workstation over HTTPS using cloudflared, a 127.0.0.1 HTTP JSON-RPC bridge, and least-privilege stream_steer Bearer tokens.

Multi-machine pairing over Cloudflare Tunnel to a loopback 127.0.0.1 HTTP bridge with stream_steer scope.
oh-router devices tunnel-start pairs cloudflared with a 127.0.0.1 HTTP JSON-RPC bridge using constant-time stream_steer Bearer tokens.

One-click agent pairing recipe

Copy the self-contained setup prompt below and paste it into a coding agent running on your remote Linux or macOS machine, or generate a customized Markdown recipe locally with oh-router devices recipe --name build-box --quick.

Remote Host Setup Prompt

Instructs an agent on a remote host to install oh-router, start ohd, open a stream_steer Quick Tunnel, and report the HTTPS URL and 0600 token path.

Quick Tunnels and Named Tunnels

devices tunnel-start binds the HTTP JSON-RPC bridge strictly to 127.0.0.1 (default port 7842), writes or rotates the secret token in <state-dir>/bridge.token (mode 0600), and spawns cloudflared pointing at that loopback port.

Ephemeral Quick Tunnel (*.trycloudflare.com, no Cloudflare account or DNS record required):

Remote machine (Quick Tunnel)
$ oh-router daemon start
$ oh-router devices tunnel-start --scope stream_steer --quick --publish

Persistent Named Tunnel with your own DNS hostname:

Remote machine (Named Tunnel)
$ oh-router devices tunnel-start --scope stream_steer --tunnel build-box --hostname ohd.example.com --publish

Register the remote host on your primary workstation:

Primary workstation
$ oh-router devices add-remote --name build-box --role server --platform linux --tunnel-url https://ohd.example.com --bearer-token "<PASTE_STREAM_STEER_TOKEN>"
$ oh-router devices list --json

Token scopes and transport rules

  • Loopback binding only: /v1/rpc binds exclusively to 127.0.0.1 and never listens on 0.0.0.0.
  • Header-only Bearer auth: Authorization: Bearer <token> is verified in constant time (subtle::ConstantTimeEq). Any request carrying ?token= or percent-encoded query credentials is rejected with 401 Unauthorized.
  • Least-privilege stream_steer default: allows state.snapshot, session.list, session.inspect, session.steer, session.action, queue.*, and claude/codex spawns while rejecting kind: "shell", custom argv, profile edits, and tunnel changes (403 Forbidden).
  • Token-free #fleet announcements: passing --publish posts {device_id, name, role, platform, url} to the #fleet board channel so workstations follow rotated Quick Tunnel URLs without ever transmitting the Bearer secret.

Optional SSH ProxyCommand helper

When a remote machine also runs an SSH Access hostname behind cloudflared, devices ssh-config previews or writes a managed # oh-cloudflare-ssh:start block in ~/.ssh/config after validating host, DNS, and username characters.

Preview or write ~/.ssh/config
$ oh-router devices ssh-config --host build-box --hostname ssh.example.com --user dev
$ oh-router devices ssh-config --host build-box --hostname ssh.example.com --user dev --write