hyperhive/docs/getting-started/nixos.md

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 for the steps that stay by hand.

1 · Add the flake input

In your host's flake.nix, add hyperhive next to nixpkgs:

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.

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:

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 and swarm/credentials.md.
• Every option, with its type and default: the options reference.
• The secret store's seal and the granter: swarm/bao.md.

Next

setup.md: initialize the secret store, create your SSO account and your first agents.