Tensorlake Documentation

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>",
  "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>",
    "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>',
    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>',
    '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  \"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  \"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  \"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>"
}

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>",
  "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>",
    "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>',
    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>',
    '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  \"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  \"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  \"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>"
}

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

Show child attributes

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

Show child attributes

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.

file_systems

object[]

Filesystems 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

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.

API Documentation

Sandboxes

Restore Sandbox

Endpoint

Example Request

Authorizations

Body

Response

​Endpoint

​Example Request

Authorizations

Body

Response

Endpoint

Example Request