Install the bridge

outridr is a small server that runs next to herdr and exposes it to your tailnet, so the app on your phone can watch and drive your agents. It goes on the machine your agents run on.

Before you start

• Node.js 20 or newer on that machine (node --version to check).
• herdr installed and running. If you don't know what that is yet, read What is herdr? first.
• Tailscale signed in on the machine and on your phone, on the same tailnet.

Install

$ npx outridr install

That installs the npm package globally and sets it up as a user service: systemd on Linux, launchd on macOS. The service starts right away and restarts if it dies. It binds your Tailscale interface on port 8674 and nothing else; it is not meant to be reachable from the public internet.

One macOS wrinkle: Tailscale.app doesn't put the tailscale CLI on your PATH. outridr looks for it at /Applications/Tailscale.app/Contents/MacOS/Tailscale on its own, and OUTRIDR_TAILSCALE_BIN overrides that if yours lives somewhere else.

Pairing the app

$ outridr pair

pair makes sure a token is set, generating one the first time and reusing it on every later run, then prints a QR code and an outridr://pair?… link. Point your phone's camera at the QR: the outridr app opens a confirmation screen, and one tap applies the host, port, and token.

The token is optional, but set it anyway. Your tailnet is the perimeter; the token is a second lock on top of it. And treat the QR and the link like a password — anyone who has either can drive your agents.

If the app says the bridge rejected your token, run outridr pair again and rescan. It never overwrites a saved token, so a fresh QR always carries the one the server expects.

Afterwards

Configuration lives at ~/.config/outridr/config.json, and every field is optional. OUTRIDR_PORT, OUTRIDR_HOST, OUTRIDR_TOKEN, and HERDR_SOCKET_PATH override it from the environment. The full reference is in the repo README.

• outridr status shows the service state.
• outridr config prints the resolved configuration, masking the token unless you pass --show-secrets.
• outridr serve runs in the foreground.
• outridr uninstall stops and removes the service.

If the app still can't find the machine, Troubleshooting covers the usual reasons.