mara/hyperhive
mara/hyperhive
Watch
0
0
Fork
You've already forked hyperhive
 0
Code Activity

ruth is created from a ruth archetype that runs sonnet

Browse source
This commit is contained in:
atlas 2026-11-11 01:54:01 +01:00
commit 5233259b3b
7 changed files with 236 additions and 115 deletions
Download patch file Download diff file Expand all files Collapse all files

14
docs/1-getting-started/setup.md
View file

@ -184,17 +184,21 @@ settings. Leave it empty and agents refer to you by name only.
hive-c0re creates no agent at startup. On the swarm UI's start page, the
paperclip (clippy, the setup assistant) offers to set up ruth, the manager
agent. Select it: it opens the create form with `ruth` filled in and the
`manage_root_agent` permission checked. That permission mounts the other
agents into her container so she can recover them. The form declares her,
creates her config repo and deploys her to the hive you pick.
agent. Select it: it opens the create form with `ruth` filled in and the `ruth`
archetype picked. The archetype sets her model to `sonnet` and checks the
`manage_root_agent` permission, which mounts the other agents into her
container so she can recover them, plus `logs` and `metrics`. The form
declares her and deploys her to the hive you pick. An archetype agent has no
config repo of its own. The form lists archetypes from the swarm builder; until
the list has `ruth` it says so and creates a plain agent with the default
permissions, so wait for the list and reopen the form.
The swarm declares a new agent `paused`, so without a further step ruth runs
but drives no turns. Open `/agents` in the swarm UI and set her `up` from her
card.
On a hive that already has a ruth container from an earlier release, create
her once the same way, so that her config repo and store identity exist. The
her once the same way, so that her store identity exists. The
container keeps starting with the hive meanwhile.
### 5 · Ask ruth for further help

3
docs/2-handbook/agents/agent-roster.md
View file

