Reach it from anywhere

Choose a route#

• Your own VPN
  Good when: You already use Tailscale, WireGuard or similar on the phone
  You need: The bridge listening on its VPN address
• Reverse relay
  Good when: The computer is behind NAT or a work firewall, or you don’t want a VPN on the phone
  You need: A small server with HTTPS that you run; no inbound port on the computer
• App-only WireGuard
  Good when: You run a WireGuard server and want only this app to use it
  You need: A WireGuard peer for each phone

The phone never falls back from one route to another on its own, and a relay or VPN can’t read or type into your terminals. See Security for why.

Your own VPN#

If your phone and computer share a VPN, give the bridge the computer’s VPN address. For a new bridge, initialise it with that address before the first start:

herdr-remote init --url https://100.101.102.103:8443 --listen 0.0.0.0 --port 8443herdr-remote serveherdr-remote pair --scope control --qr

The address in --url is the one the phone dials and is always included in the certificate; add others with --san. An IP address is the tested form on iPhone. init never overwrites existing state, so for a bridge that already exists, use a separate --state directory (and pair again), or pair with a QR code from the console once its saved address is the VPN one.

Reverse relay#

The bridge dials out to a relay you run, over ordinary HTTPS on port 443, and phones reach the relay from anywhere. Nothing listens on the computer’s network, so it works from behind NAT, a work firewall or a proxy (the bridge honours HTTPS_PROXY).

  phone ──WSS──▶  relay you run  ◀──WSS (dials out)──  bridge on your computer
    │              (HTTPS, port 443)                         ▲
    └──────── TLS pinned to your computer's own certificate ─┘

1. 1

   Run the relay on a server

   Any small Linux server with a public name works. The relay is the same herdr-remote program:

   TerminalCopy

   herdr-remote relay serve --listen 127.0.0.1 --port 8788

   Output

   {"event":"relay_listening","port":8788}

   Put HTTPS in front of it with your reverse proxy or Cloudflare Tunnel, forwarding only /v1/tunnel and /v1/host and keeping WebSocket upgrades. For example, with Caddy:

   CaddyfileCopy

   relay.example.com {  reverse_proxy /v1/tunnel 127.0.0.1:8788  reverse_proxy /v1/host 127.0.0.1:8788}

   The relay keeps its own secrets in ~/.local/share/herdr-remote-relay. Run it as a service the same way as the bridge.

2. 2

   Make a relay profile

   TerminalCopy

   herdr-remote relay profile --public-url wss://relay.example.com > relay.jsonchmod 600 relay.json

   relay.json (secrets shown as <secret>)

   {  "version": 1,  "host": {    "url": "wss://relay.example.com/v1/host",    "token": "<secret>"  },  "phone": {    "mode": "gateway",    "gateway": {      "url": "wss://relay.example.com/v1/tunnel",      "token": "<secret>"    }  }}

   The profile holds two separate random secrets: one the bridge uses to register, one phones use to get in. Copy it to your computer privately (for example with scp) and keep it mode 600.

3. 3

   Join the relay from your computer

   TerminalCopy

   herdr-remote relay join relay.json

   Output

   {"joined":true,"relay":"relay.example.com","next":"restart serve/up, then pair --scope control --qr"}

   Restart the bridge. It now keeps one outgoing connection to the relay and reconnects with backoff if it drops:

   TerminalCopy

   herdr-remote up

   Output

   {"event":"listening","url":"https://studio.local:8443","relay":true,"localRoute":true,…}{"event":"relay_connected","url":"relay.example.com"}

4. 4

   Pair through the relay

   TerminalCopy

   herdr-remote pair --scope control --qr

   The invitation now carries the relay route and a relay credential made for that one phone. Scan it, and the phone reaches your computer from any network. Phones paired before you joined need a fresh QR invitation to learn the route.

Home network, automatically

A bridge that has joined a relay still answers phones on its own network, and tells paired phones its local addresses. At home the phone connects directly; when you leave, it switches back to the relay. Nothing needs re-pairing, and the phone checks the same certificate either way. To keep the bridge on loopback only, start it with --no-local-route or untick the option in the console.

Keeping the relay tight

• Each phone gets its own relay credential, and the bridge tells the relay which ones to admit every few seconds. Once all your phones have connected with a current app, restart the relay with --personal-only so the shared phone secret no longer works and revoked phones are refused at the relay. Keep the shared secret while you use the Android app.
• herdr-remote relay rotate --public-url wss://relay.example.com issues new relay secrets; join again with the new profile.
• The console shows relay connections admitted and rejected, and warns if another connection took over with the bridge’s credential.
• herdr-remote relay status and relay leave show or remove the profile, and pair --no-relay makes a direct-only invitation.

App-only WireGuard#

The iPhone and iPad app has WireGuard built in for its own connection only: it doesn’t install a VPN profile or touch other apps’ traffic. If you run a WireGuard server that can reach the computer, you can pair in either of two ways:

• Create the invitation with a private route file: herdr-remote pair --scope control --qr --connection wireguard-route.json. The format is described in connection-routes.md.
• Or, while pairing, choose Connection options → Paste WireGuard configuration and import a standard single-peer config. The app narrows it to the one computer you are pairing with.

Give each phone its own peer: two devices sharing one peer key interrupt each other. A guided container setup that bundles a WireGuard endpoint with the bridge is being prepared for the public repository.

Keep the computer reachable#

Whatever the route, the computer must be on, awake and running the bridge. Run the bridge as a service, and stop the computer from sleeping while you want to reach it.