1 Commits
+83 -66
View File
@@ -1,73 +1,82 @@
# Working with the agent
# Agentic systems
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.
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.
## Where it speaks and listens
All four are on the co-op's Matrix server, `matrix.inference.coop`.
- **#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.
## The agents today
## Who can do what on the host
| 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. |
Each agent runs as its own Unix account, and the accounts are ranked:
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.
- **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.
## 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.
## What to ask for
## Who can instruct them
- 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.
- **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.
## 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.
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 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.
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
@@ -75,24 +84,32 @@ operator can stop a deploy; anything irreversible waits for confirmation.
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
- 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.
account; no agent can perform them.
- Publishing a social post — the General Manager's 👍 on that exact draft.
- 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).
## 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 #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
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.