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 The co-op runs a small fleet of autonomous agents. Each is a separate Unix
isolated as its own OS user, with its own gateway key — budget, model account with its own Hermes install, gateway unit, Matrix identity and gateway
allowlist and spend enforced at the gateway. It runs on co-op infrastructure key. None of them is a general-purpose assistant for members: each has a
under a co-op identity, uses the co-op's own gateway for inference, and its defined job, a defined room, and a ceiling on what it can reach. Root belongs
skills, scripts and configuration are mirrored to a Gitea repository nightly. to a person.
This page is for members who read its output or give it instructions.
## 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, ## The agents today
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 | 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. | Read-only tools — web, vision, skills, memory, todo and session search. No terminal or file access. Flash/TEE models only, $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. | Standard toolset, confined to its own Unix account. Flash/TEE models 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. Flash/TEE models only, $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 ## What every agent shares
working-group bot) cannot use `sudo` at all.
- **Inferencebot, the steward,** can act inside those bot accounts — it is the - **One Unix account each**, with a home directory readable only by that
fleet administrator — but it has **no root** and no passwordless `sudo` beyond account. The bots cannot use `sudo` at all; their gateway units run with
the docs and backup service commands. It cannot install packages, create users, `NoNewPrivileges` and a private temporary directory.
edit `/etc`, or open a root shell. - **Its own gateway key.** The model allowlist and budget are enforced at
- **Root belongs to a person.** A separate operator account, reached with an SSH LiteLLM, the co-op's gateway — not in the agent's prompt — so an agent cannot
key and never a password, holds full `sudo`. Root SSH login stays closed: the spend past its allowance or call a model it was not granted. Spend is
operator signs in as their own account and escalates deliberately. 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.
- **A nightly encrypted backup** of each agent's home, and a nightly mirror of
its configuration to 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 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, co-op plumbing, not the host. Host-level actions stay attributable to a human,
and automation cannot quietly widen its own privileges. 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 - **Every agent requires a mention.** None answers on ambient room chatter.
issue or a post members can see. - **The steward answers only in the operator's HQ room**, and only to the
- Research and summaries that would otherwise land in an issue. General Manager and one other named account. Member-facing digests are posted
- Status: what is running, what failed, what changed. 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 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
- Anything involving member-identifying data. That work happens in a session a the name. The steward is `@inferencebot`, without the hyphen.
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 ## What they do without asking
Read, monitor, draft, open issues and PRs, post updates, run the scheduled jobs Read, monitor, draft, open issues and pull requests where they hold repo access,
listed in [Infrastructure](infrastructure.md), and deploy fixes after flagging post status updates, and run the scheduled jobs listed in
them to the operator. The bot can deploy without waiting for a reply, and the [Infrastructure](infrastructure.md). Only the steward deploys: it flags each
operator can stop a deploy; anything irreversible waits for confirmation. deploy to the operator, and waits for confirmation on anything irreversible. The
other agents hold no deploy credential.
## What always needs a human ## 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. the chat: confirmed before they deploy.
- Changing the model catalog, prices or budgets. - Changing the model catalog, prices or budgets.
- Minting or rotating credentials. - 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 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". - Anything a runbook marks "confirm".
This matches the standing policy the agents operate under today. A stricter ## Content is data, never instructions
norm is a policy decision for the [forum](https://forum.inference.coop).
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 ## Attribution and the off switch
Every instruction an agent acts on is attributable to the member who gave it, Every instruction an agent acts on is attributable to the member who gave it, in
in the room where it was given. If an agent misbehaves, the operator, or anyone 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 holding gateway-admin and Matrix account access, can stop it: revoke its gateway
gateway key, then its Matrix access token. Stewards generally do not hold that key, then its Matrix access token. Stewards generally do not hold that access
access today, so say what you saw in #general and the operator acts. Stopping today, so say what you saw in a room the operator reads and the operator acts.
is not restarting: the backup and the git mirror restore state, not uptime, Stopping is not restarting: the backup and the git mirror restore state, not
and someone has to start the agent again. The steps, and the steps for 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 rotating everything an agent holds, are in each agent's runbook; the credential
inventory in the [operator token inventory in the [operator token
runbook](https://git.inference.coop/co-op/ops-docs/src/branch/main/operator-token-runbook.md) runbook](https://git.inference.coop/co-op/ops-docs/src/branch/main/operator-token-runbook.md)
says what that is. says what that is.