README.md

@@ -77,7 +77,7 @@ Minimal `flake.nix` for a host that runs hive-c0re:
       modules = [
         hyperhive.nixosModules.default  # hive-c0re + hive-forge + hive-gateway in one import
         ({ ... }: {
-          services.hyperhive.deploy.hive-controller.enable = true;
+          services.hyperhive.enable = true;
           # services.hyperhive.c0re.operatorPronouns = "they/them";  # default: "she/her"
 
           # ... rest of your host config

docs/networking/network.md

@@ -90,7 +90,7 @@ listener on `bridgeIp` is on the host's bridge interface.
 ```nix
 {
   services.hyperhive = {
-    deploy.hive-controller.enable = true;
+    enable = true;
     hiveName = "pr1ma";
     swarm.domain = "darkest.space";
     swarm.hives.pr1ma = { };          # -> domain = pr1ma.darkest.space

docs/networking/snapshot-store.md

@@ -38,7 +38,7 @@ The store host is a swarm member like any other: it gets an entry in
 [swarm/](../swarm/README.md) for the mesh itself.
 
 Note that `deploy.wireguard.enable` gates the mesh, **not**
-`deploy.hive-controller.enable` --- a store host runs no hive and would otherwise get no
+`c0re.enable` --- a store host runs no hive and would otherwise get no
 `wg-hive` interface at all.
 
 ## Pointing a hive at it

docs/swarm/README.md

@@ -299,9 +299,9 @@ migrating agent keeps one unbroken incremental chain. See
 
 `services.hyperhive.deploy.swarm-controller.enable` runs the `swarm-controller`
 daemon on this host. **Off by default and deliberately not derived from
-`services.hyperhive.deploy.hive-controller.enable`**: a swarm has one
-controller, so enabling it states a fact about swarm topology, not about
-whether this host runs a hive. Every hive runs `hive-c0re` (the agents on that host); one
+`services.hyperhive.enable`**: a swarm has one controller, so enabling it
+is a statement about swarm topology, not about whether the operator has
+installed hyperhive. Every hive runs `hive-c0re` (the agents on that host); one
 hive additionally runs this (what's true across hives).
 
 What it serves, why it's a unix socket rather than a port, and the

flake.nix

@@ -119,7 +119,7 @@
           # an operator override still wins. Intended usage:
           #
           #   imports = [ hyperhive.nixosModules.default ];
-          #   services.hyperhive.deploy.hive-controller.enable = true;
+          #   services.hyperhive.enable = true;
           #
           default =
             { lib, pkgs, ... }:

nix/docs/default.nix

@@ -54,7 +54,7 @@ let
           };
           boot.loader.grub.enable = false;
           system.stateVersion = "25.11";
-          services.hyperhive.deploy.hive-controller.enable = lib.mkForce false;
+          services.hyperhive.enable = lib.mkForce false;
           services.hyperhive.deploy.matrix.enable = lib.mkForce false;
         }
       )

nix/host-modules/default.nix

@@ -1,8 +1,7 @@
 # The full hyperhive host stack, pulled together in one place — this
 # is what the flake exports as `nixosModules.default` (wrapped with
 # the package/source wiring; see flake.nix). One import covers
-# everything; `services.hyperhive.deploy.hive-controller.enable = true`
-# runs a hive on this host.
+# everything; `services.hyperhive.enable = true` turns the stack on.
 #
 # Every swarm needs the forge — hive-c0re mirrors every agent's applied
 # config repo into it and it's the canonical store for the meta flake
@@ -10,7 +9,7 @@
 # runs it (derived from `deploy.allSwarmServices`, see
 # ./swarm-required-services.nix). hive-matrix is opt-in (off by default). All
 # subsystems rely on `services.hyperhive.domain`, which is required
-# (asserted in hive-network.nix) wherever this host runs a hive.
+# (asserted in hive-network.nix) whenever hyperhive is enabled.
 {
   imports = [
     ./hyperhive.nix

nix/host-modules/deploy.nix

@@ -119,15 +119,6 @@ in
       [ "services" "hyperhive" "swarm" "statusPublish" "clientSecretFile" ]
       [ "services" "hyperhive" "deploy" "hive-controller" "statusPublish" "clientSecretFile" ]
     )
-    # Both old spellings of "run a hive here" forward to the one switch.
-    (lib.mkRenamedOptionModule
-      [ "services" "hyperhive" "enable" ]
-      [ "services" "hyperhive" "deploy" "hive-controller" "enable" ]
-    )
-    (lib.mkRenamedOptionModule
-      [ "services" "hyperhive" "c0re" "enable" ]
-      [ "services" "hyperhive" "deploy" "hive-controller" "enable" ]
-    )
     (lib.mkRenamedOptionModule
       [ "services" "hyperhive" "swarm" "otel" "enable" ]
       [ "services" "hyperhive" "deploy" "swarm-otel" "enable" ]
@@ -461,9 +452,9 @@ in
         Run the swarm's metrics UI on this host.
 
         Off by default and not derived from
-        {option}`services.hyperhive.deploy.hive-controller.enable`: a swarm
-        has one Grafana, so running it is a decision about this host rather
-        than about whether it runs a hive.
+        {option}`services.hyperhive.enable`: a swarm has one Grafana, so
+        running it is a decision about this host rather than about
+        whether hyperhive is installed.
       '';
     };
 
@@ -579,21 +570,6 @@ in
       '';
     };
 
-    hive-controller.enable = lib.mkOption {
-      type = lib.types.bool;
-      default = false;
-      example = true;
-      description = ''
-        Run a hive on this host: the `hive-c0re` coordinator that owns every
-        agent container here, its `hive-priv` helper, and the bridge,
-        resolver and gateway the agents hang off.
-
-        Every hive turns this on. A host that only runs the swarm's shared
-        services ({option}`services.hyperhive.deploy.allSwarmServices`)
-        leaves it off.
-      '';
-    };
-
     swarm-controller.enable = lib.mkOption {
       type = lib.types.bool;
       default = false;
@@ -601,9 +577,9 @@ in
         Run the swarm-controller daemon on this host.
 
         Off by default and deliberately not derived from
-        {option}`services.hyperhive.deploy.hive-controller.enable`: a swarm
-        has one controller, so running it is a decision about this host
-        rather than about whether it runs a hive.
+        {option}`services.hyperhive.enable`: a swarm has one controller,
+        so running it is a decision about this host rather than about
+        whether hyperhive is installed.
       '';
     };
 

nix/host-modules/glue-bao-readers-policy-order.nix

@@ -31,21 +31,22 @@ let
   readersHere = {
     # ./glue-matrix-bao-token.nix
     swarm-bao-matrix-token =
-      havePair baoDeploy.matrixTokenClientCertFile baoDeploy.matrixTokenClientKeyFile
+      hyperhiveCfg.enable
+      && havePair baoDeploy.matrixTokenClientCertFile baoDeploy.matrixTokenClientKeyFile
       && deployCfg.matrix.enable;
     # ./glue-queue-agent-credential.nix
     swarm-bao-queue-agent =
-      deployCfg.hive-controller.enable
+      hyperhiveCfg.enable
       && havePair baoDeploy.queueAgentClientCertFile baoDeploy.queueAgentClientKeyFile;
     # ./swarm-grafana.nix
-    swarm-bao-grafana-oidc = deployCfg.grafana.enable;
+    swarm-bao-grafana-oidc = hyperhiveCfg.enable && deployCfg.grafana.enable;
     # ./swarm-otel.nix
     swarm-bao-otel-oidc =
       deployCfg.swarm-otel.enable
       && havePair baoDeploy.otelOidcClientCertFile baoDeploy.otelOidcClientKeyFile;
     # ./swarm-bao.nix: its block is gated on the store, which `orderAfterPolicy`
     # already checks.
-    swarm-bao-forwarder-oidc = true;
+    swarm-bao-forwarder-oidc = hyperhiveCfg.enable;
     # ./swarm-nats.nix: the queue's TLS leaf, not a secret, but the same wait.
     swarm-bao-nats-tls = deployCfg.nats.enable;
   };

nix/host-modules/glue-bao-tls.nix

@@ -43,10 +43,9 @@ let
 
   # What a reader calls itself to the store. The hive's name, because a bao
   # cert-auth role matches on the CN — this is an interface, not a label.
-  # No fallback: `hiveName` is asserted set wherever `deploy.bao.enable` is
-  # (./hyperhive.nix), the same condition this file's `config` is gated on. A
-  # fallback here reads as a second supported spelling and there is no such
-  # thing.
+  # No fallback: `hiveName` is asserted set for every hyperhive host, which is
+  # the same condition this file's `config` is gated on. A fallback here reads
+  # as a second supported spelling and there is no such thing.
   clientCn = hyperhiveCfg.hiveName;
 
   # $1 dir  $2 basename  $3 CN  $4 SAN or ""  $5 EKU
@@ -72,7 +71,7 @@ let
   '';
 in
 {
-  config = lib.mkIf deployCfg.bao.enable {
+  config = lib.mkIf (hyperhiveCfg.enable && deployCfg.bao.enable) {
     services.hyperhive.deploy.bao = {
       serverCertFile = lib.mkDefault "${pkiDir}/server.pem";
       serverKeyFile = lib.mkDefault "${pkiDir}/server-key.pem";

nix/host-modules/glue-controller-bao-identity.nix

@@ -32,7 +32,7 @@ let
   pkiDir = if haveMintedPki then builtins.dirOf baoDeploy.clientCertFile else null;
 in
 {
-  config = lib.mkIf (deployCfg.swarm-controller.enable && haveMintedPki) {
+  config = lib.mkIf (hyperhiveCfg.enable && deployCfg.swarm-controller.enable && haveMintedPki) {
     services.hyperhive.deploy.swarm-controller = {
       baoClientCertFile = lib.mkDefault "${pkiDir}/controller.pem";
       baoClientKeyFile = lib.mkDefault "${pkiDir}/controller-key.pem";

nix/host-modules/glue-forge-oidc-client.nix

@@ -24,7 +24,7 @@ let
   forgeCfg = hyperhiveCfg.swarm.forge;
 in
 {
-  config = lib.mkIf deployCfg.authelia.enable {
+  config = lib.mkIf (hyperhiveCfg.enable && deployCfg.authelia.enable) {
     # One declaration, two readers. The forge knows its own callback URL;
     # making the operator restate it in authelia's client list would be a
     # second source of truth for a string whose mismatch is a silent

nix/host-modules/glue-grafana-oidc-client.nix

@@ -32,7 +32,7 @@ let
   grafanaCfg = hyperhiveCfg.swarm.grafana;
 in
 {
-  config = lib.mkIf deployCfg.authelia.enable {
+  config = lib.mkIf (hyperhiveCfg.enable && deployCfg.authelia.enable) {
     # One declaration, two readers. Grafana's callback URL is format-locked to
     # its own root URL, and the read-only option it is taken from is where that
     # format is spelled — restating it here would be a second source of truth

nix/host-modules/glue-matrix-bao-token.nix

@@ -69,8 +69,7 @@ let
   # pieces; this literal is the nix half of that one agreement.
   #
   # `hiveName` has no fallback here for the reason ./glue-bao-tls.nix gives at
-  # its own use of it: it is asserted set on every host that runs the
-  # homeserver.
+  # its own use of it: it is asserted set for every hyperhive host.
   tokenPath = "secret/swarm/hives/${hyperhiveCfg.hiveName}/matrix/appservice-token";
 
   # A literal, not an option — ./hive-matrix.nix names its container
@@ -95,7 +94,7 @@ in
     # is a hive that has no store, which is supported. So this one additionally
     # requires `hiveReaderIdentity`: the host demonstrably reads the store, and
     # named every option but this pair.
-    (lib.mkIf (deployCfg.matrix.enable && hiveReaderIdentity) {
+    (lib.mkIf (hyperhiveCfg.enable && deployCfg.matrix.enable && hiveReaderIdentity) {
       assertions = [
         {
           assertion = haveClientIdentity;
@@ -125,7 +124,7 @@ in
       ];
     })
 
-    (lib.mkIf (haveClientIdentity && deployCfg.matrix.enable) {
+    (lib.mkIf (hyperhiveCfg.enable && haveClientIdentity && deployCfg.matrix.enable) {
       # Same rule as the unit's own gate: this reader exists on a host that has a
       # client identity and a homeserver, which is not every host that runs the
       # store, so the store's module cannot name it.

nix/host-modules/glue-matrix-ctl-bao-identity.nix

@@ -31,7 +31,7 @@ let
   pkiDir = if haveMintedPki then builtins.dirOf baoDeploy.clientCertFile else null;
 in
 {
-  config = lib.mkIf (deployCfg.matrix.enable && haveMintedPki) {
+  config = lib.mkIf (hyperhiveCfg.enable && deployCfg.matrix.enable && haveMintedPki) {
     services.hyperhive.deploy.matrix = {
       ctlBaoClientCertFile = lib.mkDefault "${pkiDir}/matrix-ctl.pem";
       ctlBaoClientKeyFile = lib.mkDefault "${pkiDir}/matrix-ctl-key.pem";

nix/host-modules/glue-nats-bao-identity.nix

@@ -31,7 +31,7 @@ let
   pkiDir = if haveMintedPki then builtins.dirOf baoDeploy.clientCertFile else null;
 in
 {
-  config = lib.mkIf (deployCfg.nats.enable && haveMintedPki) {
+  config = lib.mkIf (hyperhiveCfg.enable && deployCfg.nats.enable && haveMintedPki) {
     services.hyperhive.deploy.nats = {
       baoClientCertFile = lib.mkDefault "${pkiDir}/nats.pem";
       baoClientKeyFile = lib.mkDefault "${pkiDir}/nats-key.pem";

nix/host-modules/glue-queue-agent-credential.nix

@@ -20,10 +20,10 @@
 # into one that is refused, which reaches the agent as a timeout.
 #
 # 📌 This runs wherever a client identity is configured, NOT only where the
-# store is — the rule ./glue-matrix-bao-token.nix states in full — and
-# wherever this host runs a hive (`deploy.hive-controller.enable`): the
-# credential is for the agents hive-c0re creates here at runtime, and the unit
-# writes under hive-c0re's own state directory.
+# store is — the rule ./glue-matrix-bao-token.nix states in full. There is no
+# "this hive runs agents" condition to gate it on as well: agent containers
+# are created at runtime by hive-c0re, so every hyperhive host is a host that
+# may run one.
 {
   pkgs,
   lib,
@@ -74,8 +74,7 @@ let
   # one agreement.
   #
   # `hiveName` has no fallback here for the reason ./glue-bao-tls.nix gives at
-  # its own use of it: it is asserted set wherever
-  # `deploy.hive-controller.enable` is.
+  # its own use of it: it is asserted set for every hyperhive host.
   credentialPath = "secret/swarm/hives/${hyperhiveCfg.hiveName}/queue/agent";
 in
 {
@@ -111,11 +110,11 @@ in
     #
     # Shaped after ./swarm-grafana.nix's `haveClientIdentity` assertion — the
     # same refusal, named to this principal's own pair. Where Grafana's gate
-    # is `deploy.grafana.enable`, this reader's is the hive's own: every hive
-    # runs one for its own agents, so on a hive, reading the store at all is
-    # what asks for it. Hence `hiveReaderIdentity` — a host holding no hive
-    # leaf has no store to read and nothing is missing.
-    (lib.mkIf (deployCfg.hive-controller.enable && hiveReaderIdentity) {
+    # is `deploy.grafana.enable`, this reader has no toggle of its own to
+    # check: every hive runs one for its own agents, so reading the store at
+    # all is what asks for it. Hence `hiveReaderIdentity` alone — a host
+    # holding no hive leaf has no store to read and nothing is missing.
+    (lib.mkIf (hyperhiveCfg.enable && hiveReaderIdentity) {
       assertions = [
         {
           assertion = haveClientIdentity;
@@ -150,7 +149,7 @@ in
       ];
     })
 
-    (lib.mkIf (deployCfg.hive-controller.enable && haveClientIdentity) {
+    (lib.mkIf (hyperhiveCfg.enable && haveClientIdentity) {
       # Same rule as the unit's own gate: this reader exists on any host holding
       # a client identity, which is not every host that runs the store, so the
       # store's module cannot name it.

nix/host-modules/glue-secret-publisher-bao-identity.nix

@@ -31,7 +31,9 @@ let
   pkiDir = if haveMintedPki then builtins.dirOf baoDeploy.clientCertFile else null;
 in
 {
-  config = lib.mkIf (deployCfg.swarm-secret-publisher.enable && haveMintedPki) {
+  config =
+    lib.mkIf (hyperhiveCfg.enable && deployCfg.swarm-secret-publisher.enable && haveMintedPki)
+      {
         services.hyperhive.deploy.swarm-secret-publisher = {
           baoClientCertFile = lib.mkDefault "${pkiDir}/secret-publisher.pem";
           baoClientKeyFile = lib.mkDefault "${pkiDir}/secret-publisher-key.pem";

nix/host-modules/glue-services-issuer-bao-identity.nix

@@ -34,7 +34,7 @@ let
   pkiDir = if haveMintedPki then builtins.dirOf baoDeploy.clientCertFile else null;
 in
 {
-  config = lib.mkIf haveMintedPki {
+  config = lib.mkIf (hyperhiveCfg.enable && haveMintedPki) {
     services.hyperhive.deploy.hive-controller.tls = {
       baoClientCertFile = lib.mkDefault "${pkiDir}/services-issuer.pem";
       baoClientKeyFile = lib.mkDefault "${pkiDir}/services-issuer-key.pem";

nix/host-modules/glue-swarm-bao-otel-oidc-client.nix

@@ -29,7 +29,7 @@ let
   baoCfg = hyperhiveCfg.swarm.bao;
 in
 {
-  config = lib.mkIf deployCfg.authelia.enable {
+  config = lib.mkIf (hyperhiveCfg.enable && deployCfg.authelia.enable) {
     # One declaration, two readers: `clientId` is a read-only option
     # ./swarm-bao.nix owns, and ./swarm-otel.nix builds this principal's
     # authenticator audience from the same option.