v5

latestOpenAPI 3.1.0raw.githubusercontent.com2026-08-016917.1 KB

Create Sandbox

Create, boot, and register a new sandbox.

Builds a :class:~smolvm.SmolVM from the request's auto-config fields, starts it, stores it in the registry under its id, and returns the client-safe view.

post/sandboxes

Request body

imagestring nullable

Image reference to boot (S3 ref, file:// URI, or path). Omit to use the default built-in image.

os'alpine' | 'ubuntu' | 'windows' | 'macos' nullable

Guest OS for auto-configured images: 'alpine', 'ubuntu', 'windows', or 'macos'.

memoryinteger nullable

Guest memory in MiB.

disk_sizeinteger nullable

Guest disk size in MiB.

backend'firecracker' | 'qemu' | 'libkrun' | 'vz' nullable

Runtime backend override: 'firecracker', 'qemu', 'libkrun', or 'vz'.

Response

Successful Response

idstring required

Stable sandbox identifier.

status'created' | 'running' | 'paused' | 'stopped' | 'error' required

VM lifecycle states.