Your crew & fleet
Bots & the Team board
A bot is a persistent worker on an instance's team — a name, a role, a model, and a ceiling it can never exceed. Here's how to run a crew.
A single Anvil session is one conversation. A bot is something more durable: a standing member of a machine's team that's there between sessions, ready to take work. Think of the instance itself as the team lead — it holds an identity, takes orders, and decides which bot does a given job — and the bots as the crew it directs.
What a bot is
Each bot has:
- A nickname — how you refer to it.
- A role — what it's for ("reviewer", "release-runner").
- A squad — the capability it serves.
- A model — which model it runs on.
- A ceiling — the most it's ever allowed to do, no matter who assigns it work.
- Its own identity — so in a team chat room, its messages come from it, not from you.
A team holds up to twelve bots. Each one is a small file on the host; the host is the single source of truth for who's on the team.
Ceilings — the safety rail
A bot's ceiling is the hard limit on what it can touch, and it only ever composes downward. The three levels:
| Ceiling | The bot may… |
|---|---|
| Read-only | Look, analyse, report — never change anything. |
| Workspace-write | Change files inside its workspace, run the normal build/test loop. |
| Full access | Everything, including outside the workspace. Hand this out sparingly. |
The ceiling is a maximum, not a grant: a task can ask for less, never more. A read-only bot assigned something that would write simply refuses — the ceiling wins.
Three ways to run your crew
The same team of bots is reachable through three doors, and they all read and write the same underlying crew:
- In the terminal —
/botto create, edit, enable, disable;/teamto see the roster. - In team chat — address a bot directly in an org chat room (
bot: …) and it picks up the task with its own identity. - On AnvilHub — the Team page: a board of every bot with its role, squad, model, ceiling, identity status, and what it's running right now and recently.
[!NOTE] On AnvilHub, the host is always authoritative — the web never invents or secretly edits a bot. When you create or change a bot from the Team page, AnvilHub files that as an instruction; the daemon applies it and confirms. That's why a change made while the machine was offline still lands when it comes back.
The Team board on AnvilHub
The Team page is where a crew becomes legible. For each bot you see who it is, what it's cleared to do, and — crucially — what it's doing now and what it did recently. Paired with the Runs page (every run's cost, changeset and outcome) and the squad chart, it turns a set of background workers into something you can actually supervise.
Bots vs squads vs agents
Three words that sound similar and aren't:
- A squad is a capability the orchestrator delegates to — "I need security work done."
- A bot is a persistent worker that stands by between sessions and serves a squad.
- An agent is a specialist the host resolves from a squad to actually do a delegated task, in its own context.
So: you keep a crew of bots; the orchestrator routes work by squad; the host runs the right agent.
Where to next
- Squads — how work is routed to the right capability.
- Instances & the fleet — running crews across many machines.
- Automation & routines — giving a bot a schedule.