From 34ade7a8827b79065a81ce409fa85996b999feb1 Mon Sep 17 00:00:00 2001 From: inference-bot Date: Sat, 21 Nov 2026 16:39:13 +0000 Subject: [PATCH 1/2] docs(agentic-systems): cover the whole agent fleet, not one bot --- operations/agentic-systems.md | 149 +++++++++++++++++++--------------- 1 file changed, 83 insertions(+), 66 deletions(-) diff --git a/operations/agentic-systems.md b/operations/agentic-systems.md index 20316e3..b912801 100644 --- a/operations/agentic-systems.md +++ b/operations/agentic-systems.md @@ -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. From d2440528cfba243065392750c0dd2e7081c8a09d Mon Sep 17 00:00:00 2001 From: inference-bot Date: Sat, 21 Nov 2026 16:40:26 +0000 Subject: [PATCH 2/2] docs(infrastructure): correct which account speaks in member rooms --- operations/infrastructure.md | 19 +++++++++++-------- 1 file changed, 11 insertions(+), 8 deletions(-) diff --git a/operations/infrastructure.md b/operations/infrastructure.md index 1634788..4da7f6a 100644 --- a/operations/infrastructure.md +++ b/operations/infrastructure.md @@ -108,17 +108,20 @@ from any homeserver you already use. A few accounts in the space are automation rather than people: -- **`@inferencebot` — the steward.** It posts the digests, newsletter notes and - reminders. It holds no more power than posting needs. +- **`@inferencebot` — the steward.** It works in the operator's HQ room, not in + the member rooms, and holds the steward credentials. Member-facing messages + that come from its work are posted by `@inference-admin`, and say so in the + message. - **`@inference-admin`** — the administrator of record for the co-op's rooms (#general, #community, #design, #skillshare, #updates and #infrastructure) and - their membership. It **never speaks in a member room** — a message from it is - a mistake, not a feature. + their membership. It also posts member-facing digests on the steward's behalf, + with an attribution line naming the steward. -The house rule: **power belongs to `@inference-admin`, voice belongs to -`@inferencebot`.** Please don't create an account whose name differs from an -existing one by a character or two — spotting lookalikes is exactly what this -convention is for. +The house rule: **room power and membership belong to `@inference-admin`; the +steward's own voice stays in HQ, and anything it sends to a member room carries +the admin account's attribution.** Please don't create an account whose name +differs from an existing one by a character or two — spotting lookalikes is +exactly what this convention is for. ## Membership