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>",
"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 = {
"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({
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([
'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 \"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 \"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 \"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.
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>",
"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 = {
"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({
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([
'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 \"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 \"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 \"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
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).
Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Body
application/json
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?