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

# Create & Manage Sandboxes

> Resources, start commands, timeouts, labels, and cleanup

## Create a sandbox

```bash CLI theme={null}
prime sandbox create python:3.11-slim \
  --name analytics-lab \
  --cpu-cores 2 \
  --memory-gb 4 \
  --disk-size-gb 20 \
  --timeout-minutes 240
```

```python Python theme={null}
sandbox = client.create(
    CreateSandboxRequest(
        name="analytics-lab",
        docker_image="python:3.11-slim",
        cpu_cores=2,
        memory_gb=4,
        disk_size_gb=20,
        timeout_minutes=240,
    )
)
client.wait_for_creation(sandbox.id)
```

* Omit `--name` to auto-generate a slug.
* Pass `--team-id` to charge a different workspace.
* Add `--yes` to skip the confirmation prompt in automation.
* In the SDK, pass `idempotency_key` to make create retries safe: requests that share a key are deduplicated, so a network failure mid-create can be re-run without producing a second sandbox.

The image can be a Docker Hub image or a [Prime Image](./images#image-references). See [Limits](./overview#limits) for resource ranges and defaults.

## Start command

Run your own process when the sandbox boots. There is no shell, so the executable and each argument are separate values:

```bash CLI theme={null}
prime sandbox create python:3.11-slim -- python serve.py --port 8000
```

```python Python theme={null}
from prime_sandboxes import StartCommand

sandbox = client.create(
    CreateSandboxRequest(
        name="api-server",
        docker_image="python:3.11-slim",
        start_command=StartCommand(executable="python", args=["serve.py", "--port", "8000"]),
    )
)
```

To get shell features (pipes, variables, `&&`), invoke a shell explicitly: `-- /bin/sh -c "python serve.py --port 8000"` on the CLI, or `StartCommand(executable="/bin/sh", args=["-c", "python serve.py --port 8000"])` in Python.

The start command is one-shot: when the process exits, the sandbox stops. Omit it to keep the sandbox up and ready for [commands](./commands).

## Timeouts

The timeout caps total lifetime (default 60 minutes). Set it to any negative value to remove the lifetime deadline.

The idle timeout terminates the sandbox sooner when nothing is using it, which is useful for agent workflows that might forget to clean up:

```bash CLI theme={null}
prime sandbox create python:3.11-slim \
  --timeout-minutes -1 \
  --idle-timeout-minutes 15
```

```python Python theme={null}
sandbox = client.create(
    CreateSandboxRequest(
        name="idle-aware",
        docker_image="python:3.11-slim",
        timeout_minutes=-1,
        idle_timeout_minutes=15,
    )
)
```

Any command, upload, download, or file read resets the idle clock. Long-running commands stay pinned for their full duration.

* Disabled by default.
* Must be between 1 and 1,440 minutes. For a finite lifetime, it must not exceed the timeout.
* SSH sessions do **not** count as activity.

A sandbox that shuts down this way reports `termination_reason="idle_timeout"` in the SDK, and **Idle Timeout** in `prime sandbox get` and on the dashboard.

## Labels

Tag sandboxes by project, team, or environment, then filter or bulk-delete by label:

```bash CLI theme={null}
prime sandbox create python:3.11-slim --label experiment --label ml-pipeline

# Must have ALL labels
prime sandbox list --label experiment --label ml-pipeline
```

```python Python theme={null}
sandbox = client.create(
    CreateSandboxRequest(
        name="tagged",
        docker_image="python:3.11-slim",
        labels=["experiment", "ml-pipeline"],
    )
)
```

## Inspect

```bash theme={null}
# Overview at a glance
prime sandbox list --status RUNNING --output table

# Rich details for one sandbox
prime sandbox get sbx_123 --output json
```

## Delete

```bash CLI theme={null}
# By ID (space or comma-separated)
prime sandbox delete sbx_123 sbx_456 sbx_789

# Everything matching ALL given labels
prime sandbox delete --label experiment --label staging --yes

# Every active sandbox you own (careful!)
prime sandbox delete --all --yes

# Team admins: the whole team, or one teammate
prime sandbox delete --all --all-users --yes
prime sandbox delete --all --user <user-id> --yes
```

```python Python theme={null}
client.delete("sbx_123")

# Bulk delete by IDs or by labels (not both)
result = client.bulk_delete(sandbox_ids=["sbx_456", "sbx_789"])
result = client.bulk_delete(labels=["experiment", "staging"])
print(f"Deleted: {result.succeeded}, Failed: {result.failed}")
```

On the CLI, use exactly one of: sandbox IDs, `--label`, or `--all`. `--all` and `--label` deletes run as a single server-side scoped delete: by default they cover your own sandboxes, `--all-users` covers the whole team, and `--user <user-id>` covers one teammate (both admin-only). The CLI prints a count preview before deleting, and per-sandbox results for explicit IDs.

## Troubleshooting

* Sandbox stuck in `PENDING` the first time you use an image? Prime is converting it into a VM image, which can take a few minutes. See [VM images](./images#vm-images).
* Stuck in `PROVISIONING`? Wait a minute, then rerun `prime sandbox list --status RUNNING`. If it stays pending, delete and recreate from a known-good image.
* Auth errors on transfers? `prime sandbox reset-cache` (CLI) or `client.clear_auth_cache()` (SDK) refreshes the gateway token after you rotate API keys.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.