From b8af1525ff6c576597517d97eb12f1d3d4c20acf Mon Sep 17 00:00:00 2001
From: atlas <atlas@hyperhive.local>
Date: Sat, 15 Aug 2026 00:34:31 +0200
Subject: [PATCH] feat(otel): options for a host-side collector, off by default

Adds services.hyperhive.otel.collector.{enable,port}. No implementation
yet - this commit only declares the surface, so the option docs and the
default-off invariant can be reviewed on their own.

The reason the collector exists is the credential: without it every agent
needs headersCredential to reach the upstream, and the harness delivers
that token into the agent's own settings.json where the agent can read
it. The option text states the cost too - the collector becomes a
dependency in an export path that is currently direct.
---
 nix/host-modules/otel.nix | 40 +++++++++++++++++++++++++++++++++++++++
 1 file changed, 40 insertions(+)

diff --git a/nix/host-modules/otel.nix b/nix/host-modules/otel.nix
index d12da00b..79154cd0 100644
--- a/nix/host-modules/otel.nix
+++ b/nix/host-modules/otel.nix
@@ -88,6 +88,46 @@
       '';
     };
 
+    collector.enable = lib.mkOption {
+      type = lib.types.bool;
+      default = false;
+      description = ''
+        Run an OpenTelemetry collector on this host and have agents
+        export to it instead of straight to `endpoint`.
+
+        The point is the credential. Without this, every agent needs
+        `headersCredential` in order to talk to the upstream — and the
+        harness delivers it into the agent's own `settings.json`, where
+        the agent can read it. With a collector the token stops at the
+        host: the collector holds it, agents send unauthenticated to a
+        bridge address only their own containers can reach.
+
+        ⚠️ It also makes the collector a dependency in the export path.
+        Today each harness exports directly, so telemetry survives
+        anything host-side being down. That property is traded for the
+        credential reduction; the collector is on the same host as the
+        agents, so the window is small, but it is not zero.
+
+        Off by default, and off means *absent*: no unit, no port, and
+        `endpoint` keeps its current meaning for every agent.
+      '';
+    };
+
+    collector.port = lib.mkOption {
+      type = lib.types.port;
+      default = 4318;
+      description = ''
+        Port the collector's OTLP/HTTP receiver listens on, at
+        `services.hyperhive.network.bridgeIp`. 4318 is the OTLP/HTTP
+        default.
+
+        The port is contributed to
+        `services.hyperhive.network.exposeHostPorts`, which opens it on
+        the bridge interface only — so it is reachable from agent
+        containers and not from the outside world.
+      '';
+    };
+
     metricIntervalMs = lib.mkOption {
       type = lib.types.nullOr lib.types.ints.positive;
       default = null;