Skip to content

Create a sandbox

POST/sandboxes

Boots a Firecracker microVM. All fields are optional; an empty body uses the daemon defaults. `image` boots from a converted OCI image (pulled on demand — see the images endpoints); a daemon without an image store answers 501.

All fields are optional: an empty body {} boots a sandbox with daemon defaults.

{
  "vcpus": 1,
  "memory_mib": 512,
  "boot_args": "",
  "timeout_s": 0,
  "network": {
    "enabled": true,
    "allowlist": ["pypi.org", "*.npmjs.org"]
  }
}
Field Type Notes
vcpus int vCPU count. Defaulted and range-capped by the daemon.
memory_mib int Guest memory in MiB. Defaulted and range-capped.
boot_args string Extra kernel cmdline appended to the daemon's default.
timeout_s int Max sandbox lifetime in seconds. 0 = no timeout (lives until DELETE or shutdown).
profile string Pre-baked rootfs to boot from, e.g. "python-3.12". Empty uses the daemon's default --rootfs. An unknown profile is a 400. See Profiles.
network object Omit or null for no network (default-deny). See Networking.
image object Boot from an OCI image instead of a profile: {"oci": "nginx:alpine"} (a registry ref or a converted digest). Mutually exclusive with profile.
pull string Image pull policy when image.oci is set: "missing" (default), "always", "never".
publish array Host-to-guest port publishes, e.g. [{"host_port":8080,"guest_port":80}] (optional host_ip, default protocol "tcp"). Requires a NIC; when network is absent one is created ingress-published, egress-denied.
disk_bytes int Grow the writable rootfs clone to at least this size before boot. 0 keeps the image or profile headroom; a smaller value is a no-op (never shrinks). The shared template is never modified.

The 201 response echoes the applied config with the assigned addresses; network is omitted when the sandbox has no NIC, and profile is echoed when the sandbox booted from a named profile.

Request bodyapplication/json
CreateSandboxRequest
boot_argsstring
disk_bytesintegerint64
imageImageRef
ocistring
pathstring
memory_mibinteger
networkNetworkRequest
allowlistarray
items
string
allowlist_cidrarray
items
string
enabledboolean
full_egressboolean
profilestring
publisharray
items
PortMapping
guest_portinteger
host_ipstring
host_portinteger
protocolstring
publish_allboolean
pullstring
serviceWireServiceSpec
cmdarray | null
items
string
cwdstring
envobject
additional properties
string
env_exactboolean
log_buffer_bytesinteger
restartWireRestartPolicy
max_retriesinteger
policystring
stop_grace_sinteger
stop_signalstring
userstring
timeout_sinteger
vcpusinteger
Responses
201 CreatedCreated
SandboxResponse
created_atstringdate-time
idstring
memory_mibinteger
networkNetworkResponse
allowlistarray
items
string
enabledboolean
gatewaystring
guest_ipstring
profilestring
publishedarray
items
PortMapping
guest_portinteger
host_ipstring
host_portinteger
protocolstring
source_snapshot_idstring
vcpusinteger
workdirstring
400 Bad requestBad Request
ErrorResponse
errorstring
403 ForbiddenForbidden
ErrorResponse
errorstring
500 Server errorInternal Server Error
ErrorResponse
errorstring
501 Not Implemented
ErrorResponse
errorstring
502 Bad gatewayBad Gateway
ErrorResponse
errorstring
Authentication
bearerAuthHTTP bearer. Daemon API key. Omit on a keyless loopback daemon.
Request
▍POST/sandboxes
cURL
curl '/sandboxes' \
  -X POST \
  -H 'Content-Type: application/json' \
  -d '{}'
Response
201 Created
{
  "created_at": "2026-01-02T15:04:05Z",
  "id": "string",
  "memory_mib": 0,
  "network": {
    "allowlist": [
      "string"
    ],
    "enabled": false,
    "gateway": "string",
    "guest_ip": "string"
  },
  "profile": "string",
  "published": [
    {
      "guest_port": 0,
      "host_ip": "string",
      "host_port": 0,
      "protocol": "string"
    }
  ],
  "source_snapshot_id": "string",
  "vcpus": 0,
  "workdir": "string"
}
Was this page helpful?