Skip to main content
POST
/
sandboxes
Create a sandbox
curl --request POST \
  --url https://api.tensorlake.ai/sandboxes \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "image": "<string>",
  "resources": {
    "cpus": 123,
    "memory_mb": 123,
    "disk_mb": 56320,
    "gpus": [
      {
        "count": 2,
        "model": "<string>"
      }
    ]
  },
  "secret_names": [
    "<string>"
  ],
  "timeout_secs": 1,
  "entrypoint": [
    "<string>"
  ],
  "network": {
    "allow_internet_access": true,
    "allow_out": [
      "<string>"
    ],
    "deny_out": [
      "<string>"
    ]
  },
  "snapshot_id": "<string>",
  "allow_unauthenticated_access": true,
  "exposed_ports": [
    32768
  ],
  "template_id": "<string>",
  "name": "<string>"
}
'
{
  "sandbox_id": "<string>",
  "ingress_endpoint": "<string>"
}
Restore a new sandbox from a previously created snapshot.

​
Endpoint

POST /sandboxes
To restore from a snapshot, call the standard create sandbox endpoint and include snapshot_id in the request body.
  • If the snapshot type is filesystem (default), the new sandbox restores the captured filesystem. You can override launch settings (including resources).
  • If the snapshot type is memory, the new sandbox restores filesystem, memory, and running processes exactly as they were. Image, resources (CPUs, memory), entrypoint, and secrets come from the snapshot and cannot be changed at restore time.

​
Example Request

curl -X POST https://api.tensorlake.ai/sandboxes \
  -H "Authorization: Bearer $TENSORLAKE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "snapshot_id": "<snapshot-id>"
  }'
For filesystem snapshots, resources.disk_mb can be used at restore time to grow the root disk (growth-only). For the full request and response schema of POST /sandboxes, see Create Sandbox. For the end-to-end snapshot workflow, see Snapshots.

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json
​
image
string

Optional sandbox image name to boot from. When omitted, Tensorlake uses the default managed environment. This can also be a registered Sandbox Image name.

​
resources
object
​
secret_names
string[]

Secret names to inject into the sandbox.

​
timeout_secs
integer<int64>

Sandbox timeout in seconds. 0 requests the maximum allowed by your plan. Plan maximums: Free unverified 3600 (1h), Free verified 7200 (2h), On-Demand 86400 (24h). See tensorlake.ai/pricing for higher limits on committed plans.

Required range: x >= 0
​
entrypoint
string[]

Optional command to run when the sandbox starts.

​
network
object
​
snapshot_id
string

Snapshot to restore from.

​
allow_unauthenticated_access
boolean

Allow sandbox ingress to route requests without validating auth credentials. The legacy request alias allow_unauthenticated_proxy_access is also accepted.

​
exposed_ports
integer<int32>[]

Additional sandbox ports that public ingress may route to. When omitted, only the management port 9501 is routable.

Required range: 1 <= x <= 65535
​
template_id
string

Template identifier to associate with the launched sandbox.

​
name
string

Optional user-provided sandbox name. When set, the sandbox is named and supports suspend/resume. When omitted, the sandbox is ephemeral.

Response

Sandbox created successfully

​
sandbox_id
string
required
​
status
enum<string>
required
Available options:
pending,
running,
snapshotting,
suspending,
suspended,
terminated
​
pending_reason
enum<string>
Available options:
scheduling,
waiting_for_container,
no_executors_available,
no_resources_available,
pool_at_capacity
​
ingress_endpoint
string | null

Base ingress origin for this sandbox's current placement.