Skip to main content
Forking a sandbox takes a point-in-time snapshot of the parent VM and spawns n independent children, each starting from that same state. Children share memory pages with their siblings via copy-on-write — a child only consumes additional memory for the pages it actually modifies. Use fork to explore multiple plans in parallel without duplicating work done in the parent.

​
Request

POST /v1/sandboxes/:id/fork
​
id
string
required
The parent sandbox id.
​
n
int
default:"1"
Number of child sandboxes to spawn. Must be between 1 and 32 inclusive. Requests with n > 32 return 400.

​
Response

​
children
string[]
Array of n new sandbox ids. Each id is immediately usable — children are booted in parallel and are ready when the response arrives.

​
Examples

curl -X POST https://api.podflare.dev/v1/sandboxes/$SID/fork \
  -H "Authorization: Bearer $PODFLARE_API_KEY" \
  -H "content-type: application/json" \
  -d '{"n": 5}'
200 response 
{
  "children": [
    "sbx_a1ac8f28d473413585d8f4f425bcc2b1",
    "sbx_03cfbf63bb394575aefa4e6c62874998",
    "sbx_532288c716c8424cb8bb549e6ce2748b",
    "sbx_bca65926af5f4afcaa6b8f20a66845b2",
    "sbx_267b68883b41469fbda8973296767542"
  ]
}

​
What children inherit

Each child starts from the parent’s state at the moment of the snapshot:
  • Python REPL state — all variables, imports, and open file handles
  • Filesystem — everything written to the parent’s rootfs up to the fork point
  • Full VM memory — pages are shared copy-on-write with siblings; a child only pays for pages it mutates
exec calls made on the parent after fork returns are not visible to children. Each child only sees the pre-fork state.

​
Parent impact

The parent is paused for approximately 80 ms while the snapshot is taken. It resumes automatically once fork returns.

​
Timing reference

nTotal fork latency
192 ms
2102 ms
5101 ms
Spawn cost is near-flat in n because children boot in parallel (~10 ms each) and the snapshot and merge step happens only once.

​
Requirements

The parent sandbox must have been created from the Podflare API (a standard POST /v1/sandboxes call or a previous fork child). Sandboxes started in offline local dev mode that bypass the API do not support fork and return 500.

​
Error responses

StatusBodyCause
400{"error": "n must be between 1 and 32"}n is out of range
401{"error": "invalid api key"}Missing or invalid bearer token
404{"error": "sandbox not found"}Parent id does not exist
500{"error": "..."}Parent has no Firecracker API socket or snapshot failed