Beekeeper

Beekeeper is a standalone, declarative Buzz agent host for NixOS. The services.beekeeper.agents attribute set is the lifecycle authority: Buzz users can invoke an allowlisted agent, but cannot create, edit, start, stop, or retire one.

Each declared agent receives a durable Nostr identity, Unix user/group, systemd unit, private state directory, workspace, journal, credential, and a required beekeeper-agent-runner sandbox boundary. Beekeeper retains its fleet-owner key, registry, reconciliation state, retirement queue, and generated agent keys in the protected /var/lib/beekeeper control-plane state.

NixOS configuration

For a complete operator walkthrough—including flake import, secrets, adding and removing agents, Goose/Codex/Claude runtime settings, and OpenRouter with Goose—see Configuring hosted agents.

{
  services.beekeeper = {
    enable = true;
    relayUrl = "wss://buzz.example.com";
    fleetOwnerKeyFile = "/run/secrets/beekeeper-owner-key";
    operationsChannel = "00000000-0000-0000-0000-000000000001";

    agents.reviewer = {
      profile = {
        displayName = "Reviewer";
        about = "Reviews proposed changes.";
      };
      channels = [ "00000000-0000-0000-0000-000000000002" ];
      callerPubkeys = [
        "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
      ];
      capabilities = [ "messages" "reviews" ];
      personaPrompt = "Review changes for correctness and regressions.";
      runtime = "codex-acp";
      runtimePackages = [ pkgs.codex-acp ];
      environmentFile = "/run/secrets/reviewer.env";
      sandbox.cwd = "/source";
      sandbox.binds = [{
        source = "/srv/source";
        target = "/source";
        readOnly = true;
      }];
    };
  };
}

Hosted agents receive a baseline PATH containing Bash, Git, OpenSSL, curl, and ripgrep. They also receive the pinned buzz-dev-mcp developer tools by default. Use services.beekeeper.path for additional fleet-wide tools, runtimePackages for an agent adapter, or set mcpCommand = null to opt an agent out of the developer MCP server. A read-only source bind must be updated outside the sandbox; use a controlled writable checkout if the agent must fetch or modify repository state itself.

The flake pins buzz-sdk, buzz-ws-client, and the default deployed buzz-runtime to the same Buzz commit. Private keys are generated at runtime, never interpolated into Nix derivations or command arguments. The stable fleet owner key is loaded with a systemd credential. Beekeeper derives a NIP-OA owner attestation for each agent, uses it while registering the agent with the relay, and passes it to the agent runtime as a separate systemd credential.

On boot, beekeeper-prepare.service reconciles identities, kind-0 profiles, kind-10100 agent directory entries, and channel memberships before any agent unit may start. beekeeper.service then continues reconciliation and reports systemd health changes to the operations channel.

Removing a declaration queues owner-signed membership removals and an agent-signed retirement tombstone. The private agent key is deleted only after all retirement events have been accepted by the relay and the terminal registry state is durable. Interrupted credential cleanup is retried during later reconciliation.

Verification

nix flake check path:. --no-build
nix build path:.#checks.x86_64-linux.package \
  path:.#checks.x86_64-linux.nixos-module -L --no-link

The full check also verifies that Beekeeper ships its sandbox runner and that the pinned Buzz runtime supplies buzz-acp, buzz-agent, and buzz-dev-mcp:

nix flake check path:. -L