mara/hyperhive
mara/hyperhive
Watch
0
0
Fork
You've already forked hyperhive
 0
Code Activity

docs: sort the top-level directories into five sections by what the reader wants

Browse source 
Every docs directory moves under 1-getting-started, 2-handbook,
4-implementation or 5-project; the options reference (section 3) comes from
the website and has no directory here. trust-boundary stays whole under the
handbook for now. web-ui, swarm and tools split between handbook and
implementation, and the command-line references move to
2-handbook/reference. Links, path references in code and nix, and the docs
index follow the moves; no page content changes.
This commit is contained in:
iris 2026-11-06 18:30:12 +01:00 • committed by mara
commit 6739bb903d
2 changed files with 736 additions and 701 deletions
Download patch file Download diff file Expand all files Collapse all files

96
docs/1-getting-started/nixos.md Normal file
View file

@ -0,0 +1,96 @@
# Adding hyperhive to a NixOS flake
How to take a NixOS machine you already manage with a flake to the point
where `nixos-rebuild switch` brings hyperhive up. After the switch, continue
with [`setup.md`](setup.md) for the steps that stay by hand.
## 1 · Add the flake input
In your host's `flake.nix`, add hyperhive next to nixpkgs:
```nix
inputs = {
nixpkgs.url = "github:NixOS/nixpkgs/nixos-26.05";
hyperhive.url = "git+https://forge.darkest.space/hyperhive/hyperhive";
};
```
Add `hyperhive` to the arguments of `outputs` too, so the next step can
reach it.
## 2 · Import the module
Import `hyperhive.nixosModules.default`. It's the whole host stack in one
import: the hive (`hive-c0re` and its gateway, bridge and resolver) and every
swarm service. It also wires in hyperhive's own packages, so you set no
package options.
Importing `default` turns nothing on. Every service stays off until you
enable it, and a host that imports it and enables nothing evaluates without
any of the options below.
```nix
nixosConfigurations.my-host = nixpkgs.lib.nixosSystem {
system = "x86_64-linux";
modules = [
hyperhive.nixosModules.default
{ services.hyperhive = { /* step 3 */ }; }
];
};
```
`claude-code` is unfree. Hyperhive scopes the allowance to itself, and only
for agents that run claude (`services.hyperhive.agent.runtime = "claude"`, the
default), so you don't set `allowUnfree`.
## 3 · Set the required options
All of these live under `services.hyperhive`. Evaluation fails with a message
naming the option when one is missing. None of them has a default, because a
guessed value here is a wrong hostname that evaluates cleanly and deploys.
| option | what it does | without it |
| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------ |
| `deploy.hive-controller.enable` | Runs a hive on this host: `hive-c0re`, which owns every agent container, plus the bridge and gateway for the agents. | No agents can run here. Leave it off on a host that only runs shared swarm services. |
| `swarm.domain` | The swarm's DNS domain. Each hive lives in a sub-domain of it. Use the same value on every host of the swarm. | Eval fails on any host that runs a hyperhive service. |
| `deploy.hive-controller.hiveName` | This hive's label inside the swarm, and the first part of its address, `<hiveName>.<swarm.domain>`. It's also the hive's identity in the secret store. | Eval fails on a host that runs a hive. |
| `swarm.hives` | The directory of every hive in the swarm, this one included. Entries need no fields: each `domain` defaults to `<name>.<swarm.domain>`. Every host of the swarm shares one identical copy. | Eval fails, naming the missing entry for `hiveName`. |
An all-local swarm, with every shared service and the hive on this one box,
adds one switch:
| option | what it does |
| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `deploy.singleHostSwarm` | Turns on the shared swarm services, the swarm controller, and `/etc/hosts` entries so the swarm's names resolve on the box itself. Leave it off if the services run on other hosts. |
The smallest working config, as in the README's
[all-local quick start](../../README.md#quick-start-an-all-local-swarm):
```nix
services.hyperhive = {
deploy.singleHostSwarm = true;
deploy.hive-controller.enable = true;
swarm.domain = "hive.example";
deploy.hive-controller.hiveName = "pr1ma";
swarm.hives.pr1ma = { };
};
```
Run `nixos-rebuild switch --flake .#my-host`. The swarm UI then answers at
`https://<swarm.domain>/`.
## Everything else is optional
Leave the other options at their defaults until you need them:
- Spreading a swarm over more than one host, and the credentials a split swarm
needs: [`swarm/README.md`](../2-handbook/swarm/README.md) and
[`swarm/credentials.md`](../2-handbook/swarm/credentials.md).
- Every option, with its type and default:
[the options reference](https://hyperhive.darkest.space/options/).
- The secret store's seal and the granter: [`swarm/bao.md`](../4-implementation/swarm/bao.md).
## Next
[`setup.md`](setup.md): initialize the secret store, create your SSO account
and your first agents.

138
docs/1-getting-started/setup.md Normal file
View file

@ -0,0 +1,138 @@
# First-run setup
What's left to do by hand after the first `nixos-rebuild switch` of the
[README's all-local quick start](../../README.md#quick-start-an-all-local-swarm)
— from a freshly built host to your first agent. Do the steps in order;
each one assumes the ones before it. Step 0, the NixOS flake, module and
required options, is [`nixos.md`](nixos.md).
Every command runs as **root on the host**.
> **Not all-local?** Each step says which host it runs on. A split swarm
> also has credentials you can't generate where they're read — each
> host's mTLS identity at the secret store. Read [`swarm/credentials.md`](../2-handbook/swarm/credentials.md) first; it
> says which files you place, and where.
## 1 · Secret store
_On the host running `swarm-bao`._ Everything else fetches its credentials
from the store, so it comes first.
```bash
sudo bao operator init # keep the keys it prints and the root token OFF this host
```
Then bootstrap the **granter**, the one principal that writes every
`swarm-*` policy and role from then on. This is the only step that needs
the root token:
```bash
sudo -i
read -rs BAO_TOKEN && export BAO_TOKEN # paste the root token from `bao operator init`
bao policy write bao-bootstrap /etc/hyperhive/bao-bootstrap-policy.hcl
bao token create -policy=bao-bootstrap -ttl=24h -orphan -display-name=bao-bootstrap -field=token \
| install -D -m 0600 /dev/stdin /var/lib/swarm-bao-bootstrap/grant.token
unset BAO_TOKEN
systemctl restart swarm-bao-granter-role
```
Check `systemctl status swarm-bao-granter-role` logs
`Uploaded policy: bao-granter`, then restart the granting units that
failed while they waited. The granter unit deletes the token itself after a
successful run:
```bash
systemctl reset-failed 'swarm-bao-*-policy.service' swarm-bao-agent-pki.service
systemctl restart 'swarm-bao-*-policy.service' swarm-bao-agent-pki.service
systemctl status swarm-bao-controller-policy # Uploaded policy, Data written to: auth/cert/certs/swarm-controller
```
⏱️ A first attempt right after a rebuild may fail with `local node not
active` while the store comes up; the units retry every 30s for a day.
With the default `pkcs11` seal the store unseals itself from here on. With
`deploy.bao.seal = "shamir"`, run `bao operator unseal` after every restart.
What the granter is, why it's root-equivalent, and the store's TLS:
[`swarm/bao.md`](../4-implementation/swarm/bao.md).
## 2 · Your SSO account
_On the host running authelia._ Until this runs, `auth.<swarm.domain>` serves
a login page that refuses everyone: its only subject is a placeholder marked `disabled`.
```bash
swarmctl user add mara --display-name Mara --email mara@example.com --group admins
```
It prints a generated password once — record it. Keep both flags:
- **`--group admins`** — the swarm UI and other operator surfaces gate on
it. Without it you log in fine and are then refused.
- **`--email`** — the forge won't create an account without one.
Fix either afterwards with `swarmctl user update mara --add-group admins
--email …`. Details: [`swarm/sso.md`](../2-handbook/swarm/sso.md).
## 3 · Swarm UI login
Open `https://<swarm.domain>/` and sign in with the account from step 2. The
name resolves on the box itself through `/etc/hosts`; from anywhere else it
needs a real DNS record. → [`swarm/ui.md`](../2-handbook/swarm/ui.md)
Signing in to the forge once through SSO creates your forge account under the
same username. Then, _on the swarm-controller's host_:
```bash
swarmctl forge make-admin mara
```
If the forge already has a local account with your username, the first
SSO login asks for its forge password once, to link the two.
Agents learn your pronouns from the **Pronouns** field of your forge profile
settings. Leave it empty and agents refer to you by name only.
## 4 · Clippy, then ruth
hive-c0re creates no agent at startup. On the swarm UI's start page, the
paperclip (clippy, the setup assistant) offers to set up ruth, the manager
agent. Select it: it opens the create form with `ruth` filled in and the
`manage_root_agent` permission checked. That permission mounts the other
agents into her container so she can recover them. The form declares her,
creates her config repo and deploys her to the hive you pick.
The swarm declares a new agent `paused`, so without a further step ruth runs
but drives no turns. Open `/agents` in the swarm UI and set her `up` from her
card.
On a hive that already has a ruth container from an earlier release, create
her once the same way, so that her config repo and store identity exist. The
container keeps starting with the hive meanwhile.
## 5 · Ask ruth for further help
From here on, ask ruth. Open her card on `/agents` in the swarm UI and use the
message box under her terminal. She is the manager agent: her MCP surface is the
privileged one that configures agents, and she can recover the others. Changes to
an agent's config arrive as PRs you merge. → [`agent-lifecycle/agent-roster.md`](../2-handbook/agent-lifecycle/agent-roster.md)
To create an agent yourself instead, use the swarm UI, or:
```bash
swarmctl agent create iris --hive pr1ma
```
The controller provisions iris's identity, forge user and config repo
(`agent-configs/iris`, from the default template), then has the hive build
and start the container. It returns once the scheduler queues the job — watch the
swarm UI's job view for progress.
Later config changes are PRs on `agent-configs/iris`; you merge them on the
forge, and the merge deploys them. →
[`agent-lifecycle/config-changes.md`](../2-handbook/agent-lifecycle/config-changes.md#config-changes)
## After setup: use the swarm UI
Day-to-day operation happens in the swarm UI at `https://<swarm.domain>/`:
agents, hives, jobs and messages. Swarm-level operations take over from the
per-hive dashboard and `hivectl`. → [`swarm/ui.md`](../2-handbook/swarm/ui.md)