Tensorlake Documentation

Sandboxes support two networking features:

Routing internet traffic into services running inside a sandbox through *.sandbox.tensorlake.ai
Restricting the sandbox’s own outbound internet access

Sandbox Public URL

Every running sandbox is reachable through sandbox-specific ingress.

https://<sandbox-id-or-name>.sandbox.tensorlake.ai routes to the sandbox management API on port 9501
https://<port>-<sandbox-id-or-name>.sandbox.tensorlake.ai routes to a user service listening on <port> inside the sandbox

The proxy preserves the request path and query string, supports WebSocket upgrades, and forwards gRPC over HTTP/2. The hostname can use either the sandbox ID or a sandbox name. The proxy resolves names to the sandbox’s canonical ID before forwarding the request. These examples use the familiar *.sandbox.tensorlake.ai hostname pattern. The returned sandbox_url is the management URL on port 9501.

Route Traffic Into Sandbox Apps

There are two access modes for internet-facing sandbox traffic:

Authenticated requests: the caller sends TensorLake auth credentials, and the proxy authorizes the request before forwarding it.
Unauthenticated requests: the sandbox owner explicitly makes selected user ports public, and the proxy skips auth for those user ports.

Expose a User Port

Port 9501 is the built-in management API and is always routable through the bare sandbox hostname. For any other port, the proxy only forwards requests if that port is listed in exposed_ports.

allow_unauthenticated_access does not expose a port by itself. User ports still have to be present in exposed_ports.

Authenticated-Only Exposure with the HTTP API

Use this when a port should be routable from the internet but still require TensorLake auth on every request.

Python
TypeScript
HTTP

from tensorlake.sandbox import Sandbox


sandbox = client.expose_ports(
    "my-env",
    [8080],
    allow_unauthenticated_access=False,
)

print(sandbox.exposed_ports)

sandbox = client.unexpose_ports("my-env", [8080])
print(sandbox.exposed_ports)

const sandbox = await client.exposePorts(
  "my-env",
  [8080],
  { allowUnauthenticatedAccess: false },
);

console.log(sandbox.exposedPorts);

const updated = await client.unexposePorts("my-env", [8080]);
console.log(updated.exposedPorts);

curl -X PATCH https://api.tensorlake.ai/sandboxes/<sandbox-id-or-name> \
  -H "Authorization: Bearer $TENSORLAKE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "allow_unauthenticated_access": false,
    "exposed_ports": [8080]
  }'

curl -X PATCH https://api.tensorlake.ai/sandboxes/<sandbox-id-or-name> \
  -H "Authorization: Bearer $TENSORLAKE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "allow_unauthenticated_access": false,
    "exposed_ports": []
  }'

Unauthenticated Public Internet Access with the CLI

Use this when you want anyone on the internet to be able to reach a sandbox app without TensorLake credentials. Common cases include webhook receivers, demo apps, public APIs, browser clients, and temporary preview environments.

CLI
Python
TypeScript
HTTP

tl sbx port expose <sandbox-id-or-name> 8080
tl sbx port ls <sandbox-id-or-name>
tl sbx port rm <sandbox-id-or-name> 8080

from tensorlake.sandbox import Sandbox


sandbox = client.expose_ports(
    "my-public-sandbox",
    [8080],
    allow_unauthenticated_access=True,
)

print(sandbox.allow_unauthenticated_access, sandbox.exposed_ports)

sandbox = client.unexpose_ports("my-public-sandbox", [8080])
print(sandbox.allow_unauthenticated_access, sandbox.exposed_ports)

const sandbox = await client.exposePorts(
  "my-public-sandbox",
  [8080],
  { allowUnauthenticatedAccess: true },
);

console.log(sandbox.allowUnauthenticatedAccess, sandbox.exposedPorts);

const updated = await client.unexposePorts("my-public-sandbox", [8080]);
console.log(updated.allowUnauthenticatedAccess, updated.exposedPorts);

