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

# Sandbox sizes

> Small, Medium, Large and XL: the vCPU, memory and disk a sandbox gets, and which templates run on each.

A sandbox's size decides how much CPU, memory and disk it gets. The template decides what is inside it. You pick both when you create a sandbox: any template, at any size that template can run on.

## The four sizes

| Size | vCPU | Memory | Disk |
| - | - | - | - |
| **Small** | 1 | 2 GiB | 10 GB |
| **Medium** | 2 | 4 GiB | 20 GB |
| **Large** | 4 | 8 GiB | 40 GB |
| **XL** | 8 | 16 GiB | 80 GB |

Each plan includes the sizes up to its largest: Free and Starter up to Medium (Free runs at most two Medium sandboxes at once), Pro up to Large, Scale up to XL. See [limits](/docs/concepts/limits.md); prices are on the [pricing page](/docs/pricing.md).

## Choosing a size

```bash cli.sh
anona-compute create -t desktop --size large
anona-compute run -t python --size small -- 'python -c "import os; print(os.cpu_count())"'
anona-compute template info desktop   # the sizes a template can run at, and its minimum
```

```python size.py
from anona_compute import Sandbox

sbx = Sandbox.create("desktop", size="large")
print(sbx.get_info())
sbx.kill()
```

```typescript size.ts
import { Sandbox, withSize } from "@anona-labs/compute-sdk";

const sbx = await Sandbox.create("desktop", withSize("large"));
await sbx.kill();
```

```bash api.sh
curl -X POST https://api.compute.anonalabs.com/v2/sandboxes \
  -H "X-API-Key: $ANONA_API_KEY" -H "Content-Type: application/json" \
  -d '{"templateID": "desktop", "size": "large", "timeout": 600}'
```

* The API's create body takes `size`: `small`, `medium`, `large` or `xl`. The stock E2B SDK cannot send that field, so it can set the size as metadata instead: `metadata={"anona.size": "large"}`. That key is read as the size and is not stored with the sandbox's metadata. The Anona SDKs above do this for you.
* A sandbox's info (`GET /sandboxes/{id}`, `anona-compute info`) reports the `size` it was created at, with its `cpuCount`, `memoryMB` and `diskSizeMB`.
* **Without a size**, a sandbox runs at its template's own size, exactly as before sizes existed. The console's **New sandbox** dialog preselects the template's default size from the table below.
* **The first sandbox at a new size takes longer.** The first time anyone creates a template at a size it was not built at, that size is prepared, which takes about half a minute. A create that waits too long for it gets `503` `sandbox_size_preparing` with `Retry-After`, and the CLI and the console retry it for you. Every sandbox after that starts as fast as any other.

## Disk is your working space

The disk figure is space for your work: files you create, packages you install, build output, `/home/user` and `/tmp`. The template's own files do not use any of it.

A sandbox's root filesystem is two layers. The template image is a read-only layer underneath, shared by every sandbox started from that template. Your disk is a writable layer on top of it. So a 2 GB template on Medium still gives you the full 20 GB to write into, and `df -h /` inside the sandbox shows the disk size with almost nothing used, even though every tool in the template is there.

* Changing a file that came with the template copies it into your layer, so that change does count.
* When the disk is full, writes fail with `No space left on device`. The template's files are never affected.
* A small part of the disk goes to filesystem overhead, a few percent.

## Which templates run on which size

Each template has a **minimum size**, and a sandbox can use that size or any larger one. For a template you build, the minimum is the smallest size that meets its vCPU, memory and disk (see [Your own templates](#your-own-templates)). For a built-in template, the minimum is set per template, as in the table below. It does not come from the template's own size, which is what a sandbox gets without a size: `base` runs at 2 vCPU when no size is given, yet it can be created at Small, with 1 vCPU.

| Template | Small | Medium | Large | XL | Console default | Without a size |
| - | - | - | - | - | - | - |
| `base` | ✓ | ✓ | ✓ | ✓ | Small | 2 vCPU, 1 GiB, 1 GiB disk |
| `python` | ✓ | ✓ | ✓ | ✓ | Small | 2 vCPU, 2 GiB, 2 GiB disk |
| `node` | ✓ | ✓ | ✓ | ✓ | Small | 2 vCPU, 2 GiB, 2 GiB disk |
| `code-interpreter` | ✓ | ✓ | ✓ | ✓ | Small | 2 vCPU, 2 GiB, 2 GiB disk |
| `desktop` | | ✓ | ✓ | ✓ | Medium | 2 vCPU, 4 GiB, 4 GiB disk |
| `agent-desktop` | | ✓ | ✓ | ✓ | Large | 2 vCPU, 6 GiB, 8 GiB disk |

`anona-compute template info <template>` prints the same: the template's own vCPU, memory and disk, its minimum size and the sizes you can create it at.

Why the desktops start at Medium: Small has one vCPU, and the live view (which encodes the screen) and the browser have to share it, so the desktop stutters. Memory is not the limit: `desktop` with Chrome and three tabs open uses about 750 MiB. `agent-desktop` adds the coding-agent toolchain on top, so it defaults to Large for agents that build and test while they drive the browser; Medium works for light use.

Use Medium or larger for `python`, `node` and `code-interpreter` when the work is heavier than scripts and small builds: data analysis on real datasets, large monorepos, or test suites that run in parallel.

## Your own templates

When you build a template, its `--cpu`, `--memory` and `--disk` are its **minimum requirements**. Sandboxes from it can run at any size that meets all three, or, without a size, at exactly what it was built with.

```bash template_minimums.sh
# needs at least 2 vCPU, 4 GiB of memory and 15 GB of writable disk
anona-compute template build --name my-env --cpu 2 --memory 4096 --disk 15360
```

That template runs at Medium, Large and XL, and the console preselects Medium, the smallest size that meets all three minimums. A template built without those flags gets 2 vCPU, 2 GiB and 1 GiB of disk, so its minimum is Medium (for the 2 vCPU). Set `--disk` to the writable space the template needs to run, such as caches, downloaded models or build output. The image itself is separate: it is limited to 10 GiB and counts toward your plan's template storage (see [Templates](/docs/concepts/templates.md#build-your-own)).

The rules:

* **Eligible sizes** are the sizes that meet every minimum *and* that your plan includes.
* A size below the template's minimum is refused with `400` `sandbox_size_not_available`, naming the size the template needs. A size above your plan's largest (Free and Starter: Medium; Pro: Large; Scale: XL) is refused with `403` `plan_limit_exceeded`, and so is a sandbox created without a size from a template registered above it. A sandbox is never quietly given less than its template needs. See [limits](/docs/concepts/limits.md).
* A template whose minimums exceed XL (more than 8 vCPU, 16 GiB of memory or 80 GB of disk) is refused when it is built, not when a sandbox is created.
* Templates you have already built keep working: their current vCPU, memory and disk become their minimums.

## How a size is chosen

| You pass | The sandbox gets |
| - | - |
| A template only, on Free | The smallest size the template allows: Small for `base`, `python`, `node`, `code-interpreter` and templates built at Small or less; Medium for `desktop` and `agent-desktop` |
| A template only, on a paid plan | The template's own size, as before sizes existed |
| A template and a size the template supports | That size |
| A size smaller than the template's minimum | `400`, naming the minimum size |
| A size your plan does not include | `403` `plan_limit_exceeded`, naming your plan's largest size |
| A size not prepared for that template yet | That size, after about half a minute; or `503` `sandbox_size_preparing` with `Retry-After` if the create cannot wait that long |


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