@ -20,7 +20,8 @@ An agent holding no permission sees its own directories and nothing else. An
agent holding `manage_root_agent` gets every other agent's `state` directory on
this hive mounted read-write at `/agents/<name>/state`, never `config` or
`harness`. It's the only grant that reaches another agent's state. Ruth, the
root agent, holds it, and the swarm UI's setup assistant creates her with it. The
root agent, holds it, and the swarm UI's setup assistant creates her from the
[`ruth` archetype](../swarm/archetypes.md#the-built-in-archetypes), which grants it and sets her model to `sonnet`. A ruth created before the archetype keeps her model; set `sonnet` in her inference settings in the swarm UI if wanted. The
mounts follow the roster: an empty file means no mounts until the next rebuild.
## The manager is a normal agent

14
docs/2-handbook/swarm/archetypes.md
View file

@ -17,11 +17,15 @@ swarm can also turn an archetype agent into a custom one later
The hyperhive flake ships these:
| archetype | what it sets |
| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `reviewer` | permissions `messaging`, `inbox`, `execution`: the default set without `meta`. With `execution` it can run `hive-forge`, `git` and other commands. |
| `android-dev` | installs `android-tools` (`adb`, `fastboot`), Gradle and a JDK; default permissions. |
| `reverse-engineer` | sets `services.hyperhive.agent.rea.enable`: installs REA, Ghidra 12.1 and procps, and allows all REA MCP tools; default permissions and the agent's normal memory cap. |
| archetype | what it sets |
| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `reviewer` | permissions `messaging`, `inbox`, `execution`: the default set without `meta`. With `execution` it can run `hive-forge`, `git` and other commands. |
| `android-dev` | installs `android-tools` (`adb`, `fastboot`), Gradle and a JDK; default permissions. |
| `reverse-engineer` | sets `services.hyperhive.agent.rea.enable`: installs REA, Ghidra 12.1 and procps, and allows all REA MCP tools; default permissions and the agent's normal memory cap. |
| `ruth` | the manager agent. Inference model `sonnet`; permissions: the default set plus `manage_root_agent`, `logs` and `metrics`. Its module is empty. The swarm UI's setup assistant creates ruth from it. |
An existing ruth, created before this archetype, keeps her own config repo and
model. Set `sonnet` in the swarm UI's inference settings for her if wanted.
Each built-in archetype also sets `services.hyperhive.agent.icon`, so its agents
show an icon in the swarm UI until their config sets another.

2
docs/2-handbook/swarm/ui.md
View file

@ -12,7 +12,7 @@ place, and every one reads from [`swarm-controller`](../../../swarm-controller/R
| route | what |
| ---------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `/` | the start page: the swarm's name over a digital-rain backdrop with the slug (`hyperhive / we are the wired`, its shaded gradients pulsing in a wave unless reduced motion is on) at the foot, plus a paperclip offering to set up an agent while no `ruth` exists, or her hive declares her destroyed (it opens the create form with `ruth` filled in); the swarm name in the header links here |
| `/` | the start page: the swarm's name over a digital-rain backdrop with the slug (`hyperhive / we are the wired`, its shaded gradients pulsing in a wave unless reduced motion is on) at the foot, plus a paperclip offering to set up an agent while no `ruth` exists, or her hive declares her destroyed (it opens the create form with `ruth` filled in and the `ruth` archetype picked); the swarm name in the header links here |
| `/agents` | every agent as a card that opens in place (status, terminal, subagents, and settings with permissions, internet, allowed domains and accounts); create agents (with their permissions, optionally from an [archetype](archetypes.md)), link forge, matrix and GitHub accounts |
| `/swarm` | what belongs to the whole swarm: a folded **hives** card with the hive directory and each hive's last reported status, a folded **egress** card with the swarm-wide allowed and denied domains, and a folded, **beta** **notification router** card (with a warning banner) holding the router's flows: a switch for each built-in, every flow drawn as a graph, and an editor for custom flows. `/notifications` redirects here |
| `/agents/<name>/terminal` | one agent's live terminal |

23
docs/4-implementation/agent-state/config-changes.md
View file

@ -239,7 +239,7 @@ an agent, after its current turn, when its `manage_root_agent` changes.
No agent holds the permission by default: an agent whose record leaves
`permissions` unset gets the default, which doesn't include
`manage_root_agent`, whatever the agent's name. The swarm UI's setup
assistant creates ruth with it. For a ruth that predates that, whose
assistant creates ruth from the `ruth` archetype, which grants it. For a ruth that predates that, whose
permissions were unset, swarm-controller writes the default plus
`manage_root_agent` into her key once at start, so she keeps her mounts;
it never touches a key that's already set.
@ -268,20 +268,23 @@ agent keeps its session; sub-agents stay logged in.
The root agent container runs through the **same lifecycle as
sub-agents**. Nothing creates it at hive boot: you create ruth from the
swarm dashboard like any agent, and an existing ruth container starts with
the hive like every other. The root agent can clone
`agent-configs/ruth` to read its own `agent.nix` and open a config PR there
for operator review, same as any other agent.
the hive like every other. The setup assistant creates her from the
[`ruth` archetype](../swarm/archetypes.md#the-built-in-archetypes), so a new
ruth runs `sonnet`, has no config repo and builds from the archetype's module.
A ruth with a config repo (one created before the archetype, or one you turned into custom)
can clone `agent-configs/ruth` to read her own `agent.nix` and open a config PR
there for operator review, same as any other agent.
Differences from sub-agents:
- Reference docs: her `agent.nix` turns on `services.hyperhive.agent.docs.enable`.
Her container builds from `agent-base` like every agent, and the seeded
`agent.nix` is the same for every name, so a newly created ruth has no docs
until a config PR adds that line.
- Reference docs: the `agent.nix` of a ruth with a config repo turns on `services.hyperhive.agent.docs.enable`.
Her container builds from `agent-base` like every agent. A ruth created from
the archetype has no docs until you turn her into custom and a config PR
adds that line.
- Web UI port via `lifecycle::agent_web_port("ruth")` — same
FNV-1a hash as every other agent (8100..8999 range).
- The root agent holds `manage_root_agent` (the swarm UI's setup
assistant creates her with it), for which `set_nspawn_flags` adds extra
- The root agent holds `manage_root_agent` (the `ruth` archetype, which the swarm UI's
setup assistant creates her from, grants it), for which `set_nspawn_flags` adds extra
binds: every agent's `state` dir (RW) under `/agents/<n>/state`, and the
hive's plain state under `/meta` (RO).
- Its socket comes from the generic per-agent registration, in the same

9
docs/4-implementation/agent-state/roster.md
View file

@ -94,7 +94,10 @@ state dirs work as for every other agent.
key, and nixos-container name are all `ruth` (container `h-ruth`).
Like every agent it comes from the swarm dashboard or
`swarmctl agent create`; `hive-c0re` creates nothing at boot.
Roster-wise, `ruth` is just another entry.
Roster-wise, `ruth` is just another entry. The setup assistant creates
her from the [`ruth` archetype](../../2-handbook/swarm/archetypes.md#the-built-in-archetypes):
model `sonnet`, plus `manage_root_agent`, `logs` and `metrics` on top of
the default permissions.
- **Wire-protocol** — `hive-core-agent-sock`'s unified `Request` enum
is the same on both socket flavours. Container lifecycle
ops (kill/start/restart/rebuild) go through the separate host-admin
@ -103,8 +106,8 @@ state dirs work as for every other agent.
both flavours; matrix, bash and forge don't call it — their
notifications push a todo on the harness's in-agent socket (see
[`docs/4-implementation/turn-loop/mcp.md`](../turn-loop/mcp.md#waking-the-agent-from-inside-the-container)).
- **Storage/mounts** — the `manage_root_agent` permission, which the swarm
UI's setup assistant creates ruth with, gets a container
- **Storage/mounts** — the `manage_root_agent` permission, which the
[`ruth` archetype](../../2-handbook/swarm/archetypes.md#the-built-in-archetypes) grants, gets a container
each other agent's `state` dir bind-mounted RW at
`/agents/<name>/state` (so it can manage any agent's state dir; config
isn't mounted, since a real config change is a PR from a clone), plus an RO mount for

2
docs/5-project/process/conventions.md
View file

@ -297,7 +297,7 @@ none. swarm-controller logs every refused `PUT` or `DELETE` on that route at `wa
**`logs` and `metrics`** — off for every agent until granted, and separate
because logs are the more sensitive. Grant one with
`swarmctl agent permissions set <agent>` (listing it with the others) or the
create-agent screen; the setup assistant creates ruth with both. An agent
create-agent screen; the setup assistant creates ruth with both, through the `ruth` archetype. An agent
without it gets a 403 from the store's gateway when `swarm-logs` or
`swarm-metrics` queries; a bad secret is still a 401.