Skip to main content
A test suite needs CPU, a large build needs disk, a long-lived service needs stable memory. Set all three explicitly in production rather than relying on defaults. CPU and memory can be set independently; there is no fixed ratio. For hosted boxes, use the complete Cloud sizing examples.

Fractional CPU

cpus accepts numbers from 0.125 to 16, in 0.001-core increments, with the bundled guest kernel. Examples include 0.125, 0.5, 1, and 1.5. A fractional allocation limits aggregate CPU time on a Linux execution host. The guest sees the allocation rounded up to a whole number of virtual CPUs: 0.5 exposes one, and 1.5 exposes two. nproc reports that visible count, not the CPU-time limit. For a local box, fractional CPU requires Linux, the jailer, and an available cgroup v2 CPU controller. Local macOS execution accepts whole CPU allocations only. A client on macOS can still request fractional CPU from a Linux REST execution host; see Cloud vs open source.
On a self-hosted Linux machine, CPU quota application is best-effort. If the cgroup CPU controller cannot be configured, startup can succeed without the requested bandwidth limit and logs an error. Verify host cgroup setup before relying on quota enforcement.
Configure a small local Linux box with either SDK:
Increase memory independently, for example to 4096 MiB while keeping cpus=0.5. Physical host capacity and any REST service quotas still apply.

Quick Example

The following uses Python to create a sandbox with 2 cores / 1024 MiB of memory / 8 GB of disk and prints the configuration that actually takes effect.

Parameters and Returns

Resource parameters (core)

SimpleBox exposes cpus / memory_mib (Python) / cpus / memoryMib (Node) directly. Python’s disk_size_gb is not an explicit SimpleBox parameter but is forwarded through **kwargs to the underlying BoxOptions (which explicitly supports disk_size_gb). Node’s SimpleBoxOptions includes diskSizeGb explicitly.

Defaults

When cpus / memory_mib are not specified, the VM is provisioned with 1 vCPU / 1024 MiB. Both values come from one place — vm_defaults::DEFAULT_CPUS / DEFAULT_MEMORY_MIB in src/boxlite/src/runtime/constants.rs — which the VM engine and the stored box config both read, so box.info() and the real allocation agree. Read configured CPU from box information. Inside the guest, nproc reports visible vCPUs, while MemTotal from /proc/meminfo reports memory available after kernel reservations. When disk_size_gb is not specified, the disk is sparse and grows on demand (default cap 10 GB).
Practical advice: for predictability and cost control, always set cpus / memory_mib / disk_size_gb explicitly in production; do not rely on implicit defaults.

Specialized Box resource defaults (reference)

Some specialized sandboxes have their own higher resource defaults that override the general defaults above:
The DEFAULT_CPUS / DEFAULT_MEMORY_MIB constants exported by the Python and Node SDKs are reference values only — they are not applied on the box-creation path, and the Node one does not match the runtime. Treat src/boxlite/src/runtime/constants.rs as the single source of truth.

Return value

SimpleBox.exec(...) returns an ExecResult:

Troubleshooting

How much is allocated when cpus/memory are not passed (1 vCPU / 1024 MiB)

Symptom: you need to confirm how much a sandbox actually gets when cpus / memory_mib / memoryMib are not passed. Explanation: when not passed, the VM is provisioned with 1 vCPU / 1024 MiB. Read configured CPU from box information; nproc shows guest-visible vCPUs, not a fractional CPU-time limit. See the “Defaults” subsection above. Fix: for deterministic resources, specify the parameters explicitly; production code should not rely on implicit defaults:

Unit confusion (MB vs MiB, bytes vs MiB)

Symptom: you want to allocate 2 GB of memory but write memory_mib=2000000000 (filling in bytes), so the requested amount far exceeds the host and startup fails. Cause: memory_mib is in MiB, and disk_size_gb is in GB. Fix: write 2 GB of memory as memory_mib=2048; write 10 GB of disk as disk_size_gb=10.

CPU allocation is rejected

Use the range and precision under Fractional CPU. Out-of-range values are rejected instead of silently changing the requested allocation. For fractional cpus requires a Linux host, use whole CPU allocations locally on macOS or connect to a Linux execution host. For a jailer or cgroup error, check the Linux host configuration.

Startup fails in a no-virtualization environment

Symptom: creating a sandbox in a Linux container/CI without KVM raises a RuntimeError (Python) or a bare Error (Node). Cause: BoxLite is a microVM and requires hardware virtualization. Linux requires /dev/kvm, macOS (Apple Silicon) uses Hypervisor.framework, and Windows requires WSL2 + KVM. Fix: confirm the environment supports virtualization; in CI, enable nested virtualization or use a KVM-capable runner. Catch with try/except (Python) / try/catch (Node); the process does not crash, only that sandbox fails to start.

A process is killed due to insufficient resources

Symptom: a build/test running inside the sandbox suddenly exits, with a non-zero exit_code or a non-empty error_message. Cause: memory_mib is set too small, triggering OOM. Fix: raise memory_mib (e.g. 2048-4096 for building a large project), and check ExecResult.exit_code / error_message rather than assuming the command succeeded — a non-zero exec exit does not raise.

An image pull failure mistaken for a resource error

Symptom: creating a sandbox for the first time errors with a message related to networking/images. Cause: the first run pulls the image over the network, and network flakiness raises a standard RuntimeError (Python) / a bare Error (Node), not a BoxliteError. Fix: catch the standard exception and retry; pulling the image ahead of time reduces first-create latency.