herdr-mobile-relay
Control agents from the Herdr TUI, herdr-app or herdr-core from your phone. Each Linux or macOS computer runs its own relay; the phone connects to them and merges every agent into one installable web app.
Current version: 0.25.1 · Changelog
[!IMPORTANT] Native Windows is not supported. WSL2 may work but is not tested.
[!WARNING] 0.20.0 replaces the shared relay key with per-device credentials and a new encrypted transport. It cannot be installed through the phone updater: upgrade the relay manually and pair every phone again.
Get started in two minutes
For the TUI relay: Herdr 0.7.5 or newer, Git, and curl. Herdr 0.9.0 is
recommended for the complete live JSON inventory and workspace-management
surface; the relay does not treat that recommendation as a new minimum.
The relay reports the installed Herdr client version separately from the running local server version and protocol. A server upgrade can enable or disable individual actions without changing the relay release.
herdr plugin install 0cv/herdr-mobile-relay
The setup menu opens automatically after installation and asks how your phone should reach this computer:
Choose a path:
1. Cloudflare
2. WebRTC
3. Tailscale
q. Exit, change nothing
Each path then lists only its own actions; b goes back.
On a computer that also runs herdr-app, the menu first asks whether the phone should control the Herdr TUI, herdr-app (core), or both, and shows each relay's status. Core setup →
To reopen the main setup menu later:
herdr plugin pane open \
--plugin herdr-mobile-relay.events \
--entrypoint setup \
--placement zoomed \
--focus
Open WebRTC → Community WebRTC Gateway. It is the recommended path: as fast
to set up as the temporary tunnel, with stable relay connectivity and no
Cloudflare account, domain, cloudflared, or tunnel configuration. If prompted,
choose the installed Herdr app that should host the phone UI. The relay starts
and prints a QR code.
Cloudflare → Temporary Cloudflare Tunnel is the fastest getting-started option for a one-computer trial. It installs any missing user-level tools with confirmation, starts the relay and bundled app, and prints a QR code.
If you already use Tailscale on your phone and computer, choose Tailscale → Always on Tailscale for private HTTPS inside your tailnet, without a Cloudflare account or gateway. Tailscale keeps the connection up in the background, so the app reconnects quickly (setup steps).
Scan the QR with your phone. A relay started in the pane stops with Ctrl-C; an installed background service keeps running.
The relay setup does not run sudo or need a Python, Node.js, or Go toolchain.
Treat the QR and its setup link as secrets: they contain a one-use device
invitation.
QUICKSTART.md has pairing detail and troubleshooting for all three paths.
Core compatibility — new in 0.25.0
Control herdr-app and herdr-core (hc) agents from your phone through a second
relay, shown as <hostname> (core) beside the Herdr TUI relay.
Tested with herdr-core 0.1.18 and herdr-app 0.1.13 (also 0.1.12).
- Available: agents, status, screens, prompts, keys, secrets, start/stop/clear/restart, tab and workspace rename and reorder, and Resize Session.
- Conversation supports Pi, Claude Code, Codex, Cursor, Omp, OpenCode, Hermes, Qoder, agy, Grok and Kimi, with the session setup described in the guide.
- Cursor and Hermes need a newer Herdr core/app to report status; they appear once Herdr recognises them.
- Not yet: colour, creating/closing workspaces and tabs, worktrees, or phone-driven updates.
If you use the Herdr TUI, the setup menu above sets up the TUI relay, the core
relay, or both, and each QR says which computer it adds. Without the TUI,
download install.sh from this repository at tag v0.25.1 and run
sh install.sh 0.25.1; it downloads and verifies the release bundle and prints
the command that opens the same menu. Core pairs over Tailscale or Cloudflare;
see the core guide.
What you get
| Agents | Terminal | Pairing |
|---|---|---|
 |
 |
 |
