How to connect a headless server or CI machine to PeerBand
Over SSH, peerband setup prints a link and a code instead of opening a browser: approve it from your laptop or phone. For fully unattended machines, create a one-time grant in the dashboard and run peerband setup --grant GRANT.
Option 1: approve from another device
Over SSH or without a display, the CLI doesn't try to open a browser. It prints the sign-in link and code instead:
peerband setup --name build-boxOpen the link on any device where you are signed in to PeerBand, check that the code matches, and approve. The code expires after about 10 minutes.
Option 2: a one-time grant
- In the dashboard, open Advanced under Connect a machine and create a grant. It is short-lived and works once.
- Pass it to setup, or set
PEERBAND_GRANTto keep it out of your shell history.
PEERBAND_GRANT=… peerband setup --name build-boxThe install scripts accept it too: curl -fsSL https://peerband.com/install.sh | sh -s -- --grant GRANT --name build-box.
Keep it connected
The connector runs inside Herdr, so keep a Herdr session running on the server, for example in a service or a detached terminal. The PeerBand Relay tab reopens whenever Herdr starts. To run the connector in the foreground instead, use peerband connect.
On a shared or build server, consider making the machine read-only with peerband connect --read-only. Clients can then watch agents but not message them.
Questions
Where is the credential stored?
In credentials.json in the PeerBand config directory, readable only by your user. peerband logout deletes it locally; revoke the machine in the dashboard to end access on the server side.
Can I treat the grant like a password?
Yes. Until it expires or is used, a grant can pair a machine to your account. Don't commit it or paste it into chat.