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.
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)
SimpleBoxexposescpus/memory_mib(Python) /cpus/memoryMib(Node) directly. Python’sdisk_size_gbis not an explicitSimpleBoxparameter but is forwarded through**kwargsto the underlyingBoxOptions(which explicitly supportsdisk_size_gb). Node’sSimpleBoxOptionsincludesdiskSizeGbexplicitly.
Defaults
Whencpus / 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 setcpus/memory_mib/disk_size_gbexplicitly 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:TheDEFAULT_CPUS/DEFAULT_MEMORY_MIBconstants 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. Treatsrc/boxlite/src/runtime/constants.rsas 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 whencpus / 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 writememory_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. Forfractional 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 aRuntimeError (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-zeroexit_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 standardRuntimeError (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.
