# How to reserve CPU for a sandbox (dedicated vCPUs)

Create the sandbox with `cpu: "reserved"` to guarantee every vCPU. Or raise
`cpuFloorMillis` to guarantee part of them while CPU stays shared.

**On Runtime, you choose how much CPU is guaranteed for each sandbox, from
a twentieth of a vCPU up to every core.** The default is shared CPU with a
50-millicore floor. With that default, a waiting 2 vCPU, 4 GiB sandbox costs
$0.03125 an hour. When a benchmark or a latency-bound job needs cores that
are always available, reserving them costs $0.08 an hour at that size.
That is the same as a shared sandbox with both CPUs busy (rates as of 26 October 2026, [pricing](/docs/pricing)).

## Reserve every vCPU

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

await using sbx = await Sandbox.create({ vcpu: 2, cpu: "reserved" });
console.log(sbx.info.cpu); // "reserved"
```

```python check
from withruntime import Sandbox

with Sandbox.create(vcpu=2, cpu="reserved") as sbx:
    print(sbx.info["cpu"], sbx.info["cpuFloorMillis"])
```

Over HTTP, use the same field in the create request body:

```bash no-run
curl -sS https://api.withruntime.com/v1/sandboxes \
  -H "Authorization: Bearer ${RUNTIME_API_KEY}" \
  -H "Content-Type: application/json" \
  -H "Prefer: wait=60" \
  -d '{"vcpu": 4, "cpu": "reserved"}'
```

## Or guarantee part of the CPU

`cpuFloorMillis` is the CPU guaranteed while the sandbox is shared, in
thousandths of a vCPU. The sandbox can still burst up to `vcpu` cores when the
host has spare capacity:

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

// Half a core always there, two cores when it bursts.
await using sbx = await Sandbox.create({ vcpu: 2, cpuFloorMillis: 500 });
console.log(sbx.info.cpu, sbx.info.cpuFloorMillis); // "shared" 500
```

```python check
from withruntime import Sandbox

with Sandbox.create(vcpu=2, cpu_floor_millis=500) as sbx:
    print(sbx.info["cpu"], sbx.info["cpuFloorMillis"])
```

## The three modes

| Mode                 | Setting                                        | Guaranteed    | Without credit |
| -------------------- | ---------------------------------------------- | ------------- | -------------- |
| Shared (default)     | `cpu: "shared"`                                | 50 millicores | Yes            |
| Shared, raised floor | `cpuFloorMillis` above 50, up to `vcpu × 1000` | The floor     | Up to 250      |
| Reserved             | `cpu: "reserved"`                              | Every vCPU    | No             |

## What it costs

You pay for the larger of two values: the CPU the sandbox measured, and its
guaranteed floor. CPU is billed at $0.025 per vCPU-hour. Memory is billed
at $0.0075 per GiB-hour. Reserved CPU guarantees every vCPU, so it bills
as if every vCPU were busy all the time.

| 2 vCPU, 4 GiB sandbox       |                            Idle, per hour | Both CPUs busy, per hour |
| --------------------------- | ----------------------------------------: | -----------------------: |
| Shared, 50-millicore floor  |                             $0.03125 |            $0.08 |
| Shared, 250-millicore floor | $0.03625 |            $0.08 |
| Shared, 500-millicore floor |  $0.0425 |            $0.08 |
| Reserved                    |                             $0.08 |            $0.08 |

A fully busy sandbox costs the same in every mode. So reserving CPU adds cost
only for the time the job would have left the cores idle. Each sandbox's quote
is fixed when the sandbox is created.

## When to reserve

- **Benchmarks and timing tests.** A shared CPU ceiling is not a reserved
  physical core. Reserve CPU to compare like with like against a provider that
  sells whole cores.
- **Steady CPU-bound work.** A compile farm or a simulation that keeps every
  core busy costs the same either way. Reserved CPU also removes contention.
- **Latency you promise someone.** A request that must respond within a fixed
  time gets cores that are always available.
- **Not for agents that wait.** An agent loop that spends most of its time
  waiting for model replies is what shared CPU is priced for.

## Mistakes and how Runtime handles them

- **Reserved CPU without credit.** A sandbox without credit must use shared CPU
  with a floor of at most 250 millicores. Anything else fails with
  `no_credit_size_limit` before the sandbox starts. Once the account holds
  prepaid credit, its sandboxes can reserve CPU.
- **A floor above `vcpu × 1000`.** Runtime refuses the create request with
  `invalid_request`. The error names `cpuFloorMillis` and its maximum. Raise
  `vcpu`, or use `cpu: "reserved"`.
- **Forking a reserved sandbox without credit.** Copies keep the source's `cpu`
  and `cpuFloorMillis`, and are billed as a create with them. So a sandbox with reserved CPU, or a floor above 250, forks only once the account holds credit.
- **Leaving a reserved sandbox parked.** Pause it. A paused sandbox holds no CPU
  or memory. It pays only for its saved state.

## Related

- [How to choose CPU, memory and disk](/how-to/size-cpu-and-memory)
- [How to pause and resume a sandbox](/how-to/pause-and-resume-a-sandbox)
- [Runtime vs Fly.io](/docs/fly-alternative), where whole cores matter
- [Choosing an agent sandbox](/docs/choosing-agent-sandbox)

Facts on this page were checked on 26 October 2026.