# 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.

Canonical URL: https://ohrouter.com/docs/tunnels

## 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**

```text
Set up oh-router remote session pairing on this machine and report the connection details back to me:
1. Install oh-router if missing by running: curl -fsSL https://ohrouter.com/install.sh | sh
2. Ensure cloudflared is installed on PATH (brew install cloudflared on macOS, or the official cloudflared binary on Linux).
3. Start the local supervisor and launch a least-privilege Quick Tunnel by running:
   oh-router daemon start --json
   oh-router --json devices tunnel-start --scope stream_steer --quick --publish
4. Return the tunnel_url and token_file path from the JSON output so I can run oh-router devices add-remote on my workstation. Do not post the raw bearer token to any shared channel.
```

## 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)**

```sh
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)**

```sh
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**

```sh
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**

```sh
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
```
