From 86ec5d12c3a0032e8a5775e7b9838ee85faeb94e Mon Sep 17 00:00:00 2001 From: atlas Date: Wed, 4 Nov 2026 19:51:17 +0100 Subject: [PATCH] docs: add a getting-started page for the nixos flake, module import and required options --- docs/README.md | 2 + docs/getting-started/nixos.md | 95 +++++++++++++++++++++++++++++++++++ docs/getting-started/setup.md | 3 +- 3 files changed, 99 insertions(+), 1 deletion(-) create mode 100644 docs/getting-started/nixos.md diff --git a/docs/README.md b/docs/README.md index 7aa65bc6..8caf44da 100644 --- a/docs/README.md +++ b/docs/README.md @@ -11,6 +11,8 @@ declarations. ## Getting started +- **Adding hyperhive to a NixOS flake? Which options does it need?** → + [`getting-started/nixos.md`](getting-started/nixos.md). - **Bringing a fresh swarm online?** → [`getting-started/setup.md`](getting-started/setup.md) (the hand steps after the first switch). - **What does the dashboard look like, and how to use it?** → diff --git a/docs/getting-started/nixos.md b/docs/getting-started/nixos.md new file mode 100644 index 00000000..48685247 --- /dev/null +++ b/docs/getting-started/nixos.md @@ -0,0 +1,95 @@ +# 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, `.`. 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 `.`. 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:///`. + +## 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. diff --git a/docs/getting-started/setup.md b/docs/getting-started/setup.md index 3e955439..4ae6756f 100644 --- a/docs/getting-started/setup.md +++ b/docs/getting-started/setup.md @@ -5,7 +5,8 @@ What's left to do by hand after the first `nixos-rebuild switch` of the — from a freshly built host to your first agent. Do the steps in order; each one assumes the ones before it. -Every command runs as **root on the host**. +Every command runs as **root on the host**. The flake input, module import +and required options are in [`nixos.md`](nixos.md). > **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