- Monitor and control agents across several computers, grouped by status and Herdr workspace, with agents that need input pinned on top.
- Answer approvals and structured plan questions from Codex, Claude Code, Hermes, Qoder, OpenCode, Oh My Pi, and Pi.
- Send prompts, terminal keys, and slash commands, including discovered Cursor commands and skills; attach screenshots, photos, and documents in cancellable batches. Optionally discover live Pi extension commands, skills, and templates by enabling Settings → Pi Integration for that computer, then reloading Pi (CLI alternative).
- Read and search native conversations for agents with a native history reader, including Hermes, OpenCode, Antigravity CLI, Grok, Oh My OpenCode plans and native Kimi Code journals. Kimi imports and human-engine-only histories use the Terminal fallback. Inspect workspace files, images, and Git diffs read-only.
- Manage workspaces and Git worktrees; start, rename, clear, and stop agents.
- Have the relay read responses aloud, even with the screen off.
- Pair every phone as its own named device — controller or read-only reader — each with its own notification rules, and revoke any of them.
With Codex 0.160 or later, start Codex with codex --no-daemon in Herdr panes.
Otherwise, Codex's shared background server runs Herdr's hooks outside the pane,
and Codex's Conversation is missing or shows another pane's session.
See docs/herdr-core.md for the zsh snippet.
New in 0.24.0: Connect through Tailscale. The setup menu groups Cloudflare, WebRTC and Tailscale; an open Conversation refreshes after a reconnect.
Mobile onboarding
https://github.com/user-attachments/assets/e52c4fd0-ef77-4852-bb43-078a7154eae8
The walkthrough follows setup from scanning the QR through the agent list, terminal controls, and notification settings.
Choosing how your phone connects
The setup menu starts with Cloudflare, WebRTC, and Tailscale. Select a path to see only its actions; use Back to choose another path.
| Choice | Needs | Best for |
|---|---|---|
| Community gateway | no account, domain, or tunnel configuration; an installed app origin | the recommended stable, no-configuration relay path |
| Cloudflare tunnel | nothing for a temporary URL; a Cloudflare account and domain for a permanent hostname | the fastest one-computer trial or a permanent background service |
| Tailscale Serve | Tailscale on phone and computer, in the same tailnet | private HTTPS without Cloudflare or a gateway; fast reconnects |
| Your own gateway | a small VPS | dedicated bandwidth and control of the transport logs |
All four use end-to-end relay encryption. On either gateway the phone and the computer then negotiate a direct peer-to-peer connection, leaving the gateway with the fallback; Cloudflare tunnel traffic stays on Cloudflare. Tailscale Serve is available only inside your tailnet. Set up Tailscale →.
Agents with a non-default config directory
The relay runs as a background service and does not see a pane's
CLAUDE_CONFIG_DIR, PI_CODING_AGENT_DIR, or similar. If an agent's
conversation shows as unavailable or a profile's slash commands are missing,
point the relay at that profile with HERDR_*_CONFIG_DIRS:
Agent directories →
Documentation
| Page | What is in it |
|---|---|
| QUICKSTART.md | The fast path, start to paired phone |
| docs/mobile-app.md | Every feature: agent list, terminal, devices, speech, notifications |
| docs/transports.md | Cloudflare, Tailscale, gateways, direct WebRTC |
| docs/herdr-core.md | A second relay for herdr-core (herdr-app) beside the TUI relay |
| docs/cloudflare-tunnel.md | The stable tunnel wizard, DNS, and teardown |
| docs/gateway-self-hosting.md | Deploying and operating a gateway |
| docs/agent-directories.md | Agents that use a non-default config or profile directory |
| docs/slash-command-discovery.md | Bounded slash-command discovery and incomplete-catalog guidance |
| docs/updates.md | Verified releases, phone-driven upgrades, upgrading from 0.19.1 |
| docs/security.md | What is encrypted, device pairing, what an intermediary sees |
| docs/development.md | Building, testing, and contributing |
Security in one paragraph
Prompts, terminal output, uploads, and push details are encrypted end to end between the phone and the relay. Whatever carries the traffic — a Cloudflare tunnel, a gateway, or Tailscale Serve — observes connection metadata only, never plaintext; on the direct path no application data reaches it at all, though a gateway still answers address discovery. Paired credentials distinguish controller and reader devices, mutations default to controller-only, attachment references stay bound to the terminal and agent session that created them, and the app can require device verification before it reconnects. Details →
