Docs
Setup
Handback is the app on your Mac, iPhone, and iPad. The Engine is the part that runs where your agents do and catches their links: on a Mac, Handback runs it for you in Engine mode; on a Linux or headless box, it's a free one-line install. They talk directly — over Tailscale (recommended), your LAN, or a TLS reverse proxy.
On a Mac: Engine mode
On a Mac, Handback is the Engine itself — nothing else to install. Open Handback → Settings → Engine and turn on “Act as an engine on this Mac.” The app runs its bundled Engine and restarts it if it stops. The Engine runs while Handback is open. To have it running after a restart, turn on “Open at login” just below.
Listen address: the app shows the Tailscale address it finds and waits for you to confirm it is your tailnet — other VPNs use the same range — before the Engine listens there. Or enter another address.
Default browser: make Handback the default browser (macOS asks you to confirm) so links opened on this Mac by terminals, agents and command lines — Terminal, iTerm2, Ghostty, VS Code, Cursor, an agent's open — are handed back to your other devices, while links from other apps, like Safari, Mail or Slack, open in the browser you used before. For a Mac nobody sits at, turn on Hand back every link. While the Engine is paused, every link opens on the Mac. Turning Engine mode off gives the default browser back.
Pair a device: Show pairing QR… and scan it with the iPhone's Camera, or copy the URI into + → Add Machine on another device. The Mac doesn't pair with its own Engine: links captured there go to your other devices. The same Mac can still receive links from your other machines.
Ran the command-line Engine on this Mac before? Import existing pairing… reads its config.toml, so devices paired with it keep working. Then stop the old Engine (handback service uninstall) — it uses the same port.
1. Linux or headless box: install the Engine
On a Linux or headless box, install the free Engine with the one-line installer. It downloads the handback binary for your platform (Linux x86_64 or arm64, macOS), checks its checksum and puts it in ~/.local/bin. Then let it capture browser links: handback install writes a $BROWSER shim and prints the export BROWSER=… line to add to your shell profile; on Linux it also writes a .desktop entry so tools that use xdg-open can be caught.
curl -fsSL https://gethandback.com/install.sh | sh
# write the $BROWSER shim (catches gh, gcloud, most CLIs)
handback install
# on a headless Mac, also register a default-browser helper
handback install --default-browser 2. Pair it with Handback
Generate this machine's identity and a pairing URI. Pass the address your devices reach it at: a Tailscale name or a LAN host with its port pairs over plain ws://; behind a TLS reverse proxy, add --tls to pair over wss://.
handback pair --host your-box:8765 --qr
# behind a TLS proxy:
handback pair --host box.example.com --tls --qr
# prints a handback://pair?… URI and a scannable QR 3. Keep the Engine running
Start serving. handback service install keeps it running across reboots: a systemd user unit on Linux, a LaunchAgent on macOS. On a Linux box nobody logs into, also run loginctl enable-linger so your user services start at boot. handback service status reports on it; handback service uninstall removes it.
handback service install
# Linux box nobody logs into: start user services at boot
loginctl enable-linger
# or, in the foreground:
handback serve 4. Add it in Handback
Open Handback, hit + → Add Machine, and scan the QR or paste the URI. On an iPhone you can also scan it with the Camera. Toggle auto-open per machine if you want links to launch in your browser automatically.
Retained links
Links that arrive while no device is connected aren't lost. The Engine keeps them on its machine for 24 hours and delivers them when a device connects, where they show up as “arrived while you were away.” They're never opened automatically, and a sign-in that waited has moved on: start it again on the machine. Meanwhile the terminal that triggered the link prints it, so you can open it there.
Network & security
There is no relay and no account: the app connects straight to each Engine and presents the pairing token. Plain ws:// is only for a Tailscale tailnet or a LAN you trust; anywhere else, put a TLS reverse proxy in front of the Engine and pair with --tls. The Engine's control plane — where the $BROWSER shim, or the Mac app, hands it links — answers only on the machine itself: a loopback port and owner-only Unix sockets. Never expose it. Link history stays on your devices.
Recover a stuck login
If an OAuth login was started by another tool (not through Handback) and is stranded on a localhost callback, deliver it to its listener from the box:
handback deliver "http://localhost:60211/callback?code=…&state=…"