Sandboxes

A sandbox is the isolated environment where an agent's code runs. Each run gets its own sandbox, provisioned at start and torn down at the end.

What isolation gives you

• Containment. A run can't affect other runs, other workspaces, or the host.
• Reproducibility. Every run starts from the same base image with the same dependencies.
• Resource quotas. CPU, memory, disk, and network are bounded per sandbox.

What's inside

Every sandbox is provisioned with the things the agent needs and nothing else:

• The agent's code and current version.
• The resources you've declared.
• The tools it's allowed to call.
• Credentials to reach your own model provider, or ours.

Sandboxes are ephemeral by default: they're destroyed when the run finishes. Anything the agent needs to keep goes into the session or a durable resource.

Persistent workspaces

Some agents build up a working set that's expensive to recreate — a cloned repository, downloaded datasets, a report that evolves across runs. For those, switch the agent to a persistent workspace in its settings (or set workspace_scope: "agent" in the agent's config via the API). The agent then keeps one durable working directory that carries over between conversations and runs, instead of starting empty each time.

For the built-in Levain assistant, persistence is per person: each workspace member gets their own durable working directory with the assistant, so your files carry across your conversations without appearing in anyone else's. In Slack this follows your Slack profile email — it should match the email you use with Levain.

Three things change when it's on:

• Runs execute one at a time per volume. A dispatch while another run holds the same workspace returns 409. Scheduled fires that collide simply coalesce onto the running one, and in Slack the agent asks you to resend in a moment. With per-person persistence this only ever means your own concurrent conversations take turns — never someone else's.
• State persists. Files an earlier run left behind — including anything a misled run wrote — stay visible to every future run. A self-serve reset is on the way; until then, reach out and we'll wipe the workspace for you.
• Storage accumulates. Nothing expires automatically; large datasets sit on the volume until the workspace is wiped or the agent is deleted.

Fresh-by-default remains the recommendation for agents that don't need it: a clean workspace per conversation is easier to reason about and runs concurrently.

Inspecting a sandbox

While a run is live, you can query its sandbox to see real-time resource use:

• GET /api/v1/sandboxes/ lists every sandbox in your workspace.
• GET /api/v1/sandboxes/{sandbox_id} returns status, resource use, and the run it's attached to.

Direct sandbox interaction is uncommon in day-to-day use; the endpoints above are mainly for inspection and debugging.