herdr-remote: a menu bar, phone and Telegram dashboard for herdr agents

The gap herdr-remote fills, and who it is for

herdr runs agents. Watching them means watching a terminal. That is fine while you sit at the machine and awkward the moment you leave it, because the events that matter are the ones that need a human: an agent that blocked on a tool approval, an agent that finished, an agent that has been idle long enough to be worth interrupting. herdr-remote is a front end for those events. The README describes a live agent timeline showing who worked when, who blocked and who finished, one-tap approvals from phone, menu bar or Telegram, terminal interaction to read output and send commands, and notifications when agents need you. The audience is narrow and clear: people already running herdr 0.7 or later who want to answer an approval without walking back to the desk. It is not a herdr replacement and does not claim to be; the agents still run under herdr, and the dashboard is a view onto them.

How the relay, the poller and herdr-push fit together

The architecture diagram in the README shows three client surfaces: the web app on a phone, the Telegram bot and a terminal TUI. All three speak WebSocket to a relay listening on port 8375, which is the single point every remote client connects through. Below the relay sit two data paths. One is a local poll that calls the herdr CLI. The other is herdr-push, a separate zero-dependency plugin that the README says sends HTTP POST updates into the relay. That second path is what makes cross-machine monitoring possible: the plugin is installed with a herdr plugin install command, and the README describes it as the way to monitor agents across machines. The macOS menu bar app sits outside this flow entirely. It is drawn in the diagram as its own box marked zero config, and the README says it monitors all local herdr agents automatically with no relay, no config and no account. So there are two products in one repository: a self-contained menu bar client, and a relay-based remote stack. The split matters when you decide what to install, because the menu bar app never touches port 8375 and never needs a tunnel.

Installing Herdi.app and taking the first approval

The fastest path is the macOS menu bar app, and the README frames it as a ten-second install: download Herdi.app from the latest release and drag it to Applications. The repository also gives a direct download command for version 0.8.0, whose release notes are titled "Usable on a phone".

curl -sL https://github.com/dcolinmorgan/herdr-remote/releases/download/v0.8.0/Herdi-0.8.0.dmg -o /tmp/Herdi.dmg && open /tmp/Herdi.dmg

That fetches the disk image and opens it, so the next thing you see is the standard macOS mount window with Herdi inside. Drag it to Applications and launch it. According to the README, the app picks up your local herdr agents automatically, so the first real use is simply watching the agent list populate and waiting for a blocked agent to appear, at which point the approval is a click in the menu bar rather than a return to the terminal. If nothing appears, the prerequisite to check is herdr 0.7 or later, which the requirements list. The menu bar app requires macOS 14 or newer.

Running the relay for phone and Telegram access

Remote access is a different install. On macOS or Linux the README gives two steps: install the push plugin, then start the relay from the relay directory.

herdr plugin install dcolinmorgan/herdr-push
cd herdr-remote/relay && ./start.sh

After that you open the hosted web app on your phone and paste the tunnel URL the launcher produced. The launcher binds to 127.0.0.1:8375 by default, which is local-only, and the README is explicit that you should set HERDR_RELAY_TOKEN before enabling a tunnel or binding beyond loopback. HERDR_REMOTES takes a comma-separated list of SSH targets for monitoring agents on other machines, and HERDR_BIN exists only for the case where herdr is not on PATH. For a setup that survives logout, relay/install-service.sh creates user services on macOS or Linux, enables relay authentication for new installs, and writes credentials to ~/.config/herdr-remote/secrets.env with mode 0600. On macOS you can confirm the services with launchctl print for com.herdr-remote.relay and com.herdr-remote.telegram. Windows users clone the repository, run herdr plugin link . followed by herdr plugin list to confirm the link, then run ./relay/start.ps1. The desktop client on Windows is a separate build: herdi-win with the .NET 8 SDK, producing dist/win-x64/Herdi.exe with a tray icon and toast notifications you can approve inline.

The Telegram bot, and where its trust boundary actually sits

