How to reserve CPU for a sandbox (dedicated vCPUs)

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).

Reserve every vCPU

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

Pythonfrom withruntime import Sandboxwith 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:

Terminalcurl -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:

TypeScriptimport { 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

Pythonfrom withruntime import Sandboxwith Sandbox.create(vcpu=2, cpu_floor_millis=500) as sbx:    print(sbx.info["cpu"], sbx.info["cpuFloorMillis"])

The three modes

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.

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 pause and resume a sandbox
• Runtime vs Fly.io, where whole cores matter
• Choosing an agent sandbox

Facts on this page were checked on 26 October 2026.