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

Reserve every vCPU

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

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

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", "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:

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

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

Facts on this page were checked on 25 September 2026.