63 lines
3 KiB
Markdown
63 lines
3 KiB
Markdown
# 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.
|