Networking

Route internet traffic into sandbox applications and control outbound internet access

Sandboxes support two networking features:

1. Routing internet traffic into services running inside a sandbox through *.sandbox.tensorlake.ai
2. 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:

1. Authenticated requests: the caller sends TensorLake auth credentials, and the proxy authorizes the request before forwarding it.
2. 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

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)

TypeScript

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

HTTP

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

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

Python

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)

TypeScript

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

HTTP

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

from tensorlake.sandbox import Sandbox


sandbox = Sandbox.create(
    allow_internet_access=False
)

TypeScript

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

console.log(sandbox.sandboxId);

HTTP

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}
  }'

CLI

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

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

TypeScript

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

HTTP

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"]
    }
  }'

CLI

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

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

TypeScript

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

console.log(sandbox.sandboxId);

HTTP

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"]}
  }'

CLI

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

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)

TypeScript

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

HTTP

# 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}'

CLI

# 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.