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

Create it with `cpu: "reserved"` to guarantee every vCPU, or raise `cpuFloorMillis` to guarantee part of them while CPU stays shared.

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

## Reserve every vCPU

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

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

```python check
from withruntime import Sandbox

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

Over HTTP it is the same field on the create 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", "funding": "paid"}'
```

## Or guarantee part of the CPU

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

```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    | Free trial |
| -------------------- | ---------------------------------------------- | ------------- | ---------- |
| 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 the CPU the sandbox measured and its guaranteed
floor, at $0.025 per vCPU-hour, plus memory at $0.0075 per GiB-hour. Reserved
CPU guarantees every vCPU, so it bills as if every vCPU were always busy.

| 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 costs
extra only for the time the job would have left the cores idle. Each
sandbox's quote is fixed when it is made.

## When to reserve

- **Benchmarks and timing tests.** A shared CPU ceiling is not a reserved
  physical core. Reserve 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 pays the same either way, and reserved takes contention off the
  table.
- **Latency you promise someone.** A request that must answer in a fixed time
  gets cores that are always there.
- **Not for agents that wait.** An agent loop that spends most of its time on
  model replies is what shared CPU is priced for.

## Mistakes and how Runtime handles them

- **Reserved CPU on the trial.** A trial sandbox must be shared with a floor
  of at most 250 millicores; anything else fails with `invalid_trial` before
  it starts. Pass `funding: "paid"`.
- **A floor above `vcpu × 1000`.** The create is refused with
  `invalid_request`, naming `cpuFloorMillis` and its maximum. Raise `vcpu`, or
  use `cpu: "reserved"`.
- **Forking a reserved sandbox onto the trial.** 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 onto `"paid"`.
- **Leaving a reserved sandbox parked.** Pause it: a paused sandbox holds no
  CPU or memory and 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 25 September 2026.