# How CubeProxy Routes Requests to Sandbox Instances with E2B Protocol Compatibility

> Learn how CubeProxy routes requests to sandbox instances using Nginx and Lua. It parses requests, verifies tokens with Redis, and forwards traffic via E2B protocol compatibility. Explore the TencentCloud/CubeSandbox repository ...

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

---

**CubeProxy uses Nginx and OpenResty Lua scripts to parse incoming requests, verify traffic tokens against Redis metadata, and forward traffic to sandbox containers while maintaining compatibility with both Cube API and E2B protocols.**

CubeProxy serves as the edge gateway for TencentCloud's CubeSandbox, handling inbound HTTP traffic for both the native Cube API and the E2B-compatible protocol. Written in Lua and running on OpenResty, the proxy parses request headers or URI paths to identify target sandbox instances, validates security tokens against Redis metadata, and intelligently routes traffic to container processes. This design ensures that existing E2B SDK clients can interact with CubeSandbox instances without protocol modifications.

## Dual Entry Points for Request Routing

CubeProxy accepts traffic through two distinct routing patterns that converge on the same backend resolution logic. Both methods extract the sandbox identifier and container port, then delegate to `sandbox_backend.resolve_backend` for upstream resolution.

### Host-Based Routing (E2B-Compatible)

Requests using the hostname format `<container-port>-<sandbox-id>.<domain>` trigger the [`rewrite_phase.lua`](https://github.com/TencentCloud/CubeSandbox/blob/main/rewrite_phase.lua) script. Located at [`CubeProxy/lua/rewrite_phase.lua`](https://github.com/TencentCloud/CubeSandbox/blob/main/CubeProxy/lua/rewrite_phase.lua) (lines 5-20), this phase parses the `Host` header via `parse_port_and_instance_from_host` to extract the port and instance ID. This pattern matches the standard E2B API URL structure, allowing existing E2B clients to connect by setting their `E2B_API_URL` environment variable to the CubeProxy endpoint.

### Path-Based Routing (Cube API)

Alternatively, clients may use the URI pattern `/sandbox/<sandbox-id>/<container-port>/...`, handled by [`CubeProxy/lua/path_rewrite_phase.lua`](https://github.com/TencentCloud/CubeSandbox/blob/main/CubeProxy/lua/path_rewrite_phase.lua). This approach extracts the routing parameters directly from the request path before invoking the same backend resolution functions defined in [`sandbox_backend.lua`](https://github.com/TencentCloud/CubeSandbox/blob/main/sandbox_backend.lua).

## Backend Resolution and Metadata Lookup

The core routing logic resides in [`CubeProxy/lua/sandbox_backend.lua`](https://github.com/TencentCloud/CubeSandbox/blob/main/CubeProxy/lua/sandbox_backend.lua), where `resolve_backend` performs the heavy lifting of locating sandbox instances and enforcing access controls.

### Redis Metadata Structure

The function queries Redis for proxy metadata using the key `sandbox:proxy:<sandbox_id>` or the legacy key `bypass_host_proxy:<sandbox_id>` (lines 60-74). The returned hash contains critical fields including `HostIP` (the external host address), `SandboxIP` (the internal container IP), port mappings, `AllowPublicTraffic`, and `TrafficAccessToken`.

### Local Cache Optimization

To minimize Redis load, `resolve_backend` caches results in the Nginx shared dictionary `local_cache` with a randomized TTL calculated by `get_cache_timeout` (lines 19-33). Even cached entries enforce traffic token validation (lines 41-46), preventing stale public-access entries from bypassing security checks.

### Traffic Token Enforcement

When `AllowPublicTraffic` is set to `"false"`, the proxy requires a valid access token in either the `e2b-traffic-access-token` header (for E2B compatibility) or the `cube-traffic-access-token` header (for Cube-native clients). Missing or mismatched tokens result in a 404 response (lines 15-25 and 36-44), deliberately masking the sandbox's existence for security.

## Network Optimization and Routing Decisions

After validating tokens, `resolve_backend` determines the optimal forwarding path based on the caller's location (lines 82-99).

If the client IP (referenced as `cube_proxy_host_ip` or `server_addr`) matches the sandbox's `HostIP`, the proxy rewrites the target to the internal `SandboxIP` and forwards directly to the container port. For external callers, traffic routes to the external `HostIP` using the mapped port from the Redis metadata.

## Auto-Pause Gate and State Management

Before forwarding, both routing phases invoke `sandbox_state.gate(ins_id)` from [`CubeProxy/lua/sandbox_state.lua`](https://github.com/TencentCloud/CubeSandbox/blob/main/CubeProxy/lua/sandbox_state.lua) to respect the sandbox's pause state. If the sandbox is paused, the gate returns a 503 or 410 status (as referenced in [`rewrite_phase.lua`](https://github.com/TencentCloud/CubeSandbox/blob/main/rewrite_phase.lua) lines 35-36), preventing requests from reaching stopped containers.

## Practical Routing Examples

```bash

# Host-based routing (E2B-compatible)

curl -H "e2b-traffic-access-token: ${E2B_API_KEY}" \
     http://49983-7c8fbcd45ffe450fb8f7fb223ad45507.cube.app/hello

```

In this example, Nginx parses port `49983` and sandbox ID from the `Host` header, loads metadata from Redis, enforces the token, and forwards to the container's internal IP.

```bash

# Path-based routing (Cube API style)

curl -H "cube-traffic-access-token: ${CUBE_API_KEY}" \
     http://proxy.mycompany.com/sandbox/7c8fbcd45ffe450fb8f7fb223ad45507/49983/hello

```

Here, [`path_rewrite_phase.lua`](https://github.com/TencentCloud/CubeSandbox/blob/main/path_rewrite_phase.lua) extracts the sandbox ID and port from the URI path, runs the same `resolve_backend` logic, and proxies to the container.

## Summary

- CubeProxy leverages OpenResty Lua scripts to parse both host-based and path-based routing patterns.
- The `sandbox_backend.resolve_backend` function in [`CubeProxy/lua/sandbox_backend.lua`](https://github.com/TencentCloud/CubeSandbox/blob/main/CubeProxy/lua/sandbox_backend.lua) handles metadata retrieval from Redis, local caching, and traffic token enforcement.
- E2B compatibility is achieved by accepting the `e2b-traffic-access-token` header and parsing hostnames matching the E2B API URL format.
- Local-host optimization routes internal traffic directly to container IPs while external traffic uses mapped ports.
- The auto-pause gate prevents requests from reaching paused sandboxes.

## Frequently Asked Questions

### What is the difference between E2B and Cube API routing in CubeProxy?

There is no functional difference in the routing logic itself. Both protocols use the same Redis metadata and `resolve_backend` function. The only distinction is the header name for traffic tokens (`e2b-traffic-access-token` versus `cube-traffic-access-token`) and the URL format, which the proxy handles transparently.

### How does CubeProxy handle high-traffic scenarios without overwhelming Redis?

CubeProxy implements a local cache layer using Nginx's shared dictionary `local_cache`. The `get_cache_timeout` function randomizes TTL values to prevent cache stampedes, while still enforcing traffic token validation on cached entries to maintain security.

### What happens if a request targets a paused sandbox?

Before forwarding, [`rewrite_phase.lua`](https://github.com/TencentCloud/CubeSandbox/blob/main/rewrite_phase.lua) calls `sandbox_state.gate(ins_id)`. If the sandbox is paused, this function returns a 503 or 410 status code, preventing the request from reaching the container process.

### How does the proxy distinguish between internal and external traffic?

The proxy compares the client IP (`cube_proxy_host_ip` or `server_addr`) against the sandbox's `HostIP` stored in Redis. Matching IPs trigger a direct rewrite to the internal `SandboxIP`, while non-matching IPs route through the external host's mapped port.