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.

Request bodyapplication/json

CreateSandboxRequest

boot_argsstring

disk_bytesintegerint64

imageImageRef

ocistring

pathstring

memory_mibinteger

networkNetworkRequest

allowlistarray

items

string

enabledboolean

profilestring

publisharray

items

PortMapping

guest_portinteger

host_ipstring

host_portinteger

protocolstring

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 '{}'

JavaScript

const response = await fetch("/sandboxes", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
  },
  body: "{}",
});
const data = await response.json();

Python

import requests

response = requests.post(
    "/sandboxes",
    headers={
    "Content-Type": "application/json",
},
    data="{}",
)
data = response.json()

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"
}