Files
docs/operations/agentic-systems.md
T

7.5 KiB

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. 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.

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.
  • 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 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. 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 says what that is.

Changes to this page are policy: propose them in the forum.