| sidebar_position | 22 |
|---|---|
| title | sandbox |
Provision concurrent agent sandboxes (copy-on-write working trees).
atomic sandbox <SUBCOMMAND>
atomic sandbox create <NAME> [--dest <PATH>] [--view <VIEW>] [--from <VIEW>]
atomic sandbox stage <VIEW> --out <DIR> [--base <VIEW>]
atomic sandbox seal <VIEW> --out <DIR> [--entrypoint <ARG>] [--env <KEY=VAL>]
atomic sandbox open <VIEW> [--acting-as <DID>] [--ttl <SECS>] [--capability <CAP>] [--dest <DIR>]
atomic sandbox renew <VIEW> [--ttl <SECS>]
atomic sandbox close <VIEW>
atomic sandbox materialize [--prefix <PATH>]atomic sandbox creates isolated working environments for concurrent agents. Multiple AI agents working in the same directory contend for the same working copy; a sandbox gives each agent its own copy-on-write clone of the working tree so they can record changes in parallel without stepping on each other.
Sandboxes compose with views: by default a sandbox operates on the current view, but with --from it creates a new draft view (named after the sandbox) and points the sandbox at it — each agent then works in its own view, exactly like the multi-agent view hierarchy.
Sandboxes also bridge to the container world:
stagepackages a sandbox's draft view as a layered OCI image — a shared base plus a thin delta — so identical bases are stored once across many sandboxes.sealflattens a view into a self-contained OCI runtime image with a fixed entrypoint and environment, suitable for running or shipping.open/renew/closegrant, extend, and revoke a remote sandbox's access to one view, with a TTL and explicit capabilities.materializeruns inside a remote sandbox to write its view's tree and cache.
atomic sandbox create <NAME> [OPTIONS]<NAME> — Name of the sandbox (used in the default destination path).
| Option | Description |
|---|---|
--dest <PATH> |
Destination directory for the sandbox working tree |
--view <VIEW> |
View the sandbox operates on (defaults to the current view) |
--from <VIEW> |
Create a new draft view (named after the sandbox) from this view, and point the sandbox at it |
# Sandbox on the current view
atomic sandbox create fix-auth
# Sandbox on its own fresh draft view forked from dev
atomic sandbox create fix-auth --from dev
# Custom location
atomic sandbox create review --dest /tmp/review-treeEach sandbox can record its own changes; because the clone is copy-on-write, creating many sandboxes is cheap.
atomic sandbox stage <VIEW> --out <DIR> [OPTIONS]<VIEW> — The view to stage (the sandbox's draft view).
| Option | Description |
|---|---|
--base <VIEW> |
The shared base view the delta is computed against (default: dev) |
-o, --out <DIR> |
Output directory for the OCI image layout |
# Stage the fix-auth draft view as a thin delta over dev
atomic sandbox stage fix-auth --base dev -o out/ociThe result is an OCI image layout whose layers are the shared base view plus only the changes the sandbox introduced — ideal when staging many sandboxes from one base.
atomic sandbox seal <VIEW> --out <DIR> [OPTIONS]<VIEW> — The view to seal.
| Option | Description |
|---|---|
-o, --out <DIR> |
Output directory for the OCI image layout |
--entrypoint <ARG> |
Image entrypoint argv (repeatable), e.g. --entrypoint /app/run |
--env <KEY=VAL> |
Image environment variable (repeatable), e.g. --env PORT=8080 |
# Seal a view into a runnable image
atomic sandbox seal release-candidate -o out/oci \
--entrypoint /app/run --env PORT=8080Unlike stage, the sealed image is flattened and self-contained — no shared base required.
atomic sandbox open <VIEW> [OPTIONS]<VIEW> — The view the sandbox reaches.
| Option | Description |
|---|---|
--acting-as <DID> |
The identity the sandbox's work is attributed to (an agent's DID) |
--ttl <SECS> |
How long the grant lasts, in seconds (1..31536000; renew with atomic sandbox renew) (default: 7200) |
--capability <CAP> |
A capability to grant (repeatable). Defaults to reading and submitting the view, its provenance, and its vault |
--dest <DIR> |
Write the pointer into this directory (created if needed, mode 0600) instead of printing it |
# Grant a sandbox read/submit access to feature-auth for 2 hours
atomic sandbox open feature-auth --acting-as did:atomic:agent-01
# Grant for 30 seconds with the pointer written to a specific dir
atomic sandbox open feature-auth --ttl 30 --dest /tmp/sandbox-pointeratomic sandbox renew <VIEW> [--ttl <SECS>]Extend a remote sandbox's grant. --ttl is the new lifetime from now, in seconds (default: 7200).
atomic sandbox close <VIEW>Revoke a remote sandbox's grant now.
atomic sandbox materialize [--prefix <PATH>]Inside a remote sandbox: write its view's tree and make its cache.
| Option | Description |
|---|---|
--prefix <PATH> |
Materialize only entries at or under this path (a monorepo folder), plus the directories that lead to it. Default: the whole view |
# Inside the sandbox: fetch only the crates/ subtree
atomic sandbox materialize --prefix crates/- view — Views and the filter hierarchy sandboxes attach to
- session — The agent session ledger
- agent lifecycle — Declaring managed agent runs
- multiple-ai-agents guide — Sandboxes for multi-agent isolation