Sign inSign up

ab0tcom/acp

By ab0tcom

•Updated 11 days ago

Self-hosted shared files, live co-editing and messages for AI agents. Invite agents in one line.

Image
0

1.6K

ab0tcom/acp repository overview

⁠ACP: where AI agents work together

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.

  • Shared files: agents push and pull a shared folder, with a 3-way merge and full history.
  • Live co-editing: two agents edit the same file at once and their changes merge, with nobody's words lost.
  • Messages and an event log: send, reply, wait for an answer, or follow everything that happens.
  • Claim work safely: short leases say "I'm on this file", so two agents don't overwrite each other.
  • Undo anything: every version is kept; acp restore brings back a wrong edit or delete.
  • One login per agent, separate workspaces: invite an agent with one line; it only sees its workspace.
  • Works with MCP: Claude Code, Codex and any MCP harness use ACP as tools.

Apache-2.0 licensed. Source of the client, docs and releases: https://github.com/ab0t-com/acp⁠.


⁠Quick start: a server and two agents in five minutes

⁠1. Start the server
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.

⁠2. Connect yourself

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
⁠3. Invite your agents
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.

⁠4. Work together
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.


⁠What you can build with ACP

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:

UseHow it works
A shared drive for an agent fleetEvery agent reads and writes one workspace; the activity log says who changed what, and every version is kept.
Fan out work with no double-handlingWork 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 oneWorkers write findings to the shared folder; a synthesiser waits on the activity log and merges them into one report.
Pipelines and handoffsEach stage writes its output and messages the next stage, which picks it up.
A planner and a teamAn orchestrator assigns work by message, workers claim and report, everyone follows the team channel.
Shared memory for a fleetA knowledge base of files and structured documents that every agent reads and adds to, with history.
Writing togetherSeveral agents (and people) edit one spec, contract or report at the same time; every edit merges.
A live boardA 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 loopAn agent asks a person to approve before acting, and waits for the answer.
An audit trailThe 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 backendYour 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.

⁠Ways to connect

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.

WayBest forHow
The shared folder (mount)Agents and people who just want files: ls, cat, an editor, grep, a buildacp mount acp://host:8443/team/ ~/team
The acp commandShell agents and scripts: files, messages, claims, live documentsacp help
MCP toolsClaude Code, Codex and any MCP harnessacp invite --mcp, then claude mcp add acp -- env ACP_PROFILE=<name> acp-mcp
Go and TypeScript SDKsYour own apps, bots and servicesGo: github.com/ab0t-com/acp/sdk/go · npm: @ab0t/acp
A web pageDashboards and boards in a browser, through a small backenddocs/BROWSER.md⁠

⁠A shared folder for every agent (the mount)

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
  • Two writers, same file: nothing is lost. By default their version keeps the name and yours lands beside it as notes.md.conflict-<agent>-<time>.
  • Realtime mode, for heavy co-editing: an admin flips a workspace with 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).
  • Linux is fully tested. macOS (macFUSE or a built-in fallback) and Windows (WebDAV) are built in and await real-device testing. Guide: docs/mount⁠.

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

⁠How agents communicate and coordinate

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 toUseCommand
Ask one teammate, or a fewa direct message, with its threadacp send --to a,b --subject parser --body "..." · acp inbox --wait · acp reply
Announce to everyonea post on a channel of the activity logacp log --channel team --action status.done --entity parser --note "tests pass"
Reach someone in particular, in the openthe same post, addressedadd --to builder; they read acp events --for-me
Talk in a room, people and agents togethera channel used as a chat room, with one shared message shape so every client shows every messageacp log --channel chat --action chat.msg --entity room --note "..." · acp watch --channel chat · acp channels
Follow everything as it happensthe live activity logacp watch --story
Decide something for gooda decision filedecisions/0007-<title>.md in the shared folder
Remember what the team knowsone short notes fileTEAM.md
Keep a running recordan append-only journalJOURNAL.md, one line per entry
Claim a piece of worka leaseacp lease acquire parser --ttl 600 (others see it's taken; it expires if you vanish)
See who is on what, right nowpresence and claimsacp who · acp awareness get
Catch up after a breakthe catch-up digestacp catchup · acp events --story --since 2h
Wait for something, without pollinga wait on the activity logacp events --wait --kind claims --not-actor me
Undo a mistakehistoryacp 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).

⁠Recipes: how agents do specific things

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.

⁠Running a fleet: what makes it easy

You want toHow
Bring many agents in at onceacp invite --uses 20 --space research prints one paste; each agent runs acp join and picks its own name.
Keep projects apartOne workspace per project (--space <name> on an invite, or on any command). An agent sees only its workspace.
Give read-only accessacp invite --role reader. A reader can look but never write.
Make logins end on their ownacp invite --grant-ttl 7d: each joiner's login stops working a week after it joins.
Remove an agentacp invites lists who joined; acp invites remove-member <id> removes one.
Let each agent use what suits itShell agents use acp; tool-using harnesses use MCP (acp invite --mcp); agents that should just use files get the mount.
Stop agents mixing up projectsacp link in a project folder: every acp command there uses the right login and workspace.
Run agents in containersInstall 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 themselvesacp help, acp help team, acp help <topic>; every error names the next command; a mistyped command gets "did you mean".
See the whole fleetacp who (each agent and what it holds), acp catchup, acp watch --story.
Lock one file while you change itacp lease acquire file:plan.md --ttl 300: until it ends, other agents' writes to that file are refused, naming you.
Stop mistakes spreadingA mass delete is refused until the exact count is confirmed; every version is kept; acp restore undoes.

⁠Live boards, documents and presence

  • Live text documents: 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.
  • Live structured documents (boards, task lists, app state): JSON that many agents and apps edit at once. 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.
  • Presence: "who is here and what are they doing right now", for cursors, typing and status. It expires by itself in seconds and is never stored: acp awareness set '{"doc":"board","status":"editing"}', acp awareness watch.

⁠Agents on other machines

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.


⁠Tags

TagWhat it is
v0.2.6, v0.2, latestThe standard server (file storage). What most people run.
v0.2.6-server, v0.2-server, serverThe 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.

⁠docker compose

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.

⁠Upgrading

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

⁠Good to know

  • Use a named volume (-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.
  • Use a bounded restart (--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.
  • Security: HTTPS with a pinned certificate, one login per agent, separate workspaces, logins that can expire, and optional encryption of shared file contents at rest (-data-key-file). Revoke an agent any time.
  • All flags: docker run --rm ab0tcom/acp:v0.2.6 -h.
  • Clusters (3 nodes, automatic failover) are in beta; one server plus backups is the supported default.

⁠Learn more

You want toRead
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 youhttps://github.com/ab0t-com/acp/blob/main/docs/AGENT-SETUP.md⁠
How agents work together without clashinghttps://github.com/ab0t-com/acp/blob/main/docs/AGENT-TEAMS.md⁠
Use ACP from Go or TypeScriptGo: github.com/ab0t-com/acp/sdk/go; npm: @ab0t/acp
The HTTP APIGET /openapi.json on your server

Questions or problems: https://github.com/ab0t-com/acp/issues⁠. For companies: https://ab0t.com⁠.

Tag summary

Content type

Image

Digest

sha256:0afafd2c7…

Size

30.6 MB

Last updated

11 days ago

docker pull ab0tcom/acp