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.

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
  notifications surface waiting agents; one tap opens the exact prompt.
• Work in the live session. Auto picks per session between Control
  (terminal view + system keyboard, dictation and a keypad), Terminal (the
  real PTY, for vim and full-screen TUIs) and Chat (message the agent and
  read its replies).
• Review changes. Browse files, read git status and diffs, comment on diff
  lines and send the comments to the agent.
• Hand files to the agent. Upload photos, PDFs and other files over P2P and
  insert their workspace paths into the draft.
• Shape the workspace. Start conversations, tabs, splits and worktrees, and
  see a tab's real pane layout on the Board. Controls only appear when the
  computer supports them.
• Several computers, several devices. One phone can switch between
  computers; each computer can have several paired devices. Named Herdr
  sessions (herdr --session <name>) are on by default; see
  Named Herdr sessions.
• Keep an eye on quota. Subscription allowance for Codex, Claude Code,
  Copilot, Cursor, Grok and more, collected on the computer.

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

Security

• Pairing uses SPAKE2+ with a code both sides confirm; session keys are
  hardened with Argon2id.
• Keys live only on the computer and the paired device. The relay at
  pairfob.com forwards ciphertext frames it cannot read.
• Direct when possible. An established session upgrades to a WebRTC
  DataChannel and keeps the relay as fallback.
• Nothing exposed. The computer only dials out; Herdr is never reachable
  from the internet.

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

Requirements

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.

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.