Skip to content

Tutorial 5 · Open a Barista session in Zed (ACP)

Goal: drive a Barista session's agent from Zed (or any ACP client) over the Agent Client Protocol, so you get a native editor UI over a pausable, memory- preserving session — close Zed, the session freezes; reopen tomorrow, the agent is exactly where it was.

Prereq: the one-time setup (the barista CLI + barista login).

How it fits together

ACP clients launch the agent as a local process and talk over stdio — there is no "connect to a URL". So Zed launches barista acp, a bridge that pipes its stdio to the session's ACP agent over the attach WebSocket:

Zed ──stdio(ACP)──> barista acp ──wss──> session ──> claude-code-acp

barista acp auto-provisions the session on first use (creates it, installs the agent, waits for ready) and resumes it if it was paused — so there is no separate create/wait step.

Step 1 — point Zed at Barista

In Zed: Agent Settings → External Agents → Add Agent → Add Custom Agent. Zed opens your settings; make the entry:

"agent_servers": {
  "Barista": { "type": "custom", "command": "barista", "args": ["acp"], "env": {} }
}

"type": "custom" is required (without it Zed's linter flags "Missing property 'type'"). args: ["acp"] uses the default session named acp; use ["acp", "myname"] for a differently-named session.

Step 2 — open it and authenticate

Open Zed's agent panel and pick Barista. On first launch it provisions the session (~30–40s, one time; it's instant after that). When the agent asks to authenticate, use Zed's Authenticate button ("Log in with Claude Code") — no API key to export. (Prefer a key? Set ANTHROPIC_API_KEY in the env block above and it's forwarded to the agent.)

You're now driving Claude Code inside a pausable Barista session — with Zed's diffs, @-mentions, and history.

Step 3 — freeze and come back

barista pause acp     # stop the clock; the VM (files + memory) is frozen
# …later…
barista resume acp    # or just reopen in Zed — `barista acp` resumes it for you

Reopen the agent in Zed — the bridge reconnects and the agent reopens the same conversation from the session's persistent volume, working tree intact.

Notes

  • The ACP agent process is per-connection — closing Zed ends it. Continuity comes from the agent's on-disk session store on the session's persistent volume plus Barista's pause/resume of the whole microVM, not from keeping the process alive.
  • Auto-provision uses a public, digest-pinned base image and installs the agent at boot (no registry or local Docker needed). For an instant first launch, prebake an image (../../demos/claude-code/) and create the session from it, then barista acp <that-session> --no-ensure.
  • barista attach (raw PTY) is still there for shells and terminal agents; acp is the same seam with a clean duplex for protocol clients.

The code lives in the session — pull it with barista sync

The agent edits inside the session (/work), not on your laptop — so editing and running commands agree (this is what barista acp ensures by not handing the agent your local filesystem; pass --client-fs to opt out). Zed shows the conversation and diffs; the files stay in the sandbox.

When you want the code locally, pull it — one-way, on demand, like Amp's amp sync:

barista sync <session> [dir]     # /work -> ./<session> (git history preserved if it's a repo)

Clean up

barista rm acp

Back to the tutorials index.