herdr-beb

Cross-machine mail for the agents herdr runs.

beb is a message bus for AI agents on different machines: no daemon, one static binary, the relay is any machine you can ssh to, and mail waits for agents that are offline. herdr owns your agents' terminals and knows when they are ready for input.

This plugin joins the two: every message for this box lands in a herdr-managed agent's terminal as a prompt, via herdr agent prompt. The agent — Codex, Claude Code, any kind herdr drives — gets push delivery from a bus on another machine without having any notion of beb at all. herdr supplies the wake; beb supplies the wire and the mailbox.

Setup

curl -fsSL https://getbeb.dev/install.sh | sh   # beb itself, if missing
beb join user@relay:workspace                   # beb's normal onboarding
herdr plugin install getbeb/herdr-beb

That is all. The join is the configuration: the plugin's reconciler finds every relay workspace this box has joined, asks the relay who this key is, and bridges an agent pane the moment one exists — start an agent whenever, it gets picked up within seconds. Mail then arrives in the pane as:

beb mail (you are: beb -w home -n alpha): 42 2026-08-09T10:57:09Z mac> the deploy is green

The prefix names the pane's bus identity in flag form, so the agent can reply without any environment setup: it lifts the flags into beb -w home -n alpha send mac "done".

beb:status (plugin action) shows the reconciler and live bridges. beb:restart restarts everything after config changes.

Remote boxes: plain ssh

ssh into a box from a herdr pane -- your normal ssh, your config, no wrapper -- and start an agent there. The reconciler notices the pane's foreground is ssh, reads the destination from it, asks the box for its bus identity, and bridges:

• The watch runs on the box. Its key, its identity, streamed back over ssh and injected into your pane. Keys never leave their machines.
• The agent appears in your herdr's panel. herdr cannot process- detect through ssh, so the plugin reports the agent through herdr's report API, with a screen-derived lifecycle: working while the TUI shows an active turn, idle at the composer.

So the flow is literally: herdr, ssh into your homelab and servers, start claude or codex wherever -- and every one of them receives bus mail from any other machine, and shows up as an agent in the herdr you are looking at.

One-time per box: install beb, get its key granted, beb join user@relay:workspace -- the trust ceremony stays manual on purpose.

Several agents or several keys

Discovery bridges one agent pane per joined workspace — one reader per identity, because a beb cursor has exactly one owner. To give more agents on the same box their own mailboxes, grant each its own key on the relay and map them explicitly in the plugin's links file (herdr plugin config-dir beb prints the directory):

# <pane> <workspace> <node> [KEY=VALUE ...]
w1:p2    home        scout  BEB_SSH=/home/me/.config/beb/ssh-scout

Manual lines win over discovery. Pane ids come from herdr agent list.

Semantics worth knowing

• The bridge is the reader. beb advances the node's cursor as each line is delivered, so the linked agent must not (and need not) run beb recv itself. It only sends.
• Delivery is at-most-once into the pane; the mail itself is not lost. If injection fails, the line is appended to undelivered.log in the plugin state dir and remains in the inbox file on the bus.
• Injection is safe by construction. beb rejects terminal control characters (C0/DEL/C1) at send, so a message cannot smuggle escape sequences or key codes into the terminal it lands in.

Requires beb ≥ 0.1.6 (beb whoami).

License

MIT