> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.modbox.run/llms.txt.
> For full documentation content, see https://docs.modbox.run/llms-full.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.modbox.run/_mcp/server.

# Sandboxes

A **sandbox** is the core primitive in Modbox — a running container instance with its own URL, lifecycle, and resource limits.

## Lifecycle

```
                  ┌──────────────────────────────────────┐
   provision ───► │         PROVISIONING                 │
                  │  Modbox is scheduling the container  │
                  └──────────────┬───────────────────────┘
                                 │  sandbox ready
                                 ▼
                  ┌──────────────────────────────────────┐
                  │           RUNNING                    │
                  │  sandbox_url is accessible           │
                  └──────────────┬───────────────────────┘
                                 │  destroy() or TTL expires
                                 ▼
                  ┌──────────────────────────────────────┐
                  │           DESTROYED                  │
                  │  all sandbox resources deleted       │
                  └──────────────────────────────────────┘
```

## Provision

Create a new sandbox. This is always async — the API returns immediately with `status: provisioning`.

```bash
POST /sandboxes/provision
```

```json
{
  "task_id": "my-sandbox",         // unique identifier — used to reference the sandbox
  "image_id": "uuid-of-your-image", // optional, uses workspace default if omitted
  "ttl_seconds": 300,               // optional, auto-destroy after this many seconds
  "env_vars": {                     // optional, injected into the container
    "MY_VAR": "my-value"
  }
}
```

The `task_id` is **your** identifier for the sandbox. Choose something meaningful like `agent-{session_id}` or `pr-{pr_number}`.

## Wait for ready

After provisioning, poll for ready or use the blocking wait endpoint:

```bash
# Option A: blocking wait (recommended)
POST /sandboxes/wait
{ "task_id": "my-sandbox", "timeout": 120 }

# Option B: poll the detail endpoint
GET /sandboxes/detail/{sandbox_id}
```

Once `status` is `running`, the `sandbox_url` field contains the live HTTPS endpoint.

## List sandboxes

```bash
GET /sandboxes
GET /sandboxes?status=running
GET /sandboxes?status=provisioning
```

Pass `X-Workspace-Id` to filter by workspace.

## Destroy

```bash
POST /sandboxes/destroy
{ "task_id": "my-sandbox" }
```

This immediately deletes all sandbox resources. The sandbox moves to `status: destroyed`.

## TTL (time-to-live)

If a `ttl_seconds` is set when provisioning, the sandbox is automatically destroyed after that many seconds — even if you never call destroy. This is the recommended way to avoid resource leaks.

```json
{
  "task_id": "my-sandbox",
  "ttl_seconds": 3600
}
```

Always set a TTL for agent-driven sandboxes. If your agent crashes or your backend goes down, the sandbox will still be cleaned up automatically.

## Sandbox fields

| Field          | Type                                   | Description                                            |
| -------------- | -------------------------------------- | ------------------------------------------------------ |
| `id`           | UUID                                   | Internal sandbox ID                                    |
| `name`         | string                                 | Same as your `task_id`                                 |
| `status`       | `provisioning \| running \| destroyed` | Current lifecycle state                                |
| `sandbox_url`  | string                                 | HTTPS URL of the running sandbox (only when `running`) |
| `image`        | string                                 | Docker image tag used                                  |
| `created_by`   | string                                 | User ID of the provisioning user                       |
| `created_at`   | datetime                               | When provisioning was requested                        |
| `destroyed_at` | datetime                               | When the sandbox was destroyed (if applicable)         |