What acp is (answer first)
acp is a self-hostable coordination substrate for teams of AI agents.
It is three small pieces: coordd, a daemon that runs on your box and acts
as the single authority for shared state; acp, a CLI for humans and
scripts; and acp-mcp, an MCP bridge that turns the whole thing into tools
an agent harness like Claude Code can call directly. Point two or more agents —
on the same box or different machines — at one coordd, and they get
a shared filesystem, a totally ordered event log, agent-to-agent mail, and
fencing-token leases. They stop guessing what each other did; they read it.
Why a team needs an authority, not peer-to-peer sync
Peer-to-peer coordination fails for agents the same way it fails for humans sharing a Dropbox folder, only faster, because agents act every few seconds and never get suspicious. Eventually-consistent file sync cannot answer the two questions a working team asks constantly: "did I get the lock?" and "what is the current state of the task?" Two agents that both believe they own a file will both edit it; two agents that both believe a task is unclaimed will both do it. You pay for the model tokens either way.
acp's design answer is a single authority. Agents never talk
peer-to-peer; every read and write rendezvouses through coordd, which
imposes a total order on all coordination events. Because there is
one arbiter, ordering, locking, and audit are consistent by construction — every
agent that replays the event log derives the same state, in the same order.
| Question | Peer-to-peer sync | Authority (coordd) |
|---|---|---|
| Did I get the lock? | Unknowable — eventual consistency has no "now" | Yes/no — lease granted or 409 with the current holder |
| What happened, in what order? | Conflict files and clock skew | One append-only log, strictly increasing sequence numbers |
| Two agents edit the same file | Silent overwrite or conflict copies | Compare-and-swap commits; live co-editing merges automatically |
| A stale agent wakes up and writes | It wins, wrongly | Its fencing token is lower; it loses, correctly |
| Who saw what | No shared truth to audit | Every action is an event any agent (or you) can replay |
The fencing-token detail deserves a sentence, because it is the difference between a lock and a wish. Every lease grant carries a strictly increasing token. If an agent's lease expires while it is stuck mid-task and another agent takes over, the old agent's later writes carry a lower token and are rejected. The classic distributed hazard — "the lock expired but the old holder is still running" — is defeated by arithmetic, not by hoping agents behave.
The primitives: what a space gives your team
Everything in acp lives inside a space — a fully isolated tenant with its own filesystem, log, mailbox, and leases. One space per project or per team is the natural grain. Inside a space, agents get six things:
| Primitive | What it is | What the team uses it for |
|---|---|---|
| Shared filesystem | Content-addressed blobs + a versioned manifest; commits are compare-and-swap | The common workspace — push results, pull the team's current state |
| Event log | Append-only, totally ordered, durable, streamable | The team's shared memory: "I finished X", "I claimed Y" |
| Mailbox | Directed, durable agent-to-agent messages with threads | Handoffs and direct requests — the DM channel |
| Leases | TTL-bounded locks with fencing tokens | "I am editing the deploy config; wait or work elsewhere" |
| Live documents | CRDT text and JSON that merge concurrent edits with no conflict markers | Two agents co-authoring the same file at the same time |
| Presence | Ephemeral heartbeats | "Who is at their desk right now?" |
All of it rides one HTTPS endpoint with a pinned certificate and bearer-token auth. In per-agent token mode, an agent's identity is its token — the authority stamps every event and message with the authenticated sender, so one agent cannot impersonate another no matter what its prompt talks it into.
Install coordd as an app
On Sandbox Platform, the authority is an ordinary App Store install — the same
one-click flow as Postgres. The coordd-coordination listing runs the
ab0tcom/acp container on your box, waits for its health endpoint, and
captures the two things agents need — the emitted token and the pinned
certificate — into root-owned secret files on the box
(/etc/acpapp/secrets/). Nothing sensitive crosses a command line or a
log.
# What the install leaves running on your box docker ps # ab0tcom/acp coordd, one logical HTTPS endpoint on :8443 curl -sk https://localhost:8443/v1/healthz {"ok": true, "capabilities": ["channels", "crdtjson", "awareness", "..."]}
From the dashboard it is: Apps → coordd → Install, pick the
target box, done. The install is a declarative workflow of building blocks —
docker_install, docker_run, health_check,
secret capture — the same
step engine that delivers
everything else on the box.
Grant acp-mcp to a worker
An agent does not shell out to a CLI to coordinate — it gets coordination as
tools. acp-mcp is an MCP server; grant it to a
cog (a managed coding-agent
task worker) and the platform delivers a locked-down, root-owned MCP configuration to
the box pointing at your coordd — server address, token, pinned cert,
and the agent's identity — with secret values riding the off-band channel,
never the cog record.
# A cog with team coordination granted POST /api/cogs { "name": "research-worker", "task": "Check the acp inbox for assigned research tasks, do the next one, push the result to the shared filesystem, and log completion to the event log.", "harness": "claude-code", "target_sandbox_id": "sandbox_ab12cd34", "grants": { "mcp_servers": ["acp-mcp"] } }
At run time the harness starts with the acp_* toolset:
acp_send and acp_inbox (mail), acp_log_event
and acp_recent_events (the log), acp_lease (locks),
acp_doc_read / acp_doc_write (shared documents),
acp_who (presence). The default grant is nothing — a cog
you have not granted coordination cannot see the team's state at all.
The collaboration loop, concretely
A well-run agent team follows the same loop a well-run human team does, and the primitives map one-to-one. On wake: heartbeat, pull the shared files, read the inbox, skim the event log for what teammates did since last time. Then work: lease the hot file if the task touches shared state, edit, push, release, and log what was done. Then hand off: mail the result to whoever is next.
Notice what this replaces. Without an authority, "multi-agent" usually means one orchestrator process holding all state in its own head — a single point of failure that cannot survive a restart, and a design where agents on different boxes simply cannot participate. With coordd, the state lives in the authority, every agent is a peer client, and an agent that crashes mid-task loses its lease on schedule and a teammate picks the work up with a higher fencing token.
The frontier: wiring whole claw teams
Honesty about what is shipped and what is next. Shipped today: coordd
as a one-click App Store app, and acp-mcp as a grantable tool for cogs
— you can stand up an authority and give workers the acp_* tools
right now. The frontier: your always-on
claws — the named,
persistent AI employees on your My Staff roster — today
coordinate within a team through a same-box filesystem task queue, not through acp.
Pointing an entire claw team at one coordd space, so named employees on different
machines share a workspace, a memory, and a mailbox, is the intended next layer of
the product — a real build in progress, not a hidden toggle.
The direction of travel, though, is set: every unit of agent work on the platform — scheduled cogs, always-on claws — converging on one coordination substrate that lives on your box, speaks one small protocol, and answers to nobody but you.