Pairfob

English | 简体中文

Your Herdr agents, on your phone. Codex, Claude, Grok and the rest keep running on your computer; after pairing once, a phone, tablet or another computer opens the same live sessions, not copies. The computer dials out, so there are no inbound ports and no VPN, and the session is end-to-end encrypted.

!Pairfob on a phone: the session list, a live session, and a diff review

Quick start

macOS or Linux, with Herdr installed (the installer offers to install it if missing).

curl -fsSL https://pairfob.com/install.sh | sh
pairfob pair

On the phone, open pairfob.com/pair and scan, then press Enter once on the computer to admit it. Add it to your Home Screen and you are done. Full walkthrough: Get started.

Already living in Herdr? herdr plugin install arronKler/pairfob adds Pairfob: Pair a device to Herdr's action menu and installs the same verified binary on first use. See plugin/herdr/.

What you can do from the phone

• Respond when an agent needs you. A Needs you strip and optional push

• Work in the live session. Auto picks per session between Control

• Review changes. Browse files, read git status and diffs, comment on diff

• Hand files to the agent. Upload photos, PDFs and other files over P2P and

• Shape the workspace. Start conversations, tabs, splits and worktrees, and

• Several computers, several devices. One phone can switch between

• Keep an eye on quota. Subscription allowance for Codex, Claude Code,

The app speaks English and 中文. Details: Using the app.

Security

• Pairing uses SPAKE2+ with a code both sides confirm; session keys are

• Keys live only on the computer and the paired device. The relay at

• Direct when possible. An established session upgrades to a WebRTC

• Nothing exposed. The computer only dials out; Herdr is never reachable

See What the relay cannot see and report vulnerabilities privately via SECURITY.md.

Requirements

| Item | Requirement | | --- | --- | | Computer | macOS or Linux (Windows is not supported) | | Herdr | 0.8 or newer; the installer can install pinned 0.8.2 | | Herdr plugin | Herdr 0.8.2 or newer | | Close a workspace from the phone | Herdr 0.9.0 or newer | | Phone / tablet | A current mobile browser; installable as a PWA |

Computer commands

pairfob                     # status in a terminal; exits if it is not running
pairfob run                 # start the daemon in the foreground
pairfob pair                # pair a phone, tablet, or another computer
pairfob list                # paired devices
pairfob forget 1            # unpair by index or name
pairfob doctor              # diagnose this computer (never changes anything)
pairfob setup               # check, optionally install, and start Herdr
pairfob update              # latest release, then restart the service
pairfob quota-setup-claude  # enable Claude subscription quota collection
pairfob service status      # login service: start / stop / restart / install / uninstall

A second computer runs the same installer; pair it from the phone with Settings → Switch computer → Add a computer. Machines that Herdr already reaches over SSH can be added from the phone's Computers page without a pairing code. Everything else: Computer commands.

How it works

phone  --HTTPS/WSS pairfob.v2-->  pairfob.com (Worker + Durable Object)
pairfob --outbound WSS---------->  same room  --opaque FWD-->  phone
          \-- WebRTC DataChannel after authenticated setup --/
pairfob --loopback-------------->  Herdr

The phone reads the rendered pane and sends keys back to the PTY; it is not a terminal emulator of its own. pairfob.com is the project's official instance. Protocol specs live in proto/, including direct transport.

| Path | What it is | | --- | --- | | cmd/pairfob | the computer daemon and CLI | | internal/ | pairing, sessions, RPC, Herdr adapter, protocol primitives | | pwa/ | the phone app (React + TypeScript, built with bun) | | workers/pairfob-origin | the relay: Cloudflare Worker + Durable Object | | site/ | homepage and documentation sources | | proto/ | frozen envelope, RPC schema and test vectors | | plugin/herdr | Herdr plugin entrypoints |

Develop

(cd pwa && bun install --frozen-lockfile)
./scripts/dev-up.sh     # local origin + pairfob + PWA on loopback
./scripts/verify.sh     # full gate: Go, PWA, Worker, site tests and builds
./scripts/dev-down.sh

Set PAIRFOB_DEV_FAKE_RUNTIME=1 for demo data without Herdr. Real-phone testing, verification scope, protocol invariants and releases: docs/develop.md.

Contributing

Issues and pull requests are welcome at github.com/arronKler/pairfob. Run the checks that match your change (see docs/develop.md) and list them in the PR. The envelope, vectors and RPC fields under proto/ are frozen by design; please open an issue before proposing a change there.

Star History

License

Apache License 2.0. See NOTICE.