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

# Sandboxes Overview

> Why sandboxes exist, how to launch one, and what it costs

## Why Sandboxes

Prime Sandboxes are disposable, isolated environments for AI-assisted coding, benchmarking, and quick experiments. They give agents and humans a clean workspace without touching production infrastructure. New sandboxes are [VM sandboxes](#vm-sandboxes) by default.

<Warning>
  **Container sandboxes are being deprecated.** Sandboxes now run as virtual machines by default. You can still opt into the container runtime with `--container` on the CLI or `vm=False` in the SDK, but plan to migrate.
</Warning>

<img src="https://mintcdn.com/primeintellect/27DA8i_ikZGh6lgH/images/sandboxes/sandbox_dashboard.png?fit=max&auto=format&n=27DA8i_ikZGh6lgH&q=85&s=e6959f8950f0355be2688738a5a20403" alt="Sandbox Dashboard" width="4293" height="2160" data-path="images/sandboxes/sandbox_dashboard.png" />

### Popular moves

* **Prototype quickly** – launch a clean runtime and iterate without worrying about teardown.
* **Benchmark safely** – run untrusted code or model evaluations in a locked-down environment.
* **Run AI agents securely** – restrict where code can reach with network allow/deny lists.
* **Inject secrets safely** – pass API keys, passwords, and tokens as encrypted secrets that never appear in logs or API responses.
* **Teach & demo** – hand teammates a reproducible workspace that mirrors your setup.
* **Use custom images** – push your own Docker images and use them in sandboxes with all your dependencies pre-installed.
* **Organize with labels** – tag sandboxes by project, team, or environment for easy filtering and bulk cleanup.

## VM Sandboxes

VM sandboxes boot an OCI/Docker image as the root filesystem of a hardware-isolated microVM. Use them when you need a stronger isolation boundary or VM-only egress controls.
VM sandboxes were built with agentic RL in mind. They offer:

* **Full VM fidelity** - supports Docker, systemd, background services, and kernel-dependent workloads.
* **Fast startup** - we can start thousands of concurrent sandboxes in seconds, with image-aware scheduling for heterogeneous training runs.
* **Latency** – commands come back noticeably faster.
* **GPUs** – GPU sandboxes are VM-only (coming soon).
* **Snapshots** - save, restore, and fork a sandbox mid-run, preserving & branching your trajectories (coming soon).

VM sandboxes are used by default. To opt back into container sandboxes:

```bash theme={null}
prime sandbox create python:3.11-slim --container
```

## First Run

Make sure you have an API key with the right permissions on hand (`prime login`) before running these commands.

```bash theme={null}
# Create
prime sandbox create python:3.11-slim --timeout-minutes 120

# See what is active
prime sandbox list

# Try a quick command
prime sandbox run <sandbox-id> "python --version"

# Clean up when you're done
prime sandbox delete <sandbox-id>
```

Track usage limits and billing inside the [Prime Billing dashboard](https://app.primeintellect.ai/dashboard/billing).

## Pricing

Sandboxes are billed while running:

* **CPU**: \$0.05 per core per hour
* **Memory**: \$0.01 per GB per hour
* **Disk**: \$0.001 per GB per hour

Example: 1 CPU core, 2 GB RAM, 10 GB disk → \$0.08/hour.

## Limits

### Per-sandbox — VM sandboxes

| Resource     | Min    | Max               | Default  |
| ------------ | ------ | ----------------- | -------- |
| CPU cores    | 1      | 16                | 1        |
| Memory       | 0.1 GB | 64 GB             | 1 GB     |
| Disk         | 0.1 GB | 128 GB            | 32 GB    |
| GPUs         | 0      | 8                 | 0        |
| Timeout      | 1 min  | Unlimited         | 60 min   |
| Idle timeout | 1 min  | 1,440 min (24 hr) | Disabled |

CPU is allocated in whole vCPUs; fractional values round up to 1. Any negative timeout value removes the lifetime deadline. Idle timeouts must be between 1 and 1,440 minutes and cannot exceed a finite lifetime.

### Per-sandbox — container sandboxes

| Resource     | Min    | Max               | Default  |
| ------------ | ------ | ----------------- | -------- |
| CPU cores    | 0.1    | 16                | 1        |
| Memory       | 0.1 GB | 64 GB             | 1 GB     |
| Disk         | 0.1 GB | 1,000 GB          | 10 GB    |
| Timeout      | 1 min  | 1,440 min (24 hr) | 60 min   |
| Idle timeout | 1 min  | 1,440 min (24 hr) | Disabled |

### Per-account

| Resource            | Default limit |
| ------------------- | ------------- |
| Active sandboxes    | 512           |
| Total CPU cores     | 512           |
| Total memory        | 4,096 GB      |
| Total storage       | 5,120 GB      |
| HTTP port exposures | 128           |
| TCP port exposures  | 32            |

Account limits apply across all running sandboxes. If you need higher limits, contact support.

## Images

Sandboxes run standard Docker images. When you pass an image reference to `prime sandbox create`, it resolves in this order:

1. **Fully-qualified references** go to the registry you name — `docker.io/pytorch/pytorch:latest`, `ghcr.io/org/image:tag`, `quay.io/org/image:tag`.
2. **Prime Images** — references that start with `prime/`, like `prime/<username>/<image>:<tag>`, `prime/<team-slug>/<image>:<tag>`, or the id forms (`prime/<userId>/<image>:<tag>`, `prime/team-<teamId>/<image>:<tag>`), resolve to a [Prime Image](./images) you can access: your own, your team's, or one that's been published.
3. **Docker Hub** — any other reference with no registry host and no `prime/` prefix resolves as a Docker Hub image, so official images like `ubuntu:22.04` or `pytorch/pytorch:latest` work as usual.

### VM sandbox images

VM sandboxes can boot Prime Images and Docker Hub images. Support for any Docker-compatible registry (including private registries) is coming soon to VM sandboxes. Use `--container` for now.

The first time a given image is launched as a VM sandbox, Prime converts it into a VM image. The sandbox stays `PENDING` while that runs, which can take a few minutes; later sandboxes from the same image start normally. To skip the wait, pre-build with [`prime images build-vm`](./images#pre-build-a-vm-image).

### Container sandbox images

Container sandboxes (`--container`) pull from any Docker-compatible registry, including private ones. For private images, add registry credentials via the [dashboard](https://app.primeintellect.ai/dashboard/instances?tab=templates), then switch to `Settings` in the toggle. Then pass `--container --registry-credentials-id <id>` when creating a sandbox. Use `prime registry list` to view saved credentials and `prime registry check-image` to verify an image is accessible.

## GPU Support

GPU-enabled sandboxes are coming soon. They run only on VM sandboxes and need an explicit grant from Prime, so `--gpu-count` above 0 returns an error until your account has access. We'll announce as soon as GPU tiers open up.

## Next Steps

* Use the [Sandbox CLI Guide](./cli) for day-to-day commands.
* Build automation with the [Sandbox SDK Guide](./sdk).
* Explore runnable demos in [prime/examples](https://github.com/PrimeIntellect-ai/prime/tree/main/examples).