Tutorial 6 · An agent in a pausable sandbox¶

Goal: run a coding agent unsupervised in a remote sandbox that holds the code, driven from your editor, and pausable — freeze it mid-task, resume later with memory intact. Any harness works (Claude Code here; Codex or your own just as well). You watch and steer from Zed; the code lives in the session; you pull the result down with barista sync.

Every step below is live-verified end-to-end — it's a showcase, not aspiration.

Prereq: the one-time setup, Zed wired to Barista (Tutorial 5), and your ANTHROPIC_API_KEY.

The loop at a glance¶

attach a session  →  give the agent a task in Zed  →  it edits + runs in /work
      →  pause mid-task (freeze)  →  resume later (exactly where it was)
      →  barista sync the finished code down

Step 1 — a sandbox with an agent in it¶

The fast path: barista acp provisions a session (installs the agent — no registry, no local Docker) and bridges Zed to it. In Zed's settings (see Tutorial 5 for the walkthrough):

"agent_servers": {
  "Barista": {
    "type": "custom", "command": "barista", "args": ["acp", "dev"],
    "env": { "ANTHROPIC_API_KEY": "sk-ant-…" }
  }
}

Open Zed's agent panel → Barista. First launch provisions the session dev (~30–40s, one time), then you're in Claude Code, working in the session's /work.

Working on an existing repo? Two ways to get it in: bake it into an image (../../demos/claude-code/), or just tell the agent to git clone <url> into /work as its first step.

Step 2 — give it a real task¶

In the agent panel, in plain language:

create calc.py with add(), mean(), and fib() functions plus pytest tests for each,
then run the tests and fix any failures

Claude Code plans, writes the files, and runs pytest — all inside the sandbox. You watch the diffs and tool calls stream into Zed. The files land in the session's /work, not on your laptop: barista acp keeps the agent's edits and its shell in the same place, so when it runs the tests it's testing the code it just wrote. (Why it matters is in session-archetypes.md.)

Step 3 — pause mid-task, walk away¶

Mid-run, freeze the session from a terminal:

barista pause dev

The whole microVM freezes — working tree and memory held, zero CPU. Close your laptop; nothing is running.

Step 4 — resume, exactly where it was¶

barista resume dev

Reopen Barista in Zed — the agent continues its conversation and the working tree is untouched. On the KVM node it's restored from its memory snapshot, so it's the same session, not a cold restart.

Step 5 — pull the finished code down¶

When you're happy, pull /work to your machine — one-way, on demand:

barista sync dev ./dev-out
# cloned dev:/work -> ./dev-out (git history preserved)

If /work is a git repo you get the commits and history; otherwise the files. Review, keep, or commit locally.

Clean up¶

barista rm dev

How it compares¶

The "agent works unsupervised in a remote sandbox, sync the result down" model isn't unique — Amp offers a hosted version. Barista's take differs in two ways that matter:

Any harness. The sandbox runs any agent (Claude Code here via claude-code-acp, Codex, or your own baked into the image), because Barista is the substrate, not a bundled agent.
Pausable. Freeze mid-task and resume with memory intact; you're metered on memory-GiB-hours held, not wall-clock minutes. (The full cost model — and the park-to-storage path that drives idle toward free — is in session-archetypes.md.)

"Bring your own harness, get a pausable remote sandbox with sync." Setup and auth details live in Tutorial 5 · Session in Zed.