> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sparkles.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Sandboxes

> Create, inspect, control, and publish work from organization-scoped coding sandboxes.

A sandbox is an asynchronous coding-agent job owned by the API access grant that created it. Its public `id` starts with `c_`; internal session identifiers, agent URLs, preview ports, and credentials are never returned.

## Access model

Sandbox requests require all of the following:

* an active API access grant bound to a WorkOS organization;
* an active key with the `sandboxes` scope;
* a live organization membership for the grant's WorkOS user; and
* exact ownership by the same access grant for every read or command.

Looking up a sandbox from another grant returns `404`, including when both grants belong to the same organization.

## Lifecycle

The `status` field has seven values:

| Status        | Meaning                                  |
| ------------- | ---------------------------------------- |
| `queued`      | Accepted and waiting to boot.            |
| `creating`    | Runtime resources are being prepared.    |
| `running`     | The sandbox can execute or accept work.  |
| `succeeded`   | The sandbox completed successfully.      |
| `failed`      | The sandbox stopped because of an error. |
| `terminating` | An explicit termination is in progress.  |
| `terminated`  | The sandbox was explicitly shut down.    |

Treat `GET /api/public/v1/sandboxes/{id}` as the source of truth. Streaming lifecycle frames and webhooks are notifications that tell you when to reconcile.

## Create requests

Creation accepts repositories, an initial prompt, optional model and reasoning settings, a title, approval mode, and up to 16 string metadata entries. Request bodies are limited to 64 KiB. Sparkles selects the standard runtime, organization visibility, and the execution region server-side.

Pass `Idempotency-Key` for safe retries. Reusing a key with the same normalized request returns the existing sandbox once its row exists; a retry that arrives earlier returns `409 idempotency_in_progress`. Using the key with different details returns `409 idempotency_conflict`. A failed creation releases its lease so the same request can be retried.

Each access grant has a concurrent-sandbox limit. Creation and terminal-sandbox restart checks are serialized under the grant lock so concurrent requests cannot exceed the limit.

## Read and list

List sandboxes with an optional `status` or `repo` filter. Pagination uses an opaque `after` cursor and a maximum page size of 100. The resource response deliberately whitelists public fields: status, repositories, selected model and runtime, current turn, usage rollup, metadata, error, timestamps, and links.

Usage is eventually consistent while inference settlements are still in flight.

## Commands

* `POST /messages` queues a follow-up prompt. Supply `promptId` to deduplicate retries. A terminal job can restart, subject to the same concurrency cap.
* `POST /interrupt` aborts the latest running agent session.
* `POST /approvals/{approvalId}` resolves a pending tool approval with `approve` or `deny`.
* `POST /terminate` idempotently shuts down the sandbox without purging its history.

Command responses are receipts. They acknowledge durable acceptance, not completion; observe the stream or resource state for the outcome.

## Files and pull requests

The v1 file API is read-only. List a live sandbox's file tree or load a bounded text document; file writes remain agent-driven. Pull-request creation uses Sparkles' short-lived, repository-scoped GitHub App credentials and always creates or reuses a draft pull request.

`GET /files/download?path=…` streams one working-tree file from a running sandbox as an attachment. Sparkles reads the bytes over the sandbox's ACP agent connection, so downloads need a running sandbox with a live agent; files above 100 MiB, protected files such as `.env`, and `.git` contents are refused.