curl -X PATCH https://api.tensorlake.ai/sandboxes/<sandbox-id-or-name> \
  -H "Authorization: Bearer $TENSORLAKE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "allow_unauthenticated_access": true,
    "exposed_ports": [8080]
  }'

curl -X PATCH https://api.tensorlake.ai/sandboxes/<sandbox-id-or-name> \
  -H "Authorization: Bearer $TENSORLAKE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "allow_unauthenticated_access": false,
    "exposed_ports": []
  }'

The CLI port expose workflow sets both:

exposed_ports
allow_unauthenticated_access=true

So traffic to that user port becomes publicly reachable from the internet without TensorLake auth.

Authenticated Requests

Authenticated routing is the default model for sandbox access.

The management URL on port 9501 always requires auth
User ports can also require auth when they are exposed but allow_unauthenticated_access=false

Verified against sandbox-proxy, the proxy accepts these auth modes:

API key: Authorization: Bearer <api-key>
Personal access token: Authorization: Bearer tl_pat... plus X-Forwarded-Organization-Id and X-Forwarded-Project-Id
Session cookie: tl.session_token or legacy tl-session, plus the same forwarded organization/project context

For browser WebSocket clients that cannot set custom X-Forwarded-* headers, the proxy also accepts organizationId and projectId in the query string.

API Key
PAT
Cookie

curl https://8080-<sandbox-id-or-name>.sandbox.tensorlake.ai/health \
  -H "Authorization: Bearer $TENSORLAKE_API_KEY"

curl https://8080-<sandbox-id-or-name>.sandbox.tensorlake.ai/health \
  -H "Authorization: Bearer $TENSORLAKE_PAT" \
  -H "X-Forwarded-Organization-Id: $TENSORLAKE_ORGANIZATION_ID" \
  -H "X-Forwarded-Project-Id: $TENSORLAKE_PROJECT_ID"

curl https://8080-<sandbox-id-or-name>.sandbox.tensorlake.ai/health \
  -H "Cookie: tl.session_token=$TENSORLAKE_SESSION_TOKEN" \
  -H "X-Forwarded-Organization-Id: $TENSORLAKE_ORGANIZATION_ID" \
  -H "X-Forwarded-Project-Id: $TENSORLAKE_PROJECT_ID"

You can use the same authenticated routing model for HTTP, gRPC, and WebSocket services:

# HTTP
curl https://8080-<sandbox-id-or-name>.sandbox.tensorlake.ai/health \
  -H "Authorization: Bearer $TENSORLAKE_API_KEY"

# gRPC
grpcurl \
  -H "Authorization: Bearer $TENSORLAKE_API_KEY" \
  50051-<sandbox-id-or-name>.sandbox.tensorlake.ai:443 \
  list

# WebSocket
wscat \
  -H "Authorization: Bearer $TENSORLAKE_API_KEY" \
  -c "wss://3000-<sandbox-id-or-name>.sandbox.tensorlake.ai/socket"

const response = await fetch(
  "https://8080-my-env.sandbox.tensorlake.ai/health",
  {
    headers: {
      Authorization: `Bearer ${process.env.TENSORLAKE_API_KEY}`,
    },
  },
);

console.log(await response.text());

Unauthenticated Requests

To make a user port public on the internet, both of these conditions must be true:

the port is in exposed_ports
allow_unauthenticated_access=true

When those are set, the proxy skips TensorLake auth for that user port.

curl -X PATCH https://api.tensorlake.ai/sandboxes/<sandbox-id-or-name> \
  -H "Authorization: Bearer $TENSORLAKE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "allow_unauthenticated_access": true,
    "exposed_ports": [8080]
  }'

After that, requests to the exposed user port can omit auth entirely:

curl https://8080-<sandbox-id-or-name>.sandbox.tensorlake.ai/health

const response = await fetch(
  "https://8080-my-public-sandbox.sandbox.tensorlake.ai/health",
);

console.log(await response.text());

Unauthenticated access only applies to user ports. The management API on port 9501 never becomes public.

