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

Authenticate direct requests to the sandbox proxy with a project-scoped API key. The key selects the project, so callers do not send forwarded organization or project headers:

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

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());

Browser session authentication

Browser applications can authenticate requests to the sandbox proxy with the user’s Tensorlake Cloud session cookie. This is a browser-facing proxy flow, not SDK authentication; Python and TypeScript SDK clients continue to use only a project-scoped API key. The browser sends the current tl.session_token cookie automatically. The legacy tl-session name also remains supported during migration. Because a user session can access more than one project, include the organization and project currently selected in the application as the organizationId and projectId query parameters:

const url = new URL(
  "https://8080-my-env.sandbox.tensorlake.ai/health",
);
url.searchParams.set("organizationId", organizationId);
url.searchParams.set("projectId", projectId);

const response = await fetch(url, {
  credentials: "include",
});

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

Use the same query parameters for browser WebSocket clients, which cannot set custom headers on the upgrade request:

const url = new URL(
  "wss://3000-my-env.sandbox.tensorlake.ai/socket",
);
url.searchParams.set("organizationId", organizationId);
url.searchParams.set("projectId", projectId);

const socket = new WebSocket(url);

The sandbox proxy consumes the Tensorlake session cookie and removes it before forwarding the request to the sandbox. Your application does not receive the platform session credential; its other cookies are preserved.

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 with an empty allow_out blocks all outbound traffic, including DNS requests. Combined with a non-empty allow_out, the listed destinations stay reachable, but DNS remains blocked unless the resolver’s IP address is itself listed in allow_out. 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, leading-wildcard domains like *.example.com, 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

A wildcard entry matches all subdomains but not the apex domain itself: *.example.com matches api.example.com and v1.api.example.com, but not example.com. Add the apex as a separate entry if you need it too. Wildcards are only supported in allow_out, not deny_out.

Python
TypeScript
HTTP
CLI

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

const sandbox = await Sandbox.create({
  allowInternetAccess: true,
  allowOut: ["example.com", "*.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", "*.example.com", "203.0.113.10", "10.0.0.0/8"]
    }
  }'

tl sbx create \
  --network-allow example.com \
  --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 destinations. All other outbound traffic is blocked. The short form of --network-allow is -A. Quote wildcard entries in the shell so * is not expanded.

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. Every policy update closes the connections that the previous policy allowed. This is intentional: a firewall change must also apply to traffic that was already flowing. After an update, processes in the sandbox must open new connections, and each new connection is checked against the new policy. Clearing the policy also closes existing connections. 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`	When `allow_out` is empty, acts as a simple on/off switch for all outbound traffic. When `allow_out` is non-empty, only controls DNS. See the matrix below
`allow_out`	`list[str]`	`[]`	Allowed domains, leading-wildcard domains (`*.example.com`), IPv4 addresses, or IPv4 CIDRs. A non-empty list makes the sandbox default-deny: only the listed destinations are reachable, regardless of `allow_internet_access`
`deny_out`	`list[str]`	`[]`	Denied domains, IPv4 addresses, or IPv4 CIDRs (no wildcards). 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`

How `allow_internet_access` and `allow_out` combine

`allow_internet_access`	`allow_out`	Outbound behavior
`true`	empty	All egress open, except destinations matched by `deny_out`
`true`	non-empty	Default-deny. Only the listed destinations are reachable, plus DNS to the sandbox’s resolvers
`false`	non-empty	Default-deny. Only the listed destinations are reachable. DNS is blocked unless the resolver’s IP is itself listed in `allow_out`
`false`	empty	All egress blocked, including DNS

In short: when allow_out is empty, allow_internet_access is a simple switch for all outbound traffic. A non-empty allow_out makes the sandbox default-deny in both modes, and allow_internet_access then only controls DNS. With allow_internet_access=false, hostname entries in allow_out cannot resolve unless the resolver’s IP is also listed, so in this case, either add the resolver IP alongside them or use IP and CIDR entries only.

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

Browser session authentication

Unauthenticated Requests

Outbound Internet Access

Allow Specific Destinations

Block Specific Destinations

Update the Policy on a Running Sandbox

Network Configuration Summary

How `allow_internet_access` and `allow_out` combine

​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

​Browser session authentication

​Unauthenticated Requests

​Outbound Internet Access

​Allow Specific Destinations

​Block Specific Destinations

​Update the Policy on a Running Sandbox

​Network Configuration Summary

​How allow_internet_access and allow_out combine

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

Browser session authentication

Unauthenticated Requests

Outbound Internet Access

Allow Specific Destinations

Block Specific Destinations

Update the Policy on a Running Sandbox

Network Configuration Summary

How `allow_internet_access` and `allow_out` combine