Pair your agent
One command on the machine where Hermes runs pairs every agent you own with the Herald app. You need Hermes 0.20.0 or newer and the Herald app installed on your phone.
Quick install
curl -fsSL https://herald.eventhorizonlabs.xyz/install.sh | bash
Verify first (recommended)
Piping a script straight into bash means trusting whatever the server
returns at that moment. We publish a checksum so you don't have to:
curl -fsSL https://herald.eventhorizonlabs.xyz/install.sh -o herald-setup.sh
curl -fsSL https://herald.eventhorizonlabs.xyz/install.sh.sha256 -o herald-setup.sha256
sha256sum -c herald-setup.sha256 # must print: install.sh: OK
less herald-setup.sh # read it, it's ~450 lines of bash
bash herald-setup.sh
If sha256sum -c fails, stop — the file you received is not the file we
published.
Pin a version
install.sh always points at the latest release. For repeatable provisioning,
pin an immutable path instead:
curl -fsSL https://herald.eventhorizonlabs.xyz/v1.2.0/install.sh | bash
Released versions are never rewritten. A change ships as a new version, so a pinned URL keeps returning the same bytes forever.
See what it would do
Nothing is written until you're ready:
bash herald-setup.sh --dry-run
Every file write and config change is printed instead of applied.
What it does
- Finds Hermes and checks the version. Herald needs 0.20.0 or newer so it can speak as your agent, with its own name, instead of inventing a persona.
- Reviews your settings and offers to fix anything that would stop pairing, such as making all your profiles reachable rather than only the active one. It asks before changing anything.
- Lists your profiles so you pick which agents to add.
- Prepares API keys. Existing keys are reused, never rotated — re-running the installer will not break agents you already paired. Missing keys are minted per profile, because named profiles deliberately do not inherit the default profile's key.
- Shows one QR code carrying every selected agent. Scan it once in the app under Menu → Agents → Add another agent.
Flags
| Flag | Effect |
|---|---|
--dry-run | Print every change, write nothing |
--yes | Accept recommended config changes without prompting |
--one-per-agent | A separate QR per agent instead of one combined code |
--version | Print the installer version |
Non-interactive selection (needed when piping, since there's no keyboard):
curl -fsSL https://herald.eventhorizonlabs.xyz/install.sh | HERALD_PROFILES=all bash
curl -fsSL https://herald.eventhorizonlabs.xyz/install.sh | HERALD_PROFILES=quark,dobbo bash
Security
The QR code contains live API keys. They grant command execution on the machine running Hermes. Show it to your own camera — never a shared screen, a projector, or a screenshot in a chat.
Two things worth knowing:
- Keys are written to each profile's
.envwith mode600. - If your relay is configured over
http://, keys travel in cleartext on every request. The installer warns when it sees this. Usehttps://for anything beyond a trusted LAN.
After pairing
If the installer minted a key or changed config, restart the gateway so it loads them:
systemctl --user restart hermes-gateway
Run that from a normal shell — not from inside a Hermes session, which would terminate the command along with the gateway.
Troubleshooting
"Hermes not found" — the installer checks PATH, ~/.local/bin, the agent
venv, and /usr/local/bin. If yours is elsewhere, add it to PATH first.
"Hermes X is too old" — run hermes update. Older versions can't tell
Herald your agent's name.
An agent shows as hermes-agent instead of its name — that's the model id.
The real name comes from your agent's SOUL.md; if it has no
You are <Name>… line, there's no name to show.
A scanned agent won't connect — check the gateway was restarted after a key was minted, and that the URL is reachable from your phone. A LAN address only works on the same Wi-Fi; connect from anywhere for off-network use.