Agent Sandboxes

Agent Sandboxes are isolated, short-lived Linux environments that AI agents (or any program) use to run untrusted code, shell commands, builds, and tests. Each sandbox runs your own container image under gVisor, with its own kernel boundary, on Quave ONE infrastructure or on your own nodes. Quave ONE owns the whole lifecycle: allocation, readiness, idle termination, maximum lifetime, pause and resume, persistence, and billing.

You drive sandboxes through the Public API, the MCP server (so an AI client can manage them directly), or the Sandboxes page of the dashboard.

What you can do

• Run any OCI image. Bring your own image (Python, Node.js, a full coding-agent toolchain, anything Linux) pinned by digest, so every sandbox runs exactly the bits you approved.
• Run commands and get results. Run a command to completion and get its exit code, stdout, and stderr back in the same call. Pass secrets per command; they are never stored.
• Run long jobs, files and terminals. Open a gateway session to start processes that run for hours and stream their output, read and write workspace files, and drive interactive terminals. See Processes, files and terminals.
• Keep work between runs. Choose a persistence mode: throw everything away, keep a live directory on object storage, snapshot the whole workspace at pause, or both. Reuse the same volume in a later sandbox to continue where the previous one stopped.
• Use your own bucket. Sandbox data can live on the Quave ONE object storage point of the region or on your own S3-compatible bucket, with your own encryption key.
• Pause and resume. Pause a sandbox to release its compute (no charge while paused) and resume it later with the same id. Running a command on a paused sandbox resumes it automatically.
• Restrict egress. Limit outbound traffic to IP/CIDR ranges, domains, or both. Internal infrastructure ranges are always blocked.
• Retry safely. Creation is idempotent by a key you choose, so a retried request reconnects to the same sandbox instead of creating a second one.
• Scale. Sandboxes run on autoscaling node pools. There is no per-app limit; only an account-wide safety ceiling (200 active sandboxes by default, raisable on request) stops a runaway loop.

Core concepts

Concept	What it is
Template	A named, reusable sandbox definition, such as python-workspace. Agents ask for a template by id.
Revision	An immutable version of a template: image digest, command, size, persistence defaults, timeouts, egress rules. A new sandbox uses the latest revision; a running sandbox keeps the revision it started with. To change anything, append a new revision.
Sandbox	One running instance of a revision, in one region, attached to an app of your account.
App	Every sandbox and (optionally) template belongs to a Quave ONE app. It groups sandboxes for permissions, limits, and cleanup. A plain app with no environments is enough.
Owner	A typed reference (ownerKind + ownerId) to whatever the sandbox works for in your system: a conversation, a run, a session. Quave ONE stores it so you can find and audit sandboxes by owner.
Idempotency key	A key you choose per logical request. The same account, app, caller, and key always resolve to the same sandbox.
Persistence mode	EPHEMERAL, DIRECTORY, SNAPSHOT, or BOTH. See Persistence and volumes.
Shared volume	An object storage volume of your account that holds a sandbox's persistent data. It outlives the sandbox and can be attached to the next one.

Lifecycle

REQUESTED → ALLOCATING → STARTING → READY ⇄ BUSY
                                      │
                       pause ─────────┤──────── terminate / idle timeout / max lifetime
                                      ▼                          ▼
                     SUSPENDING → SUSPENDED → RESUMING → READY   TERMINATING → TERMINATED

• A new sandbox becomes READY after allocation and start. When the sandbox pool has a node with room, that takes a few seconds. When the pool has to add a node first, allow a few minutes.
• READY and BUSY sandboxes accept commands.
• Idle timeout and maximum lifetime (from the revision) terminate the sandbox. They never pause it.
• FAILED sandboxes carry a stable errorCode and errorRetryable flag.

Before you start

1. Access. Agent Sandboxes are enabled per account by Quave ONE. If a sandbox call answers 403 with a missing entitlement, ask Quave ONE support to enable Agent Sandboxes for your account.
2. A region with Agent Sandboxes. The region must be enabled for your account and have the Agent Sandbox add-on. A create request in a region without it answers 409 (Agent Sandbox is not enabled in this region). On Connect, ask Quave ONE to enable the add-on on your region.
3. An app. Create one in the dashboard or with the Apps API (create-app over MCP). It does not need any environment.
4. A token. A user token, or an MCP/OAuth token with the scopes below. Environment tokens are not accepted, because a sandbox records the person or principal who requested it.

Operation	Scope
List and read templates, sandboxes, volumes	quave:read
Create templates and revisions	quave:write:config
Create, pause, resume, terminate sandboxes	quave:write:deploy
Execute commands, remove volumes	quave:write:dangerous

Read operations need account membership. Changes need an admin or technical member of the account.

Where to go next

• Quickstart: template, sandbox, command, pause, resume, cleanup, step by step.
• Templates and images: build an image, pin it, and choose sizes, timeouts, and egress.
• Persistence and volumes: keep work across sandboxes, use your own bucket.
• Running commands: command semantics, long-running work, limits, and error handling.
• Processes, files and terminals: gateway sessions for long processes with streamed output, file transfer, and terminals.
• Agent Sandboxes API reference and Shared Volumes API reference.
• Pricing.

Instructions for AI agents

If you are an AI agent asked to use Quave ONE Agent Sandboxes, follow this checklist:

1. Find the account (get-current-account) and an app (list-apps; create one with create-app if none fits).
2. Reuse an existing template when one fits (list-sandbox-templates, get-sandbox-template). Otherwise create one with save-sandbox-template and give it a revision with create-sandbox-template-revision. Use a digest-pinned image (image@sha256:<64 hex>) and a long-running command such as ["sleep", "infinity"].
3. Create the sandbox with create-sandbox, using a stable idempotencyKey derived from your task, so retries never duplicate it. Pick workloadProfile and the matching ownerKind (see Workload profiles).
4. Poll get-sandbox every 2–5 seconds until status is READY. Stop on FAILED and read errorCode/errorRetryable.
5. Run commands with execute-sandbox-command. Decode result.stdout/result.stderr from base64 before reading them. The command is an argv array, never a shell string; use ["sh", "-c", "..."] for pipes and redirects. Keep each call under 900 seconds. For longer work, use start-sandbox-command, then get-sandbox-command with nextSeq until state is exited (see Long-running work). For file transfer, a live stream or a terminal, open a gateway session (POST /sandbox/session) and use the gateway API.
6. Keep files you need later under the mount path (default /workspace/persist) in DIRECTORY or BOTH mode.
7. When done, terminate-sandbox. If you will continue later and the mode keeps data, pause-sandbox instead. Remove volumes you no longer need with remove-shared-volume. Terminating never deletes data.
8. On 429, wait data.retryAfterSeconds and retry with the same idempotency key. On 409 with data.retryable: true, wait and retry. Do not retry 403; report it to the user.