Create & Manage Sandboxes

Create a sandbox

prime sandbox create python:3.11-slim \
  --name analytics-lab \
  --cpu-cores 2 \
  --memory-gb 4 \
  --disk-size-gb 20 \
  --timeout-minutes 240

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. See 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:

prime sandbox create python:3.11-slim -- python serve.py --port 8000

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.

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:

prime sandbox create python:3.11-slim \
  --timeout-minutes -1 \
  --idle-timeout-minutes 15

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:

prime sandbox create python:3.11-slim --label experiment --label ml-pipeline

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

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

Inspect

# Overview at a glance
prime sandbox list --status RUNNING --output table

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

Delete

# 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

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

Getting Started

Inference

Model Factory

Community

Compute

Traces

Libraries

Create a sandbox

Start command

Timeouts

Labels

Inspect

Delete

Troubleshooting

​Create a sandbox

​Start command

​Timeouts

​Labels

​Inspect

​Delete

​Troubleshooting

Create a sandbox

Start command

Timeouts

Labels

Inspect

Delete

Troubleshooting