If a named sandbox is suspended, the proxy can auto-resume it when a request arrives for an exposed port.

Outbound Internet Access

By default, sandboxes have outbound internet access enabled. Disable it for untrusted code:

Python
TypeScript
HTTP
CLI

from tensorlake.sandbox import Sandbox


sandbox = Sandbox.create(
    allow_internet_access=False
)

const sandbox = await Sandbox.create({
  allowInternetAccess: false,
});

console.log(sandbox.sandboxId);

curl -X POST https://api.tensorlake.ai/sandboxes \
  -H "Authorization: Bearer $TENSORLAKE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "network": {"allow_internet_access": false}
  }'

tl sbx create --no-internet

In a verified public-cloud test, a sandbox created with allow_internet_access=False failed DNS resolution for https://example.com, confirming that outbound internet access was disabled. Setting allow_internet_access=false blocks all outbound traffic, including DNS requests. In the CLI, --no-internet (or -N) cannot be combined with --network-allow or --network-deny.

Allow Specific Destinations

Use allow_out when you want a sandbox to reach only selected destinations.

values can be domains, IPv4 addresses, or IPv4 CIDR ranges
deny_out takes precedence: a destination matched by both allow_out and deny_out is blocked
hostname rules are followed across DNS changes, so a CDN-backed domain keeps working as its IP addresses rotate

Python
TypeScript
HTTP
CLI

sandbox = Sandbox.create(
    allow_internet_access=True,
    allow_out=["example.com", "203.0.113.10", "10.0.0.0/8"],
)

const sandbox = await Sandbox.create({
  allowInternetAccess: true,
  allowOut: ["example.com", "203.0.113.10", "10.0.0.0/8"],
});

console.log(sandbox.sandboxId);

curl -X POST https://api.tensorlake.ai/sandboxes \
  -H "Authorization: Bearer $TENSORLAKE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "network": {
      "allow_internet_access": true,
      "allow_out": ["example.com", "203.0.113.10", "10.0.0.0/8"]
    }
  }'

tl sbx create \
  --network-allow example.com \
  --network-allow 203.0.113.10 \
  --network-allow 10.0.0.0/8

This allows DNS requests to the sandbox’s configured resolvers and traffic to the listed domain, IPv4 address, and IPv4 CIDR range. All other outbound traffic is blocked. The short form of --network-allow is -A.

Block Specific Destinations

Python
TypeScript
HTTP
CLI

sandbox = Sandbox.create(
    deny_out=["example.com"]
)

const sandbox = await Sandbox.create({
  denyOut: ["example.com"],
});

console.log(sandbox.sandboxId);

curl -X POST https://api.tensorlake.ai/sandboxes \
  -H "Authorization: Bearer $TENSORLAKE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "network": {"deny_out": ["example.com"]}
  }'

tl sbx create --network-deny example.com

In a verified public-cloud request, deny_out=["example.com"] blocked https://example.com while https://api.openai.com/v1/models still returned 401, confirming outbound connectivity was still available for destinations that were not denied. The short form of --network-deny is -D. You can combine -A and -D; deny rules take precedence when a destination matches both lists.

Update the Policy on a Running Sandbox

You can change a sandbox’s egress policy without recreating or suspending it. The new policy is applied to the running sandbox’s firewall as a single atomic swap, so there is no window where egress is unprotected. Already-established connections are not interrupted. The network argument is tri-state:

omit it to leave the current policy unchanged (you can update name or exposed ports without touching the network policy),
pass a policy to replace the whole policy, or
clear it to return the sandbox to unrestricted egress.

Python
TypeScript
HTTP
CLI

from tensorlake.sandbox import CLEAR_NETWORK_POLICY, NetworkConfig, Sandbox

sandbox = Sandbox.connect("<sandbox-id>")

# Replace the policy: allow only api.example.com.
sandbox.update(
    network=NetworkConfig(
        allow_internet_access=True,
        allow_out=["api.example.com"],
    )
)

# Later, clear the policy (unrestricted egress).
sandbox.update(network=CLEAR_NETWORK_POLICY)

