Files
docs/operations/agentic-systems.md
T
inference-bot cb270e51b9 docs: document the host access model
State the privilege ranking on the Agentic Systems page: bots have no sudo, the steward can act only inside bot accounts, and root belongs to a separate key-only operator account. Update the Infrastructure page's least-privilege and backup statements to match.
2026-11-21 16:08:20 +00:00

102 lines
4.9 KiB
Markdown

# Working with the agent
The co-op runs **Inferencebot** to help steward its infrastructure. It is
isolated as its own OS user, with its own gateway key — budget, model
allowlist and spend enforced at the gateway. It runs on co-op infrastructure
under a co-op identity, uses the co-op's own gateway for inference, and its
skills, scripts and configuration are mirrored to a Gitea repository nightly.
This page is for members who read its output or give it instructions.
## Where it speaks and listens
- **#inferencebot-updates** is read-only: daily digests, model changes,
upgrades, maintenance, outages. Posts are anonymized.
- **Instructing the agent** is limited to members on its allowlist of Matrix
IDs (kept in its configuration, published here once settled), and only in
the rooms where it is configured to answer — most require a mention. The
General Manager decides who is on the list.
- The **retired `@inference-bot:inference.coop`** automation account (with a
hyphen) no longer holds an access token; some historical references and old
room roles still carry the name.
## Who can do what on the host
Each agent runs as its own Unix account, and the accounts are ranked:
- **The bots** (`infrastructure-bot`, `socialbot`, `designbot` and any future
working-group bot) cannot use `sudo` at all.
- **Inferencebot, the steward,** can act inside those bot accounts — it is the
fleet administrator — but it has **no root** and no passwordless `sudo` beyond
the docs and backup service commands. It cannot install packages, create users,
edit `/etc`, or open a root shell.
- **Root belongs to a person.** A separate operator account, reached with an SSH
key and never a password, holds full `sudo`. Root SSH login stays closed: the
operator signs in as their own account and escalates deliberately.
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.
## What to ask for
- Operational work that a runbook already describes, or that ends in a PR, an
issue or a post members can see.
- Research and summaries that would otherwise land in an issue.
- Status: what is running, what failed, what changed.
## What not to ask in a shared room
- Anything involving member-identifying data. That work happens in a session a
named steward opened, and the result is reported without the data.
- Anything that moves money or changes who is a member. Those go through the
portal and a human.
- Credentials, in either direction.
## 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**. The 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.
## What they do without asking
Read, monitor, draft, open issues and PRs, post updates, run the scheduled jobs
listed in [Infrastructure](infrastructure.md), and deploy fixes after flagging
them to the operator. The bot can deploy without waiting for a reply, and the
operator can stop a deploy; anything irreversible waits for confirmation.
## 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.
- Host root actions — package installs, user management, sudoers changes, and
arbitrary root commands. These run only through the operator's key-only
account; the steward cannot perform them.
- Anything a runbook marks "confirm".
This matches the standing policy the agents operate under today. A stricter
norm is a policy decision for the [forum](https://forum.inference.coop).
## 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 #general 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 the 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).