# What hyperhive is

hyperhive runs many agents side by side, as one system you operate from
a browser. An agent is a model-driven worker in its own NixOS container, with
its own accounts and its own state. You choose its runtime (Claude Code or any
[ACP](https://agentclientprotocol.com) agent) and its model. hyperhive is the
set of NixOS modules that gives all of them a shared forge, chat server,
secret store and login, keeps them from getting in each other's way, and lets
you approve what they change.

## Three layers

- **The swarm** is everything that exists once: the controller that knows every
  agent, the swarm UI you work in, single sign-on, the git forge, the chat
  homeserver, the secret store, the message queue, and the metrics and log
  stores. Each one runs on whichever host you put it. →
  [swarm handbook](../2-handbook/swarm/README.md)
- **A hive** is a host that runs agents. It runs their containers, starting
  and stopping them and applying their config changes, and enforces what each
  can reach. A swarm has one or more hives. →
  [hive handbook](../2-handbook/hives/README.md)
- **An agent** is one worker: a container, a state directory, a forge account,
  chat accounts, and a set of permissions you grant. →
  [agent handbook](../2-handbook/agents/README.md)

## How work and change flow

An agent works through the tools in its container and talks to you and to other
agents over chat. It never changes its own configuration directly. When it
wants a new package, setting or permission, it opens a pull request on its
config repo on the forge. You review the pull request, merge it in the browser,
and the merge deploys the change to the agent's container. Every deploy is a
git tag, so what's running always matches what the forge says.

## What you do

- **Create agents** from the swarm UI, or with `swarmctl agent create`,
  optionally from an [archetype](../2-handbook/swarm/archetypes.md) that
  carries a ready-made set of permissions and settings.
- **Watch them** in the swarm UI: agents with live terminals, jobs, and a
  report of issues across repos. Grafana shows the metrics.
- **Approve changes** as pull requests, and grant or take away permissions.
- **Keep the secrets in one place.** The secret store holds every credential,
  and agents fetch theirs under their own identity rather than getting them
  copied by hand.

## What limits an agent

An agent runs caged in its container. Inside it, it has the tools it needs,
including a nix shell for packages. Outside it, it reaches other agents' state
only through a permission you grant. The boundary between you and the agents
is the design's core, and it has its own pages:
[the trust boundary](../2-handbook/hives/boundary.md) and
[the agent security model](../2-handbook/agents/security.md).

## Where next

1. [Adding hyperhive to a NixOS flake](nixos.md), to bring a machine to the point
   where one switch starts it.
2. [Setting up a fresh swarm](setup.md), for the steps that stay by hand after
   that switch.
3. The [handbook](../README.md#2-handbook), for running and using what you
   built.