Create a sandbox
curl --request POST \
--url https://api.tensorlake.ai/sandboxes \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"auto_resume": true,
"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>",
"wait": true,
"max_pending_secs": 1,
"file_systems": [
{
"file_system_id": "<string>",
"mount_path": "<string>",
"read_only": false,
"prefetch": false,
"snapshot_id": "<string>"
}
]
}
'import requests
url = "https://api.tensorlake.ai/sandboxes"
payload = {
"auto_resume": True,
"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>",
"wait": True,
"max_pending_secs": 1,
"file_systems": [
{
"file_system_id": "<string>",
"mount_path": "<string>",
"read_only": False,
"prefetch": False,
"snapshot_id": "<string>"
}
]
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
auto_resume: true,
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>',
wait: true,
max_pending_secs: 1,
file_systems: [
{
file_system_id: '<string>',
mount_path: '<string>',
read_only: false,
prefetch: false,
snapshot_id: '<string>'
}
]
})
};
fetch('https://api.tensorlake.ai/sandboxes', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.tensorlake.ai/sandboxes",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'auto_resume' => true,
'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>',
'wait' => true,
'max_pending_secs' => 1,
'file_systems' => [
[
'file_system_id' => '<string>',
'mount_path' => '<string>',
'read_only' => false,
'prefetch' => false,
'snapshot_id' => '<string>'
]
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.tensorlake.ai/sandboxes"
payload := strings.NewReader("{\n \"auto_resume\": true,\n \"image\": \"<string>\",\n \"resources\": {\n \"cpus\": 123,\n \"memory_mb\": 123,\n \"disk_mb\": 56320,\n \"gpus\": [\n {\n \"count\": 2,\n \"model\": \"<string>\"\n }\n ]\n },\n \"secret_names\": [\n \"<string>\"\n ],\n \"timeout_secs\": 1,\n \"entrypoint\": [\n \"<string>\"\n ],\n \"network\": {\n \"allow_internet_access\": true,\n \"allow_out\": [\n \"<string>\"\n ],\n \"deny_out\": [\n \"<string>\"\n ]\n },\n \"snapshot_id\": \"<string>\",\n \"allow_unauthenticated_access\": true,\n \"exposed_ports\": [\n 32768\n ],\n \"template_id\": \"<string>\",\n \"name\": \"<string>\",\n \"wait\": true,\n \"max_pending_secs\": 1,\n \"file_systems\": [\n {\n \"file_system_id\": \"<string>\",\n \"mount_path\": \"<string>\",\n \"read_only\": false,\n \"prefetch\": false,\n \"snapshot_id\": \"<string>\"\n }\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.tensorlake.ai/sandboxes")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"auto_resume\": true,\n \"image\": \"<string>\",\n \"resources\": {\n \"cpus\": 123,\n \"memory_mb\": 123,\n \"disk_mb\": 56320,\n \"gpus\": [\n {\n \"count\": 2,\n \"model\": \"<string>\"\n }\n ]\n },\n \"secret_names\": [\n \"<string>\"\n ],\n \"timeout_secs\": 1,\n \"entrypoint\": [\n \"<string>\"\n ],\n \"network\": {\n \"allow_internet_access\": true,\n \"allow_out\": [\n \"<string>\"\n ],\n \"deny_out\": [\n \"<string>\"\n ]\n },\n \"snapshot_id\": \"<string>\",\n \"allow_unauthenticated_access\": true,\n \"exposed_ports\": [\n 32768\n ],\n \"template_id\": \"<string>\",\n \"name\": \"<string>\",\n \"wait\": true,\n \"max_pending_secs\": 1,\n \"file_systems\": [\n {\n \"file_system_id\": \"<string>\",\n \"mount_path\": \"<string>\",\n \"read_only\": false,\n \"prefetch\": false,\n \"snapshot_id\": \"<string>\"\n }\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.tensorlake.ai/sandboxes")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"auto_resume\": true,\n \"image\": \"<string>\",\n \"resources\": {\n \"cpus\": 123,\n \"memory_mb\": 123,\n \"disk_mb\": 56320,\n \"gpus\": [\n {\n \"count\": 2,\n \"model\": \"<string>\"\n }\n ]\n },\n \"secret_names\": [\n \"<string>\"\n ],\n \"timeout_secs\": 1,\n \"entrypoint\": [\n \"<string>\"\n ],\n \"network\": {\n \"allow_internet_access\": true,\n \"allow_out\": [\n \"<string>\"\n ],\n \"deny_out\": [\n \"<string>\"\n ]\n },\n \"snapshot_id\": \"<string>\",\n \"allow_unauthenticated_access\": true,\n \"exposed_ports\": [\n 32768\n ],\n \"template_id\": \"<string>\",\n \"name\": \"<string>\",\n \"wait\": true,\n \"max_pending_secs\": 1,\n \"file_systems\": [\n {\n \"file_system_id\": \"<string>\",\n \"mount_path\": \"<string>\",\n \"read_only\": false,\n \"prefetch\": false,\n \"snapshot_id\": \"<string>\"\n }\n ]\n}"
response = http.request(request)
puts response.read_body{
"sandbox_id": "<string>",
"status": "pending",
"pending_reason": "scheduling",
"ingress_endpoint": "<string>"
}{
"sandbox_id": "<string>",
"state": "pending",
"name": "<string>",
"pending_reason": "scheduling"
}Life Cycle Management
Restore Sandbox
Restore a sandbox from a previously created snapshot by calling the create endpoint with a snapshot_id.
POST
/
sandboxes
Create a sandbox
curl --request POST \
--url https://api.tensorlake.ai/sandboxes \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"auto_resume": true,
"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>",
"wait": true,
"max_pending_secs": 1,
"file_systems": [
{
"file_system_id": "<string>",
"mount_path": "<string>",
"read_only": false,
"prefetch": false,
"snapshot_id": "<string>"
}
]
}
'import requests
url = "https://api.tensorlake.ai/sandboxes"
payload = {
"auto_resume": True,
"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>",
"wait": True,
"max_pending_secs": 1,
"file_systems": [
{
"file_system_id": "<string>",
"mount_path": "<string>",
"read_only": False,
"prefetch": False,
"snapshot_id": "<string>"
}
]
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
auto_resume: true,
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>',
wait: true,
max_pending_secs: 1,
file_systems: [
{
file_system_id: '<string>',
mount_path: '<string>',
read_only: false,
prefetch: false,
snapshot_id: '<string>'
}
]
})
};
fetch('https://api.tensorlake.ai/sandboxes', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.tensorlake.ai/sandboxes",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'auto_resume' => true,
'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>',
'wait' => true,
'max_pending_secs' => 1,
'file_systems' => [
[
'file_system_id' => '<string>',
'mount_path' => '<string>',
'read_only' => false,
'prefetch' => false,
'snapshot_id' => '<string>'
]
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.tensorlake.ai/sandboxes"
payload := strings.NewReader("{\n \"auto_resume\": true,\n \"image\": \"<string>\",\n \"resources\": {\n \"cpus\": 123,\n \"memory_mb\": 123,\n \"disk_mb\": 56320,\n \"gpus\": [\n {\n \"count\": 2,\n \"model\": \"<string>\"\n }\n ]\n },\n \"secret_names\": [\n \"<string>\"\n ],\n \"timeout_secs\": 1,\n \"entrypoint\": [\n \"<string>\"\n ],\n \"network\": {\n \"allow_internet_access\": true,\n \"allow_out\": [\n \"<string>\"\n ],\n \"deny_out\": [\n \"<string>\"\n ]\n },\n \"snapshot_id\": \"<string>\",\n \"allow_unauthenticated_access\": true,\n \"exposed_ports\": [\n 32768\n ],\n \"template_id\": \"<string>\",\n \"name\": \"<string>\",\n \"wait\": true,\n \"max_pending_secs\": 1,\n \"file_systems\": [\n {\n \"file_system_id\": \"<string>\",\n \"mount_path\": \"<string>\",\n \"read_only\": false,\n \"prefetch\": false,\n \"snapshot_id\": \"<string>\"\n }\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.tensorlake.ai/sandboxes")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"auto_resume\": true,\n \"image\": \"<string>\",\n \"resources\": {\n \"cpus\": 123,\n \"memory_mb\": 123,\n \"disk_mb\": 56320,\n \"gpus\": [\n {\n \"count\": 2,\n \"model\": \"<string>\"\n }\n ]\n },\n \"secret_names\": [\n \"<string>\"\n ],\n \"timeout_secs\": 1,\n \"entrypoint\": [\n \"<string>\"\n ],\n \"network\": {\n \"allow_internet_access\": true,\n \"allow_out\": [\n \"<string>\"\n ],\n \"deny_out\": [\n \"<string>\"\n ]\n },\n \"snapshot_id\": \"<string>\",\n \"allow_unauthenticated_access\": true,\n \"exposed_ports\": [\n 32768\n ],\n \"template_id\": \"<string>\",\n \"name\": \"<string>\",\n \"wait\": true,\n \"max_pending_secs\": 1,\n \"file_systems\": [\n {\n \"file_system_id\": \"<string>\",\n \"mount_path\": \"<string>\",\n \"read_only\": false,\n \"prefetch\": false,\n \"snapshot_id\": \"<string>\"\n }\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.tensorlake.ai/sandboxes")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"auto_resume\": true,\n \"image\": \"<string>\",\n \"resources\": {\n \"cpus\": 123,\n \"memory_mb\": 123,\n \"disk_mb\": 56320,\n \"gpus\": [\n {\n \"count\": 2,\n \"model\": \"<string>\"\n }\n ]\n },\n \"secret_names\": [\n \"<string>\"\n ],\n \"timeout_secs\": 1,\n \"entrypoint\": [\n \"<string>\"\n ],\n \"network\": {\n \"allow_internet_access\": true,\n \"allow_out\": [\n \"<string>\"\n ],\n \"deny_out\": [\n \"<string>\"\n ]\n },\n \"snapshot_id\": \"<string>\",\n \"allow_unauthenticated_access\": true,\n \"exposed_ports\": [\n 32768\n ],\n \"template_id\": \"<string>\",\n \"name\": \"<string>\",\n \"wait\": true,\n \"max_pending_secs\": 1,\n \"file_systems\": [\n {\n \"file_system_id\": \"<string>\",\n \"mount_path\": \"<string>\",\n \"read_only\": false,\n \"prefetch\": false,\n \"snapshot_id\": \"<string>\"\n }\n ]\n}"
response = http.request(request)
puts response.read_body{
"sandbox_id": "<string>",
"status": "pending",
"pending_reason": "scheduling",
"ingress_endpoint": "<string>"
}{
"sandbox_id": "<string>",
"state": "pending",
"name": "<string>",
"pending_reason": "scheduling"
}Restore a new sandbox from a previously created snapshot.
To restore from a snapshot, call the standard create sandbox endpoint and include
For filesystem snapshots,
Endpoint
POST /sandboxes
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>"
}'
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
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Body
application/json
Whether proxy traffic may wake this sandbox while suspended. Set false to require explicit resume after suspension. False requires a name; unnamed sandboxes return 400 because they cannot suspend. This setting does not suspend a running sandbox.
Optional sandbox image name to boot from. When omitted, Tensorlake uses the default managed environment. This can also be a registered Sandbox Image name.
Show child attributes
Show child attributes
Secret names to inject into the sandbox.
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 >= 0Optional command to run when the sandbox starts.
Show child attributes
Show child attributes
Snapshot to restore from.
Allow sandbox ingress to route requests without validating auth credentials. The legacy request alias allow_unauthenticated_proxy_access is also accepted.
Additional sandbox ports that public ingress may route to. When omitted, only the management port 9501 is routable.
Required range:
1 <= x <= 65535Template identifier to associate with the launched sandbox.
Optional user-provided sandbox name. When set, the sandbox is named and supports suspend/resume. When omitted, the sandbox is ephemeral.
false returns 202 with the sandbox in pending as soon as it is durable, instead of waiting for it to run. Poll GET /sandboxes/{id} or GET /sandboxes for readiness.
Longest the sandbox may wait for capacity, in seconds. When it runs out while the sandbox is still waiting for a host, the sandbox is terminated with termination_reason no_capacity and its last pending_reason. 0 fails at once if the sandbox cannot be placed. Omit to wait indefinitely. Bare-metal hosts take up to 20 minutes to boot, so use 1800 or more for capacity waits.
Required range:
x >= 0Filesystems to mount into the sandbox, each at its own absolute, unique, non-nested guest mount path. At most 8 per sandbox. Mounts are ready before the sandbox is reported as running; a filesystem that does not exist fails the create with 422 and reason FileSystemNotFound, and a pinned snapshot_id that is not a permanent snapshot fails it with reason FileSystemSnapshotNotFound.
Show child attributes
Show child attributes
Response
Sandbox created successfully
Available options:
pending, running, snapshotting, suspending, suspended, terminated Available options:
scheduling, waiting_for_container, no_executors_available, no_resources_available, pool_at_capacity, max_capacity_reached, no_executor_for_snapshot_location Base ingress origin for this sandbox's current placement.
Was this page helpful?