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

```bash
# 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.