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

Pass `vcpu`, `memoryMiB` and `diskMiB` when you create the sandbox. The defaults
are 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 billed on what you reserve, at
$0.0075 per GiB-hour. CPU is billed at $0.025 per vCPU-hour of CPU
actually used, as of 26 October 2026 ([pricing](/docs/pricing)). So the rule
is: request the cores that a burst needs, and only the memory that the job
needs.

## Set the size

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

await using sbx = await Sandbox.create({
  vcpu: 4,
  memoryMiB: 8192,
  diskMiB: 16384,
});
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) as sbx:
    print(sbx.info["vcpu"], sbx.info["memoryMiB"], sbx.info["diskMiB"])
```

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

All three are in MiB except `vcpu`. To use the default for any of them, leave
it out.

## Limits

| Setting     | Default | Without credit                       | Notes                                                                                                         |
| ----------- | ------- | ------------------------------------ | ------------------------------------------------------------------------------------------------------------- |
| `vcpu`      | 2       | At most 2                            | Shared cores. The sandbox bursts up to this many. Paid: up to 16                                              |
| `memoryMiB` | 4096    | At most 4096                         | Reserved for the sandbox while it runs. Paid: up to 65,536 (64 GiB)                                           |
| `diskMiB`   | 4096    | At most 10,240                       | At least 3072. That is the size of the image file.                                                            |
| Per account | —       | four at the same time | Paid: 100 sandboxes, 200 vCPUs, 400 GiB memory, 1 TiB disk |

You request a size, and 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, and the sandbox pays 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 |
| 16 vCPU, 64 GiB, paid | $0.48125 | $0.88 |

Doubling `vcpu` alone does not change the waiting figure. 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. It 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 sandboxes metrics "${id}" --range 1h
```

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

## Disk

`diskMiB` includes the system image and whatever you install. In a measurement
on 24 September 2026, the default 4 GiB disk had about 2.5 GiB free. So request
more disk before you install a large toolchain or dataset. Disk speed does not
depend on size. Every sandbox gets at least about 40 MB/s, and up to about
1 GB/s while its neighbors are quiet. For data that should outlive the
sandbox, attach a [volume](/docs/storage).

## Mistakes and how Runtime handles them

- **A big size without credit.** The create fails with `no_credit_size_limit`.
  The error names each field over the limit, and nothing starts. Omit the size
  fields. Once the account holds prepaid credit, larger sizes run without any
  change on your side.
- **Changing size with `update`.** `update` changes the name, labels, idle pause, automatic wake and persistence, not the size. `runtime sandboxes resize <id> --vcpu 4 --memory 8192 --restart` changes the size by a restart on the same server: the whole disk stays and its programs stop, so snapshot it first to keep memory. `--disk` alone grows a running sandbox's disk live.
- **Past the account limit.** A create returns `quota_exceeded` and costs
  nothing. The SDKs wait for room for up to two minutes. Contact 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 26 October 2026.