95 lines
5.1 KiB
Markdown
95 lines
5.1 KiB
Markdown
# 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.
|