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
Create Sandbox
Create an ephemeral or named sandbox and configure automatic resume.
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"
}Launch an ephemeral or named sandbox.
The response includes the sandbox’s
Read
ingress_endpoint. Prefer it over constructing *.sandbox.tensorlake.ai hostnames yourself when building sandbox-specific URLs in client code.
- Set
waittofalseto get202with the sandboxpendingas soon as it is durable, instead of waiting for it to run; pollGET /sandboxes/{id}orGET /sandboxesfor readiness. See Non-blocking Sandbox Creation. - Set
max_pending_secsto bound how long the sandbox may wait for capacity; when it runs out the sandbox terminates withtermination_reasonno_capacity. Omit it to wait indefinitely. - Omit
nameto create an ephemeral sandbox. - Set
nameto create a named sandbox that supports suspend and resume. - Set
snapshot_idto restore from a snapshot, orimageto boot from a registered Sandbox Image. - For fresh creates, if
resources.disk_mbis omitted, the sandbox uses the default 10 GB root disk (10240MiB). - With
image,resources.disk_mbcan be used to grow the root disk at create time (growth-only). - With
snapshot_idfrom a filesystem snapshot,resources.disk_mbcan be used to grow the root disk at create time (growth-only).
Control automatic resume
Set the optional booleanauto_resume to false when creating a named sandbox to prevent proxy traffic from waking it after suspension. Omit it to use the default, true. Setting it to false without a name returns 400 Bad Request, because ephemeral sandboxes cannot suspend.
This request creates a running named sandbox with automatic resume disabled; it does not suspend it:
curl -X POST https://api.tensorlake.ai/sandboxes \
-H "Authorization: Bearer $TENSORLAKE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"name":"parked-agent","auto_resume":false}'
auto_resume from Get Sandbox after creation. The compact create response does not include it. See Keep a sandbox suspended for the complete lifecycle.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, resume_failed 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?