# How to choose a sandbox's CPU, memory and disk size

Pass `vcpu`, `memoryMiB` and `diskMiB` when you create the sandbox; the default is 2 vCPU, 4 GiB of memory and a 4 GiB disk.

**On Runtime extra vCPUs cost nothing while they sit idle, because CPU is
billed as measured use.** Memory is what you reserve, at $0.0075 per GiB-hour,
and CPU is $0.025 per vCPU-hour of CPU actually used, as of 25 September 2026
([pricing](/docs/pricing)). So the rule is: ask for the cores a burst needs,
and only the memory the job needs.

## Set the size

```ts check
import { Sandbox } from "withruntime";

await using sbx = await Sandbox.create({
  vcpu: 4,
  memoryMiB: 8192,
  diskMiB: 16384,
  funding: "paid", // a trial sandbox is at most 2 vCPU and 4 GiB
});
console.log(sbx.info.vcpu, sbx.info.memoryMiB, sbx.info.diskMiB);
```

```python check
from withruntime import Sandbox

with Sandbox.create(vcpu=4, memory_mib=8192, disk_mib=16384, funding="paid") as sbx:
    print(sbx.info["vcpu"], sbx.info["memoryMiB"], sbx.info["diskMiB"])
```

```bash no-run
runtime sandbox create --paid --vcpu 4 --memory 8192 --disk 16384
```

All three are in MiB except `vcpu`. Leave any of them out for its default.

## Limits

| Setting     | Default | Free trial     | Notes                                                        |
| ----------- | ------- | -------------- | ------------------------------------------------------------ |
| `vcpu`      | 2       | At most 2      | Shared cores; the sandbox bursts up to this many             |
| `memoryMiB` | 4096    | At most 4096   | Reserved for the sandbox while it runs                       |
| `diskMiB`   | 4096    | At most 10,240 | At least 3072, the size of the image file                    |
| Per account | —       | Eight at once  | Paid: 100 sandboxes, 200 vCPUs, 400 GiB memory, 400 GiB disk |

Sizes are limits you ask for. The server checks each combination against
your account's limits and the host's measured capacity.

## What each size costs

Waiting means the code is idle, paying the 50-millicore CPU floor; busy means
every vCPU is working. Memory is charged the same either way.

| Size           | Waiting, per hour | Every vCPU busy, per hour |
| -------------- | ----------------: | ------------------------: |
| 1 vCPU, 2 GiB  |          $0.01625 |                     $0.04 |
| 2 vCPU, 4 GiB  |          $0.03125 |                     $0.08 |
| 4 vCPU, 8 GiB  |          $0.06125 |                     $0.16 |
| 8 vCPU, 16 GiB |          $0.12125 |                     $0.32 |

Doubling `vcpu` alone changes the waiting figure by nothing: the floor stays
at 50 millicores and memory stays the same. A build that runs `make -j4` in
bursts gets four cores for the seconds it uses them and pays for those
seconds only.

## Measure before you pick

Run the job once at a generous size, then read what it used:

```ts check
import { Sandbox } from "withruntime";

const sbx = await Sandbox.create();
const m = await sbx.metrics({ range: "1h" });
for (const point of m.points) console.log(point.at, point.cpuPercent, point.memoryBytes);
await sbx.stop();
```

```bash no-run
runtime sandbox metrics "${id}" --range 1h
```

`cpuPercent` is CPU in use as a share of all the sandbox's vCPUs, and
`memoryPeakBytes` the most memory it held in each bucket. The host reads every
running sandbox once a minute, and the reading is the same one the bill is
made from. Set `memoryMiB` a margin above the peak; set `vcpu` to the cores
the busiest step can keep busy.

## Disk

`diskMiB` includes the system image and whatever you install. The default
4 GiB disk had about 2.5 GiB free in a measurement on 24 September 2026, so
ask for more before installing a large toolchain or dataset. Each sandbox's
disk bursts to about 250 MB/s for up to 30 seconds, then runs at about 40 MB/s
and 2,000 operations a second, whatever its size. For data that should outlive the sandbox, attach a
[volume](/docs/storage).

## Mistakes and how Runtime handles them

- **A big size on the trial.** The create fails with `invalid_trial`, naming
  each field over the limit, and nothing starts. Pass `funding: "paid"` or
  omit the size fields.
- **Changing size on a running sandbox.** `update` changes the name, labels,
  idle pause, automatic wake and persistence, not the size. Create a new
  sandbox at the new size.
- **Past the account limit.** A create returns `quota_exceeded` and costs
  nothing; the SDKs wait for room for up to two minutes. Write to support to
  raise the limit.
- **A disk full of packages.** Build a [custom image](/docs/images) once
  instead of installing on every start.
- **Expecting a guaranteed core.** Shared vCPUs burst but are not reserved.
  For guaranteed CPU, see [how to reserve CPU](/how-to/reserve-cpu).

## Related

- [How to reserve CPU](/how-to/reserve-cpu)
- [How to compare your costs](/how-to/compare-your-costs)
- [The sandbox environment](/docs/sandbox-environment#disk-cpu-and-memory)
- [Sandbox cost calculator](/calculators/sandbox-cost-calculator)

Facts on this page were checked on 25 September 2026.