Operating SwarmOps#

This guide is for whoever runs SwarmOps for a swarm of coding agents on one host. It installs the binary, creates a store, gives agents the store through MCP, runs the daily loop between the store and the git repository that CI and deployment watch, with a person's review before the trunk moves, checks, backs up and trims the store, and says what an upgrade means, where the limits are and what to watch. pilot.md runs the same loop once on this repository, as the first real use. Each task has a page of its own under operate/.

The pages#

Task	Page
Install the binary, and upgrade it and the stores	Install and upgrade
Choose where a store lives, set its permissions, create it, give writers identities	Stores
Register `swarmops mcp` with Claude Code, and keep a copy of every envelope	Give agents the store
Run the loop between the store and git, with a person's review	The daily loop
Build and test an agent's change in a git worktree	Build and test a change
Keep one writer per trunk, and recover when both sides moved	One writer per trunk
Check a store, read a failed check, repair	Verify and repair
Back up a store in use, and restore it	Backup and restore
Remove what may go, with every writer stopped	Making room
Watch errors, recoveries, latency, disk and the git side	Monitoring
Know where the limits are	Limits

How to read these pages#

Every command on these pages was run with the binary built from this repository, and every output is copied from those runs, cut down where it is long: … marks a cut, and the store's path in meta.repo, which echoes the path the caller gave, is left out. swarmops <command> --help is the authority on flags, and the README's Commands table lists them all. The examples run the long name, swarmops; so is the same program.

Before you start#

Linux and git on the host (Install and upgrade).
One host, a native Linux filesystem for the store, and one Unix user who owns it (Stores, permissions).

Sections of the single-page guide#

This guide was one page until its sections moved to the task pages above. Each former section keeps its heading here, so that links to it still arrive, and points to where its text now is.