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

Central config

The hive stores one versioned config document for the fleet (see the "Central config" section of docs/config.md for the document shape, validation rules and the fail scenarios). Operational notes:

• Publish:

  curl -X PUT http://127.0.0.1:8087/config \
    -H "X-Admin-Key: $(cat .hive-admin-key)" \
    -H 'Content-Type: application/json' \
    -d '{"layers":[{"name":"global","config":{"settings":{"llm_complete_timeout":90}}}],"note":"timeouts"}'

  layers: [] is a real publish: it clears the fleet overlay and every instance returns to its local config.

• Watch it land: GET /config/status after a publish. behind names the machines still on an older effective hash; each has its last ack and the fields that need a restart. A rejected ack means that instance refused the document — validation errors are in last_error, and the instance is still running its previous config.

• Retry: the hive pings behind instances every HIVE_NOTIFY_RETRY_SEC and on every announce reply, so a machine that was off catches up by itself. There is nothing to do manually.
• Rollback is a forward publish of an old document. History is never rewritten, including for a document that turned out to be bad.

Trust model

• The swarm key can read the config, therefore it can read whatever secrets the document holds. That is the price of a fleet-wide key rotation without per-instance setup; keep port 8087 on the LAN and treat the key as a secret on the same level as the config itself.
• Publishing needs the admin key (HIVE_ADMIN_KEY_FILE, default .hive-admin-key, also HIVE_ADMIN_KEY env) or a loopback connection (HIVE_ALLOW_LOCAL_ADMIN=0 turns even that off). Once a key is configured it is required from every address, loopback included.
• hive.db contains the config history with secrets. Back it up like a credential store (0600) and do not copy it around.

Configuration (env vars)

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):

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).