Skip to main content
Creating a sandbox allocates a Firecracker microVM from the warm pool and returns a ready-to-use sandbox id. Use that id in all subsequent exec, fork, merge_into, and destroy calls. Sandboxes from the pool boot in 7–11 ms; if the pool is empty the sandbox cold-boots, which takes longer.

​
Request

POST /v1/sandboxes
​
template
string
Template name for pool selection. Defaults to the primary pool when omitted. Named pool flavors such as python-datasci and node-web are planned — see the roadmap.

​
Response

​
id
string
The sandbox id. Pass this to exec, fork, merge_into, or destroy.
​
state
string
Always ready on a successful response — the VM is booted and the in-guest agent is accepting connections.

​
Examples

curl -X POST https://api.podflare.dev/v1/sandboxes \
  -H "Authorization: Bearer $PODFLARE_API_KEY" \
  -H "content-type: application/json" \
  -d '{}'
200 response 
{
  "id": "sbx_1cc2937f86644dc3a3ad3ffb9010c70d",
  "state": "ready"
}

​
Error responses

StatusBodyCause
401{"error": "invalid api key"}Missing or invalid bearer token
500{"error": "..."}Pool exhausted and cold boot failed