Skip to main content
POST
/
api
/
v1
/
sandboxes
cURL
curl --request POST \
  --url https://api.example.com/api/v1/sandboxes \
  --header 'Content-Type: application/json' \
  --data '
{
  "image": "node:22",
  "timeoutMs": 600000,
  "env": {
    "NODE_ENV": "production",
    "API_KEY": "secret"
  },
  "volumes": {
    "/workspace": "my_packages",
    "/cache": {
      "name": "build_cache",
      "sizeGb": 5
    }
  }
}
'
{
  "sandbox": {
    "id": "e7847229c547d8",
    "name": "sandbox-node-1",
    "state": "started",
    "region": "iad",
    "image": "node:22",
    "createdAt": "2023-12-01T00:00:00Z",
    "stopAt": "2023-12-01T01:00:00Z",
    "publicAccessUrlTemplate": "{{PORT}}-m_01h9z60rm0ex1rc4x-sandbox-shared-app-fly.apps.simplesandbox.dev"
  }
}

Body

application/json
​
image
string
required

Docker image to run inside the shared Fly app

Example:

"node:22"

​
timeoutMs
integer

Optional timeout in milliseconds for the sandbox. Defaults to 10 minutes (600000ms). Maximum 1 hour (3600000ms) from creation for FREE users.

Required range: x >= 0
Example:

600000

​
env
object

Environment variables to set in the sandbox. These will be available to all commands executed in the sandbox.

Example:
{
  "NODE_ENV": "production",
  "API_KEY": "secret"
}
​
volumes
object

Mount volumes by name. Creates if missing, reuses if exists. Key is mount path, value is volume name or config. Volume names must contain only lowercase alphanumeric characters and underscores (max 30 chars).

Example:
{
  "/workspace": "my_packages",
  "/cache": { "name": "build_cache", "sizeGb": 5 }
}

Response

Sandbox created

​
sandbox
object
required