The Telegram path is the most self-contained remote option, and the README makes a point that is easy to miss: Telegram connects to the relay over localhost, so this setup does not require Cloudflare Tunnel and the Mac only needs outbound internet access to Telegram. That removes the tunnel from the threat surface entirely, which is a better default than routing phone traffic through a public hostname. Setup runs through relay/install-service.sh, which prompts for Telegram configuration; you create the bot with @BotFather using /newbot, send /start to it, and select the discovered chat. The command set is small and operational: /agents lists everything with status, /read shows output, /reply reads and responds in one flow, /send pushes text to an agent, /trust trusts all tools for a blocked agent, /interrupt sends Ctrl+C, and /digest reports today's working time and block count. Notification replies are the interesting part. Finished and blocked notifications include an Open output & reply action, and replying directly to a notification sends a follow-up without going back to the agent list. For larger herds the pickers add Previous and Next buttons so every eligible agent stays reachable. The constraint to weigh is that this hands an approval channel to a third-party messaging service, and the README does not describe per-agent permissions or a confirmation step on /trust.

Origin checks on the relay, and what the security section leaves open

The relay validates WebSocket origins to block drive-by attacks from malicious webpages, and on a tokenless loopback relay only connections from localhost or 127.0.0.1 origins are accepted. If you front the relay with something like a Cloudflare Access hostname, you add it explicitly through HERDR_TRUSTED_ORIGINS.

export HERDR_TRUSTED_ORIGINS="https://herdr.example.com"

That is a sensible default and a real control, but it is also the whole of what the README documents on the subject. Origin validation is a browser-enforced check; it stops a page in your browser from opening a socket to your relay, and it is not authentication. Token auth is the other half, and the README notes that install-service.sh generates and persists a token for new managed installs while foreground use requires you to set HERDR_RELAY_TOKEN yourself. The gap is between those two: a foreground relay started without a token, then exposed through a tunnel, is protected by origin checks alone. The README does not document rate limiting, session expiry, or what happens to an established WebSocket when you rotate the token. Treat the token as mandatory the moment the relay is reachable from anywhere but loopback, and read SECURITY.md before you expose it.

Where herdr-remote is the wrong tool, and what to use instead

The clearest limitation is the missing Android client. The repository ships herdi-mac, herdi-win and herdi-ios. There is no Android app, and the README never claims one. Android users get the web app in a browser and nothing else, which is workable but is not the same as the native tray and menu bar clients. The second limitation is the platform floor: macOS 14 or newer for the menu bar app, Windows 10 1809 or newer for the tray app, Python 3.10 or newer with uv for the relay, TUI and bot, and cloudflared if you want remote access without Telegram. If you are on an older macOS release, the menu bar app is simply unavailable. The third is conceptual rather than technical. If your agents already run inside a terminal multiplexer you reach over SSH, that setup gives you the same read-and-interrupt capability with no relay, no token and no third-party messaging account. A tmux session over SSH is the honest alternative here: it is not a dashboard, it has no timeline and no one-tap approval in a notification, and it will not tell you that an agent blocked while you were away. But it also adds no listening port and no service to keep running. herdr-remote earns its place when you want the timeline and the notifications; if you only want to type into a pane, SSH already does that.

Maintenance cost, licence and what the repository does not say

The last push to the default branch was on 2026-09-16, and releases have come steadily through v0.8.0 on 2026-09-01, v0.7.5 on 2026-08-25 and a security release at v0.7.4 on 2026-08-17. The upgrade path has a wrinkle worth knowing: the macOS app is a drag-installed bundle, so updating means downloading a new disk image and replacing the app, while the relay and bot are Python code you run from a clone or a service install. Those two halves can drift, and the README does not document a version handshake between the app and the relay. On the service side, install-service.sh writes credentials to ~/.config/herdr-remote/secrets.env with mode 0600, which is where a token rotation lands; the README does not describe a rotation command, so rotating means editing that file and restarting the services. The licence field reports NOASSERTION, meaning GitHub could not classify the LICENSE file automatically. That is not a statement about what the licence permits, and it is not legal advice: open LICENSE and read it before shipping the relay inside anything commercial. The README also does not document rollback, so pin the release you install if you need a known-good version.

Editorial conclusion

Adopt it if you already run herdr agents on macOS and want status and approvals away from the terminal; the menu bar app alone needs no relay, account or config. Skip it if your agents live on a machine you cannot install a relay on, or if you need an Android client, since the repository ships herdi-mac, herdi-win and herdi-ios but no Android app. Before relying on remote access, verify what the README does not state: whether the relay survives a reboot outside the managed install, whether it reconnects after a dropped tunnel, and how the NOASSERTION licence in the repository actually applies to your use.

Frequently asked questions

Official sources

1. dcolinmorgan/herdr-remote on GitHub
2. Issues
3. Project website
4. README
5. Releases