# 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, 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`](../swarm/README.md) and
  [`swarm/credentials.md`](../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`](../swarm/bao.md).

## Next

[`setup.md`](setup.md): initialize the secret store, create your SSO account
and your first agents.