> ## 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.

# Sandbox quickstart

> Create a sandbox, stream its work, send a follow-up prompt, and terminate it.

Sandbox API access is available to every Sparkles user. Open the [API access page](https://sparkles.dev/api) while signed in to create a key for your active WorkOS organization, and include the `sandboxes` scope.

Store the key in a server-side environment variable:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
export SPARKLES_API_KEY='spk_test_…'
```

## 1. Create a sandbox

Use an idempotency key so a network retry cannot create a second sandbox:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl https://sparkles.dev/api/public/v1/sandboxes \
  --request POST \
  --header "Authorization: Bearer $SPARKLES_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: onboarding-example-1" \
  --data '{
    "repos": [{ "fullName": "acme/widgets" }],
    "prompt": "Find and fix the failing unit test, then summarize the change.",
    "title": "Fix the failing test"
  }'
```

The response is queued immediately. Save its `id`, which is also the public sandbox identifier:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
	"id": "c_…",
	"object": "sandbox",
	"status": "queued"
}
```

## 2. Stream the lifecycle

The stream covers boot, agent output, approvals, tools, and completion in one connection. Use a fetch-based SSE client because browser `EventSource` cannot set the authorization header.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -N https://sparkles.dev/api/public/v1/sandboxes/c_…/events/stream \
  --header "Authorization: Bearer $SPARKLES_API_KEY" \
  --header "Accept: text/event-stream"
```

Durable events include an SSE `id`. Reconnect with `Last-Event-ID`, or pass the same value as `?since=` when your HTTP client cannot set that header. Delivery is at least once, so apply events idempotently.

## 3. Send a follow-up

After the first turn settles, the same sandbox can accept another prompt. A stable `promptId` makes retries idempotent.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl https://sparkles.dev/api/public/v1/sandboxes/c_…/messages \
  --request POST \
  --header "Authorization: Bearer $SPARKLES_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "prompt": "Now add a regression test for the fix.",
    "promptId": "regression-test-1"
  }'
```

## 4. Terminate the sandbox

Termination is idempotent:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl https://sparkles.dev/api/public/v1/sandboxes/c_…/terminate \
  --request POST \
  --header "Authorization: Bearer $SPARKLES_API_KEY"
```