# How Per-Sandbox Traffic Tokens Harden Network Policies in CubeSandbox

> Discover how CubeSandbox uses per-sandbox traffic tokens and policy routing to harden network policies. Learn how CubeProxy enforces cryptographic gates for secure access.

- Repository: [Tencent Cloud/CubeSandbox](https://github.com/TencentCloud/CubeSandbox)
- Tags: how-to-guide
- Published: 2026-07-16

---

**When `network.allow_public_traffic` is set to `false`, CubeSandbox generates a unique UUID v4 token for each sandbox that must be presented in request headers to access public endpoints, effectively creating a cryptographic gate enforced by CubeProxy.**

CubeSandbox, Tencent Cloud's open-source sandbox environment, implements defense-in-depth network security through per-sandbox traffic tokens. This mechanism allows developers to completely disable public inbound access while maintaining programmatic accessibility through cryptographically unique tokens that are validated at the proxy layer.

## Token Generation and Storage Architecture

When you create a sandbox with restricted network access, the platform generates a cryptographically secure token that follows the sandbox lifecycle.

### CubeMaster Type Definition

In the CubeMaster service, the sandbox struct definition includes the `TrafficAccessToken` field to persist the generated token:

[Source](https://github.com/TencentCloud/CubeSandbox/blob/master/CubeMaster/pkg/service/sandbox/types/types.go)

### API Model Definition

The CubeAPI component defines the token in its Rust models as an optional string field exposed to clients:

[Source](https://github.com/TencentCloud/CubeSandbox/blob/master/CubeAPI/src/models/mod.rs)

### Documentation and Lifecycle

The restriction capability is documented in the official guide, which explains that setting `network.allow_public_traffic` to `false` triggers token generation during sandbox creation. The token is returned in the creation response under the JSON field `trafficAccessToken` and is immutable for the sandbox's lifetime.

[Source](https://github.com/TencentCloud/CubeSandbox/blob/master/docs/guide/restrict-public-access.md)

This feature was introduced in version 0.5.0 as "Traffic access token gating" for hardened network policies.

[Source](https://github.com/TencentCloud/CubeSandbox/blob/master/docs/changelog/v0.5.0.md)

## Token Enforcement Architecture

The enforcement of traffic tokens occurs at the edge proxy layer, ensuring unauthorized requests never reach the sandbox environment.

### CubeProxy Lua Validation

CubeProxy, the reverse proxy fronting each sandbox, executes a Lua script that extracts and validates tokens from incoming requests. The script checks for the token in two possible HTTP headers:

```lua
-- CubeProxy/lua/sandbox_backend.lua
local provided = ngx.var.http_e2b_traffic_access_token
               or ngx.var.http_cube_traffic_access_token

```

[Source](https://github.com/TencentCloud/CubeSandbox/blob/master/CubeProxy/lua/sandbox_backend.lua#L36-L37)

If the header is missing or the provided value does not match the sandbox's stored token, CubeProxy immediately returns **HTTP 403 Forbidden** before the request reaches the sandbox container.

### Security-First Logging

The token is intentionally redacted from all proxy and application logs to prevent accidental credential leakage in log aggregation systems.

## SDK Implementation and Access

Both the Python and Node.js SDKs provide first-class support for retrieving and automatically injecting traffic tokens.

### Python SDK Token Property

The Python SDK exposes the token via the `traffic_access_token` property in the `Sandbox` class:

```python

# sdk/python/cubesandbox/sandbox.py

@property
def traffic_access_token(self) -> str | None:
    """Returns the traffic access token for this sandbox, if restricted."""
    return self._data.get("trafficAccessToken")

```

[Source](https://github.com/TencentCloud/CubeSandbox/blob/master/sdk/python/cubesandbox/sandbox.py#L6-L22)

### Automatic Header Injection

When making requests to sandbox endpoints, the SDK automatically attaches the appropriate headers. The Python implementation defines a helper method:

```python
def _traffic_token_headers(self):
    headers = {}
    if self.traffic_access_token:
        headers["e2b-traffic-access-token"] = self.traffic_access_token
    return headers

```

[Source](https://github.com/TencentCloud/CubeSandbox/blob/master/sdk/python/cubesandbox/sandbox.py#L78-L86)

The Node.js SDK implements equivalent logic in the `_traffic_token_headers()` method to ensure consistent behavior across languages.

[Source](https://github.com/TencentCloud/CubeSandbox/blob/master/sdk/node/src/sandbox.ts#L258-L307)

## Practical Implementation Examples

### Python SDK Example

Create a restricted sandbox and access its public endpoints using the generated token:

```python
from cubesandbox import Sandbox
import requests

# Create sandbox with public traffic disabled

with Sandbox.create(network={"allow_public_traffic": False}) as sb:
    token = sb.traffic_access_token
    print(f"Token acquired: {token[:8]}...")  # Token is a UUID v4

    
    # Access the sandbox's public URL

    url = f"https://{sb.get_host(49999)}/"
    response = requests.get(
        url, 
        headers={"e2b-traffic-access-token": token}
    )
    print(response.status_code)  # 200 if token valid, 403 if missing/invalid

```

### Node.js SDK Example

The Node.js SDK provides equivalent functionality for TypeScript and JavaScript applications:

```typescript
import { Sandbox } from "cubesandbox";

async function accessRestrictedSandbox() {
  const sb = await Sandbox.create({ 
    network: { allow_public_traffic: false } 
  });
  
  const token = sb.trafficAccessToken;
  if (!token) throw new Error("Expected token for restricted sandbox");
  
  const url = `https://${sb.getHost(49999)}/`;
  const response = await fetch(url, {
    headers: { "e2b-traffic-access-token": token }
  });
  
  console.log(response.status); // 200 on success, 403 on invalid token
}

accessRestrictedSandbox();

```

### Raw HTTP with cURL

For direct API access without SDKs, include the token in the request headers:

```bash

# Create sandbox and extract TOKEN from response

TOKEN="your-uuid-v4-token-here"

# Access the sandbox endpoint

curl -H "e2b-traffic-access-token: $TOKEN" \
     https://49999-<sandbox-id>.cube.app/

```

If the header is omitted or the token is incorrect, the proxy returns:

```http
HTTP/1.1 403 Forbidden
Content-Type: text/plain

Traffic access token mismatch

```

## Summary

- **Per-sandbox tokens** are UUID v4 strings generated when `network.allow_public_traffic` is set to `false`, creating a cryptographic identity for each sandbox instance.
- **Proxy-level enforcement** occurs in [`CubeProxy/lua/sandbox_backend.lua`](https://github.com/TencentCloud/CubeSandbox/blob/main/CubeProxy/lua/sandbox_backend.lua), which validates the `e2b-traffic-access-token` or `cube-traffic-access-token` headers before forwarding requests.
- **SDK integration** provides seamless access via `traffic_access_token` properties in Python and Node.js, with automatic header injection for authenticated requests.
- **Security hardening** includes complete token redaction from logs and immediate 403 responses for missing or mismatched tokens, ensuring zero-trust network access.

## Frequently Asked Questions

### What happens if I request a restricted sandbox without the traffic token?

CubeProxy returns **HTTP 403 Forbidden** immediately, preventing the request from reaching the sandbox container. The response body typically indicates a token mismatch, and the event is logged with the client IP but with the token value redacted to prevent credential leakage.

### Can I rotate or regenerate the traffic access token after sandbox creation?

No. According to the current implementation in [`CubeMaster/pkg/service/sandbox/types/types.go`](https://github.com/TencentCloud/CubeSandbox/blob/main/CubeMaster/pkg/service/sandbox/types/types.go), the token is generated once during sandbox creation and persists for the sandbox's entire lifetime. To obtain a new token, you must create a new sandbox instance with `allow_public_traffic: false`; there is no API endpoint for token rotation of existing sandboxes.

### Is the traffic access token the same as my CubeSandbox API key?

No. The **API key** authenticates your requests to the CubeSandbox management API (CubeMaster/CubeAPI), while the **traffic access token** authorizes inbound HTTP traffic to the sandbox itself. The traffic token is specific to each sandbox instance and is meaningless to the management API, providing isolation between infrastructure authentication and runtime network policies.

### Does enabling public traffic restriction affect outbound connections from the sandbox?

No. The `allow_public_traffic` flag only controls **inbound** traffic to the sandbox's public endpoints. Outbound connections initiated from within the sandbox to external services remain unaffected by this policy, as the token validation only occurs on the ingress path through CubeProxy.