hive — the swarm address book

A tiny standalone service for the main server. Every Navi instance in the swarm announces itself here every couple of minutes (name, instance id, address, machine info), and agents ask the book who is currently alive and where. The free-form meta field is the seed of a future mini knowledge base about the fleet (host, OS, cores, RAM — whatever the machine reports).

The hive is not part of the Navi server and never starts by default — install.sh installs nothing hive-related. It runs on one machine with a stable address (e.g. the main server: local 192.168.1.168:8087).

Run it

On the main server, from the repo root (same clone, same venv — zero extra dependencies):

# quick check
.venv/bin/uvicorn hive.app:app --host 0.0.0.0 --port 8087

# as a systemd unit:
sed -e "s|EDIT_ME|$HOME|g" hive/hive.service | sudo tee /etc/systemd/system/hive.service
sudo systemctl daemon-reload
sudo systemctl enable --now hive

--host 0.0.0.0 is required so other machines on the LAN can announce.

Auth

Everything except /health requires the shared swarm key: an X-Swarm-Key header matching .swarm-key in the working directory. .swarm-key.previous is also accepted — that is the rotation window: put the new key in .swarm-key, move the old one to .swarm-key.previous, then delete the old file once every navi has picked up the new key.

Endpoints

Endpoint	Auth	What
`GET /health`	none	liveness + machine count
`POST /announce`	swarm key	upsert: `{name, instance_id, version, port, meta}` — the source IP is recorded as the machine's host (reliable on floating-IP networks), `port` comes from the payload
`GET /peers`	swarm key	`{peers: [{name, instance_id, host, port, address, online, last_seen, first_seen, meta}], ttl_sec}` — `online` = announced within the TTL

Configuration (env vars)

Var	Default	Meaning
`HIVE_KEY_FILE`	`.swarm-key`	current swarm key file
`HIVE_DB`	`hive.db`	SQLite file
`HIVE_TTL_SEC`	`300`	a machine is `online` if it announced within this window

Navi side

A Navi announces itself when .env sets HIVE_URL (e.g. HIVE_URL=http://192.168.1.168:8087) and .swarm-key exists next to .env (install.sh generates one; copy the same file to every machine and the hive host to form a swarm). No HIVE_URL — the navi is standalone and keeps working; the registry being down is also non-blocking: the agent just gets a context note that the book is unreachable.

Peer channel (stage 2)

Navi instances talk to each other directly — the hive is only the address book, never on the message path. Each navi exposes on its API port (8099):

Endpoint	Auth	Purpose
`GET /peer/hello`	none	name + uuid prefix + version (discovery ping)
`GET /peer/status`	PSK	identity, uptime, machine facts, its hive view
`POST /peer/ask`	PSK	ask a peer a question; a one-shot agent run under `PEER_ASK_PROFILE` answers

Agents use the built-in peer tool (list / status / ask). Loop safety is deterministic: the answering agent is created with peer excluded, so asks cannot recurse; an ask claiming to come from our own uuid is refused (409). Every ask is audited on both sides via structlog (peer.ask_sent / peer.ask_received / peer.ask_answered).