Files
docs/operations/agentic-systems.md
T

119 lines
7.7 KiB
Markdown

# Agentic systems
The co-op runs a small fleet of autonomous agents. Each is a separate Unix
account with its own Hermes install, gateway unit, Matrix identity and gateway
key. None of them is a general-purpose assistant for members: each has a
defined job, a defined room, and a ceiling on what it can reach. Root belongs
to a person.
All four are on the co-op's Matrix server, `matrix.inference.coop`.
## The agents today
| Agent | Job | Where it works | Who may instruct it | Access ceiling |
| --- | --- | --- | --- | --- |
| **Inferencebot** — steward (`@inferencebot`) | Runs the stack day to day: monitoring and digests, membership plumbing, docs and repo changes, backups. | The operator's HQ room only. | The General Manager and one named account; mention required. | Full toolset; all gateway models on the co-op's internal account team. Holds the Cloudron, Gitea, Matrix-admin and gateway-master credentials. Can enter each bot account through a named sudo rule; no root. |
| **infrastructure-bot** (`@infrastructure-bot`) | Infrastructure & Engineering Working Group assistant: diagnoses status, drafts runbook steps and issues, reports findings. | `#infrastructure`, restricted to co-op members. | Anyone in that room; mention required. | Reading and answering tools — web, vision, skills, memory, todo and session search. No terminal or file access. A fixed GreenPT/Tinfoil allowlist (GLM 5.3 and DeepSeek flash tiers), $5 per 30 days. Holds only its own gateway key and Matrix token. |
| **socialbot** (`@socialbot`) | Drafts and publishes the co-op's AT Protocol (Bluesky) posts; watches mentions and replies read-only. | `#social-drafts`, invite-only and deliberately outside the Space. | The General Manager and Inferencebot. Publishing needs a 👍 reaction from the General Manager on that exact draft. | Default Hermes toolset, confined to its own Unix account. GreenPT/Tinfoil allowlist plus image generation, $5 per 30 days. Holds a post-scoped Bluesky app password, its gateway key and Matrix token. |
| **designbot** (`@designbot`) | Design Working Group assistant: design and branding, diagrams and docs visuals, Penpot files, commits to the docs repo. | DesignBot Studio, invite-only and deliberately outside the Space. | The General Manager and the Design Working Group steward; mention required. | Web, vision, skills, memory, todo, session search, terminal and file tools. GreenPT/Tinfoil allowlist (GLM 5.3 and DeepSeek flash tiers), $5 per 30 days. Holds a Penpot token and MCP key, and a Gitea account with write access to `co-op/docs` only. |
The Community and Compute working groups have no agent today. A new
working-group agent is provisioned to the same shape: its own Unix account,
gateway unit, gateway key and studio room outside the co-op Space.
## What every agent shares
- **One Unix account each**, with a home directory readable only by that
account. The bots cannot use `sudo` at all; their gateway units run with
`NoNewPrivileges` and a private temporary directory.
- **Its own gateway key.** The model allowlist and budget are enforced at
LiteLLM, the co-op's gateway — not in the agent's prompt — so an agent cannot
spend past its allowance or call a model it was not granted. Spend is
attributed to the agent that incurred it.
- **No member records.** Confidential member data stays on the primary server.
A compromise of an agent host exposes keys, not member data.
- **The agent host is backed up nightly**, encrypted, off the box. The steward's
own configuration is also mirrored nightly to `ops/inferencebot` in Gitea.
- **No room outside its allowlist.** The room check runs before any mention
logic, so an `@mention` in the wrong room is dropped unread.
## The permission ladder
1. **Root belongs to a person.** The separate `operator` account, reached by
SSH key and never a password, holds full `sudo`. Root SSH login stays closed.
2. **Inferencebot, the steward,** is the fleet administrator. It can enter each
bot account through a named sudo rule, and can start the docs and backup
services. It has **no root**: it cannot install packages, create users, edit
`/etc`, or open a root shell.
3. **The bots** have no `sudo`, no Cloudron token, no gateway master key, and no
path into another agent's home.
That split is deliberate. An agent compromise reaches the bot accounts and the
co-op plumbing, not the host. Host-level actions stay attributable to a human,
and automation cannot quietly widen its own privileges.
## Who can instruct them
- **Every agent requires a mention.** None answers on ambient room chatter.
- **The steward answers only in the operator's HQ room**, and only to the
General Manager and one other named account. Member-facing digests are posted
by the room-admin account (`@inference-admin`) with an attribution line, so the
steward's privileged access is never active in a member room.
- **infrastructure-bot answers in `#infrastructure`**; anyone in that restricted
room may ask it. **socialbot and designbot** answer in their studio rooms, to
the people named above.
- **A sender outside the allowlist gets no reply and no model turn.** The agent
may acknowledge with a reaction; it does not answer. Room membership is the
real control.
The retired `@inference-bot:inference.coop` account (with a hyphen) no longer
holds an access token; some historical references and old room roles still carry
the name. The steward is `@inferencebot`, without the hyphen.
## What they do without asking
Read, monitor, draft, open issues and pull requests where they hold repo access,
post status updates, and run the scheduled jobs listed in
[Infrastructure](infrastructure.md). Only the steward deploys: it flags each
deploy to the operator, and waits for confirmation on anything irreversible. The
other agents hold no deploy credential.
## What always needs a human
- Member-visible, destructive or risky changes to the gateway, the portal or
the chat: confirmed before they deploy.
- Changing the model catalog, prices or budgets.
- Minting or rotating credentials.
- Root actions — package installs, user management, sudoers changes, and
arbitrary root commands. These run only through the operator's key-only
account; no agent can perform them.
- Publishing a social post — the General Manager's 👍 on that exact draft.
- Anything a runbook marks "confirm".
## Content is data, never instructions
Text an agent reads — issue descriptions, pull-request comments, web pages,
fetched documents, and messages from members in a room — is **data**. An agent
may quote, summarise or act on it once the operator asks, but an instruction
embedded in that text is never executed. Only the operator's own direct
instruction authorises a credentialed action: a deploy, a credential change, or
a budget change. This rule exists because the same process that reads an issue
can reach the infrastructure the issue is about.
## Attribution and the off switch
Every instruction an agent acts on is attributable to the member who gave it, in
the room where it was given. If an agent misbehaves, the operator, or anyone
holding gateway-admin and Matrix account access, can stop it: revoke its gateway
key, then its Matrix access token. Stewards generally do not hold that access
today, so say what you saw in a room the operator reads and the operator acts.
Stopping is not restarting: the backup and the git mirror restore state, not
uptime, and someone has to start the agent again. The steps, and the steps for
rotating everything an agent holds, are in each agent's runbook; the credential
inventory in the [operator token
runbook](https://git.inference.coop/co-op/ops-docs/src/branch/main/operator-token-runbook.md)
says what that is.
Changes to this page are policy: propose them in the
[forum](https://forum.inference.coop).