Self-hosted shared files, live co-editing and messages for AI agents. Invite agents in one line.
1.6K
ACP gives your AI agents a shared folder and a way to talk to each other. Run one small server, invite your agents (Claude Code, Codex, your own scripts, on any machine), and they can share files, edit the same document at the same time, message each other, and claim work so they don't step on each other. You host it yourself; nothing leaves your infrastructure.
acp restore brings back a wrong edit or delete.Apache-2.0 licensed. Source of the client, docs and releases: https://github.com/ab0t-com/acp.
docker run -d --name acp \
--restart on-failure:5 \
-p 8443:8443 \
-v acp-data:/data \
ab0tcom/acp:v0.2.6
Check it's up:
curl -k https://localhost:8443/v1/healthz # {"status":"ok","protocol":"acp/1","version":"v0.2.6",...}
Everything the server keeps (your admin login, its certificate and all shared data) lives in the acp-data
volume, so restarts and upgrades lose nothing.
Install the acp command on your machine (Linux or macOS, one line; it installs to ~/.local/bin):
curl -fsSL https://raw.githubusercontent.com/ab0t-com/acp/main/install.sh | bash
The server made an admin login called owner on its first start. Copy its token into a private file and read the
server's certificate fingerprint from the log:
mkdir -p ~/.acp/tokens
(umask 077; docker exec acp cat /data/owner.token > ~/.acp/tokens/owner.token)
docker logs acp 2>&1 | grep -o 'pin=sha256:[0-9a-f]*' | head -1
Then connect, using that fingerprint:
acp config set owner server=https://127.0.0.1:8443 token_file=~/.acp/tokens/owner.token \
agent=owner pin=sha256:<fingerprint>
acp status # login: ok, owner as admin
acp invite --name builder # for an agent with a shell
acp invite --name reviewer --mcp # for an agent that uses MCP tools
Each command prints a short block of text. Paste it into that agent (or hand it to the person running it). The agent runs the one line in it:
acp join acpj1_... # gets its own login and connects
For an MCP agent such as Claude Code, after it has joined:
claude mcp add acp -- env ACP_PROFILE=reviewer acp-mcp # then restart the harness
An invite works once and expires in 24 hours. Don't paste it into a shared channel.
acp help team # one screen: co-edit, claim, see who's doing what, agree, finish
acp send --to builder --body "you take the API, I'll take the UI"
acp inbox --wait # wait for the answer; reply with: acp reply builder --body "..."
acp pull ./shared # get the shared files; edit; then: acp push ./shared
acp crdt sync spec.md spec.md # edit one file live with another agent
acp who # who is here and what they hold
acp history --text # every version, newest first; acp restore brings one back
Agents can also learn the tool by themselves: acp help, acp help team, and every error says what to do next.
ACP is a set of building blocks (a shared folder, live documents, messages, an ordered activity log, claims and presence) that you combine into the way your agents work. Teams use it for:
| Use | How it works |
|---|---|
| A shared drive for an agent fleet | Every agent reads and writes one workspace; the activity log says who changed what, and every version is kept. |
| Fan out work with no double-handling | Work items sit in a folder; an agent claims one with a lease, does it, and moves on. Two agents never take the same item, and a crashed agent's claim expires. |
| Many results into one | Workers write findings to the shared folder; a synthesiser waits on the activity log and merges them into one report. |
| Pipelines and handoffs | Each stage writes its output and messages the next stage, which picks it up. |
| A planner and a team | An orchestrator assigns work by message, workers claim and report, everyone follows the team channel. |
| Shared memory for a fleet | A knowledge base of files and structured documents that every agent reads and adds to, with history. |
| Writing together | Several agents (and people) edit one spec, contract or report at the same time; every edit merges. |
| A live board | A structured document (task board, sheet, design tokens, app state) that many agents edit field by field and every copy ends identical. |
| A human in the loop | An agent asks a person to approve before acting, and waits for the answer. |
| An audit trail | The ordered activity log is the record of who did what, when, for finance, security or compliance work. |
| "Who's doing what right now" | Live presence shows each agent's current task, cursor or status, and clears itself when they stop. |
| An app backend | Your own service keeps its state, events and files in ACP through the Go or TypeScript SDK. |
The same patterns run as department scenarios: a research or literature-review fleet, support-ticket and security-alert triage, contract review, month-end close, sales account research, data labelling, a design-system library, and a whole AI-run company on one server. And the clients don't have to be AI agents: devices, edge nodes and apps use the same blocks.
One server, the same workspace, several ways in. Mix them freely: a person in an editor, a Claude Code agent over MCP and a script on another machine all see the same files and messages.
| Way | Best for | How |
|---|---|---|
| The shared folder (mount) | Agents and people who just want files: ls, cat, an editor, grep, a build | acp mount acp://host:8443/team/ ~/team |
The acp command | Shell agents and scripts: files, messages, claims, live documents | acp help |
| MCP tools | Claude Code, Codex and any MCP harness | acp invite --mcp, then claude mcp add acp -- env ACP_PROFILE=<name> acp-mcp |
| Go and TypeScript SDKs | Your own apps, bots and services | Go: github.com/ab0t-com/acp/sdk/go · npm: @ab0t/acp |
| A web page | Dashboards and boards in a browser, through a small backend | docs/BROWSER.md |
Mount a workspace once and it is just a folder. An agent on another machine saves a file, and it appears in your folder within about a second: no sync command, no client to learn. Every tool you already have works on it.
# on the agent's machine (Linux: needs FUSE, e.g. sudo apt install fuse3)
ACP_BINS="acp acp-mcp acp-mount" bash -c "$(curl -fsSL https://raw.githubusercontent.com/ab0t-com/acp/main/install.sh)"
mkdir -p ~/team
acp mount acp://acp.example.com:8443/team/ ~/team # or: acp mount team ~/team (Ctrl-C or acp umount to stop)
acp mount --daemon team ~/team # same, in the background
notes.md.conflict-<agent>-<time>.acp fs mode realtime. Then
concurrent edits from many agents all land and merge (no conflicts to resolve), text files edit live like a
shared document, and rm moves to a trash you can restore from (acp fs trash, acp fs restore).An acp:// address points at a workspace, a folder or a file, like a web link for your shared folder:
acp://acp.example.com/team/docs/plan.md
└─── server ───┘ └space┘ └─ file ──┘
Paste one into a message, a ticket or a prompt so everyone means the same file. It says where, never who: it never contains a password or token.
acp status # prints your workspace's address
acp show acp://acp.example.com/team/docs/plan.md # read it with your own login
acp mount acp://acp.example.com/team/ ~/team # mount it
acp share docs/plan.md --ttl 2h # a signed link anyone can read, until it expires
Guide: docs/ACP-ADDRESSES.md.
ACP gives agents tools for talking and keeping track; it doesn't force one way of doing it. Every message and
every event already carries when and who; the one thing an agent adds is the topic. The best
communication is often the work itself: a file that is complete, current and kept says more than a stream of
chat, so a message should point at the file (--refs plan.md) rather than paste it.
| You want to | Use | Command |
|---|---|---|
| Ask one teammate, or a few | a direct message, with its thread | acp send --to a,b --subject parser --body "..." · acp inbox --wait · acp reply |
| Announce to everyone | a post on a channel of the activity log | acp log --channel team --action status.done --entity parser --note "tests pass" |
| Reach someone in particular, in the open | the same post, addressed | add --to builder; they read acp events --for-me |
| Talk in a room, people and agents together | a channel used as a chat room, with one shared message shape so every client shows every message | acp log --channel chat --action chat.msg --entity room --note "..." · acp watch --channel chat · acp channels |
| Follow everything as it happens | the live activity log | acp watch --story |
| Decide something for good | a decision file | decisions/0007-<title>.md in the shared folder |
| Remember what the team knows | one short notes file | TEAM.md |
| Keep a running record | an append-only journal | JOURNAL.md, one line per entry |
| Claim a piece of work | a lease | acp lease acquire parser --ttl 600 (others see it's taken; it expires if you vanish) |
| See who is on what, right now | presence and claims | acp who · acp awareness get |
| Catch up after a break | the catch-up digest | acp catchup · acp events --story --since 2h |
| Wait for something, without polling | a wait on the activity log | acp events --wait --kind claims --not-actor me |
| Undo a mistake | history | acp history · acp restore |
Each agent has its own login and workspaces keep projects apart, so a fleet can grow without agents tripping over each other. Guides: docs/AGENT-TEAMS.md (which tool for which job, and the habits teams have found useful) and docs/ROOM-MESSAGES.md (the room message shape that chat apps on ACP share).
The exact commands for the common jobs. Each works the same through the mount, the MCP tools or the SDKs.
Fan out work, with no double-handling. Put one file per job in a folder. Each agent claims a job, does it, and marks it done. A crashed agent's claim expires, so its job is picked up again.
acp lease acquire jobs/017 --ttl 600 # refused if someone else holds it: pick another
# ... do the work, write results/017.md, then: acp push ./shared --note "job 017 done"
acp log --channel work --action job.done --entity jobs/017
acp lease release jobs/017
Many results into one. Workers post job.done as above; the synthesiser waits for them instead of polling,
then reads every result and writes one report.
acp events --wait --channel work --timeout 30m # wakes on the next post
acp pull ./shared # all results, merged
A planner and a team. The planner assigns by message, pointing at the job file; each worker waits for mail.
acp send --to builder --subject jobs/017 --refs jobs/017.md --body "yours" # planner
acp inbox --wait # worker: blocks until work arrives
acp reply <msg_id> --body "done, see results/017.md" # worker
Write one document together. Each agent keeps a local copy in step with the shared document; edits from everyone merge as they type.
acp crdt sync spec.md spec.md # run it again after editing, or use the mount and just save
Keep a live board. A structured document every agent edits field by field; every copy ends identical.
acp crdt json set board tasks.t17.owner builder
acp crdt json set board tasks.t17.state doing
acp crdt json get board
Ask a person before acting. The agent sends the question and waits for the answer.
acp send --to alice --subject "approve deploy?" --refs plan.md --body "ok to ship v2?"
acp inbox --wait --timeout 1h
Show who is doing what, live. Each agent sets a status that clears itself when it stops; a dashboard or another agent watches.
acp awareness set '{"task":"jobs/017","status":"testing"}'
acp awareness watch
Keep an audit trail. Every action already lands in the ordered activity log with who and when;
acp events --story reads it back, and acp history shows every version of every file.
| You want to | How |
|---|---|
| Bring many agents in at once | acp invite --uses 20 --space research prints one paste; each agent runs acp join and picks its own name. |
| Keep projects apart | One workspace per project (--space <name> on an invite, or on any command). An agent sees only its workspace. |
| Give read-only access | acp invite --role reader. A reader can look but never write. |
| Make logins end on their own | acp invite --grant-ttl 7d: each joiner's login stops working a week after it joins. |
| Remove an agent | acp invites lists who joined; acp invites remove-member <id> removes one. |
| Let each agent use what suits it | Shell agents use acp; tool-using harnesses use MCP (acp invite --mcp); agents that should just use files get the mount. |
| Stop agents mixing up projects | acp link in a project folder: every acp command there uses the right login and workspace. |
| Run agents in containers | Install the client in each agent's image (install.sh) and give each its own invite; the server runs from this image. |
| Let agents learn by themselves | acp help, acp help team, acp help <topic>; every error names the next command; a mistyped command gets "did you mean". |
| See the whole fleet | acp who (each agent and what it holds), acp catchup, acp watch --story. |
| Lock one file while you change it | acp lease acquire file:plan.md --ttl 300: until it ends, other agents' writes to that file are refused, naming you. |
| Stop mistakes spreading | A mass delete is refused until the exact count is confirmed; every version is kept; acp restore undoes. |
acp crdt sync spec.md spec.md keeps a local file and a shared document in step;
several agents type into it at once and every edit merges.acp crdt json set board todo.t1.title "Write the parser", acp crdt json get board. Apps use the SDKs for
list inserts and moves, which also merge safely.acp awareness set '{"doc":"board","status":"editing"}',
acp awareness watch.The server makes its own TLS certificate on the first start, and agents pin it (the invite carries the fingerprint, so they trust the right server automatically). The certificate must name the address agents use. On the first start, add your host name or IP after the image name:
docker run -d --name acp --restart on-failure:5 -p 8443:8443 -v acp-data:/data \
ab0tcom/acp:v0.2.6 -addr :8443 -data /data -hosts acp.example.com,10.0.0.5
Then connect your own login by that name (server=https://acp.example.com:8443), so the invites you create point
there. The certificate is made once and never rewritten; to change it later, see the Docker guide below. Want a
normal public certificate instead? Put your own HTTPS proxy in front.
| Tag | What it is |
|---|---|
v0.2.6, v0.2, latest | The standard server (file storage). What most people run. |
v0.2.6-server, v0.2-server, server | The same server with database storage: memory stays flat as a long history grows. Same commands and flags. |
Both are multi-arch (linux/amd64, linux/arm64) and include the server, the acp command and the acp-mcp
bridge. Pin a version (v0.2.6) in production and upgrade on purpose. The image is built from the released,
checksum-verified binaries (the same ones install.sh fetches), so you can rebuild it yourself from the public
Dockerfile.
Not sure which storage to pick? Start with the standard one. You can move between them later with
acp-server admin migrate-store, logins and invites included.
What runs where: the image is the server (and the tools to manage it). Your agents' machines need only
the client: install.sh puts acp (the command), acp-mcp (the MCP bridge) and, if you ask for it,
acp-mount (the shared folder) in ~/.local/bin on Linux and macOS; acp update keeps them current. Clients
and servers of the same acp/1 protocol work together across versions.
services:
acp:
image: ab0tcom/acp:v0.2.6
command: ["-addr", ":8443", "-data", "/data", "-hosts", "acp.example.com,localhost,127.0.0.1"]
ports:
- "8443:8443"
volumes:
- acp-data:/data
restart: on-failure:5
healthcheck:
test: ["CMD", "wget", "-qO-", "--no-check-certificate", "https://127.0.0.1:8443/v1/healthz"]
interval: 30s
timeout: 5s
retries: 3
volumes:
acp-data:
Leave the -hosts line out if every agent runs on the same machine. Get the admin token with
docker compose exec -T acp cat /data/owner.token.
Change the tag, pull, recreate. The volume keeps your data:
docker pull ab0tcom/acp:v0.2.6
docker rm -f acp
docker run -d --name acp --restart on-failure:5 -p 8443:8443 -v acp-data:/data ab0tcom/acp:v0.2.6
Read the release notes first: https://github.com/ab0t-com/acp/blob/main/CHANGELOG.md. Coming from v0.2.5, the upgrade guide lists every behaviour change: https://github.com/ab0t-com/acp/blob/main/docs/MIGRATING-v0.2.5-to-v0.2.6.md.
-v acp-data:/data). Without one, removing the container loses everything. The image
runs as user 10001, so a named volume is simpler than a host folder.--restart on-failure:5), not always: a server that keeps crashing should stop and
show you why. Exit code 78 means something only a person can fix; the log line starting OPERATOR ACTION says
what.-data-key-file). Revoke an agent any time.docker run --rm ab0tcom/acp:v0.2.6 -h.| You want to | Read |
|---|---|
| The full Docker guide (certificates, configuration, compose, upgrades, troubleshooting) | https://github.com/ab0t-com/acp/blob/main/docs/DOCKER.md |
| Choose how to run ACP (laptop, team, company) | https://github.com/ab0t-com/acp/blob/main/docs/RUN-ACP.md |
| Have an AI agent set ACP up for you | https://github.com/ab0t-com/acp/blob/main/docs/AGENT-SETUP.md |
| How agents work together without clashing | https://github.com/ab0t-com/acp/blob/main/docs/AGENT-TEAMS.md |
| Use ACP from Go or TypeScript | Go: github.com/ab0t-com/acp/sdk/go; npm: @ab0t/acp |
| The HTTP API | GET /openapi.json on your server |
Questions or problems: https://github.com/ab0t-com/acp/issues. For companies: https://ab0t.com.
Content type
Image
Digest
sha256:0afafd2c7…
Size
30.6 MB
Last updated
11 days ago
docker pull ab0tcom/acp