const sandbox = await Sandbox.connect({ sandboxId: "<sandbox-id>" });

// Replace the policy: allow only api.example.com.
await sandbox.update({
  network: {
    allowInternetAccess: true,
    allowOut: ["api.example.com"],
    denyOut: [],
  },
});

// Later, clear the policy (unrestricted egress) by passing null.
await sandbox.update({ network: null });

# Replace the policy.
curl -X PATCH https://api.tensorlake.ai/sandboxes/<sandbox-id> \
  -H "Authorization: Bearer $TENSORLAKE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "network": {
      "allow_internet_access": true,
      "allow_out": ["api.example.com"]
    }
  }'

# Clear the policy by sending an explicit null.
curl -X PATCH https://api.tensorlake.ai/sandboxes/<sandbox-id> \
  -H "Authorization: Bearer $TENSORLAKE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"network": null}'

# Replace the policy: allow only api.example.com and resolver-scoped DNS.
tl sbx update <sandbox-id-or-name> -A api.example.com

# Replace the policy and block all outbound traffic, including DNS.
tl sbx update <sandbox-id-or-name> --no-internet

# Clear the policy and restore unrestricted egress.
tl sbx update <sandbox-id-or-name> --clear-network

Each tl sbx update command replaces or clears the complete network policy. Repeat -A or -D to add multiple rules to the replacement policy. --no-internet is an absolute block-all mode and cannot be combined with either rule flag; --clear-network cannot be combined with any replacement-policy flag.

If a hostname in the new policy cannot be resolved, the update is rejected and the previous policy stays fully enforced — the sandbox keeps running under the policy it already had.

This is useful for phase-based agents: start a sandbox with a broad allowlist while it fetches dependencies, then tighten to a minimal policy (or block all egress) before running untrusted work.

Network Configuration Summary

Parameter	Type	Default	Description
`allow_internet_access`	`bool`	`true`	Allows internet access, including DNS requests. If `false`, all outbound traffic is blocked, including DNS requests. If `allow_out` is non-empty and this is `true`, only the listed destinations and resolver-scoped DNS requests are allowed
`allow_out`	`list[str]`	`[]`	Allowed domains, IPv4 addresses, or IPv4 CIDRs. A non-empty list allows the listed destinations and resolver-scoped DNS requests when `allow_internet_access` is `true`
`deny_out`	`list[str]`	`[]`	Denied domains, IPv4 addresses, or IPv4 CIDRs. Takes precedence over `allow_out`: a destination matched by both is blocked
`exposed_ports`	`list[int] \| null`	`null`	User ports that the sandbox proxy is allowed to route to
`allow_unauthenticated_access`	`bool`	`false`	Skip TensorLake auth for exposed user ports. Never applies to port `9501`

Overview

Guides

Use Cases

Networking

Sandbox Public URL

Route Traffic Into Sandbox Apps

Expose a User Port

Authenticated-Only Exposure with the HTTP API

Unauthenticated Public Internet Access with the CLI

Authenticated Requests

Unauthenticated Requests

Outbound Internet Access

Allow Specific Destinations

Block Specific Destinations

Update the Policy on a Running Sandbox

Network Configuration Summary

​Sandbox Public URL

​Route Traffic Into Sandbox Apps

​Expose a User Port

​Authenticated-Only Exposure with the HTTP API

​Unauthenticated Public Internet Access with the CLI

​Authenticated Requests

​Unauthenticated Requests

​Outbound Internet Access

​Allow Specific Destinations

​Block Specific Destinations

​Update the Policy on a Running Sandbox

​Network Configuration Summary

Sandbox Public URL

Route Traffic Into Sandbox Apps

Expose a User Port

Authenticated-Only Exposure with the HTTP API

Unauthenticated Public Internet Access with the CLI

Authenticated Requests

Unauthenticated Requests

Outbound Internet Access

Allow Specific Destinations

Block Specific Destinations

Update the Policy on a Running Sandbox

Network Configuration Summary