# E2B SDK Migration Path for CubeSandbox: Endpoint Configuration Guide

> Easily migrate the E2B SDK for CubeSandbox compatibility. Learn how to swap endpoints with simple environment variable changes, no code modifications needed. Configure your API URL and template ID now.

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

---

**Migrating the E2B SDK to CubeSandbox requires only environment variable changes—no code modifications—by setting `E2B_API_URL` to your Cube API endpoint and providing a `CUBE_TEMPLATE_ID`.**

The TencentCloud/CubeSandbox project implements the exact same HTTP API as the public E2B SaaS service, enabling a seamless E2B SDK migration path for CubeSandbox deployments. This compatibility means existing applications using E2B client libraries can switch to self-hosted CubeSandbox instances purely through configuration changes.

## How CubeSandbox Maintains E2B API Compatibility

CubeSandbox's control-plane exposes identical JSON RPC endpoints to the E2B service, accepting requests on paths like `/v1/sandbox/create` and `/v1/sandbox/exec`. Because the request shapes match exactly, the E2B SDK communicates with CubeSandbox without requiring protocol modifications.

According to the source code in [`sdk/go/config.go`](https://github.com/TencentCloud/CubeSandbox/blob/main/sdk/go/config.go), the SDK implements environment variable precedence logic that prefers `CUBE_API_URL` but falls back to `E2B_API_URL`. This design allows existing codebases to migrate by simply exporting the standard E2B environment variable, which the SDK reads at runtime to determine the target endpoint.

## Required Environment Variables

The migration requires three specific environment variables to route traffic and authenticate requests.

### E2B_API_URL (or CUBE_API_URL)

Set this variable to your Cube API server address, typically `http://<cube-host>:3000`. The SDK uses this value as the base URL for all sandbox operations. As implemented in [`sdk/go/config.go`](https://github.com/TencentCloud/CubeSandbox/blob/main/sdk/go/config.go), the configuration loader checks for `CUBE_API_URL` first, then falls back to `E2B_API_URL` using the `firstEnv` helper function.

### CUBE_TEMPLATE_ID

Unlike the E2B SaaS service, CubeSandbox requires an explicit template identifier to determine which sandbox image to instantiate. Export this variable or pass it via the `template` field in `E2BSandboxClientOptions`. This value corresponds to the template created via `cubemastercli template create-from-image`.

### E2B_API_KEY (Optional)

If your CubeSandbox deployment requires authentication, export the same `E2B_API_KEY` variable used for the E2B SaaS service. The SDK treats this credential identically regardless of which endpoint it targets.

## Step-by-Step Migration Configuration

Follow these steps to redirect your existing E2B SDK code to a CubeSandbox instance.

1. **Export the endpoint URL**: Set `E2B_API_URL="http://<cube-host>:3000"` in your environment or `.env` file.
2. **Set the template ID**: Export `CUBE_TEMPLATE_ID="your-template-id"` to specify which container image CubeSandbox should provision.
3. **Initialize the client**: Instantiate your E2B client normally—the SDK automatically reads the environment variables without code changes.

Referencing the integration guide at [`examples/openai-agents-example/openai-agents-sandbox-cube-integration.md`](https://github.com/TencentCloud/CubeSandbox/blob/main/examples/openai-agents-example/openai-agents-sandbox-cube-integration.md), these three steps constitute the complete migration for both Python and Go implementations.

## Implementation Examples

### Python (OpenAI Agents SDK)

The Python example in [`examples/openai-agents-example/simple_demo.py`](https://github.com/TencentCloud/CubeSandbox/blob/main/examples/openai-agents-example/simple_demo.py) demonstrates zero-code-change migration:

```python
import os
from agents.extensions.sandbox import E2BSandboxClient, E2BSandboxClientOptions

# Point to CubeSandbox endpoint

os.environ["E2B_API_URL"] = "http://<cube-host>:3000"
os.environ["CUBE_TEMPLATE_ID"] = "your-template-id"

# Initialize client exactly as with E2B SaaS

client = E2BSandboxClient(
    options=E2BSandboxClientOptions(
        template=os.getenv("CUBE_TEMPLATE_ID"),
    )
)

```

### Go SDK

The Go implementation uses `NewConfigFromEnv()` to load configuration from environment variables, as defined in [`sdk/go/config.go`](https://github.com/TencentCloud/CubeSandbox/blob/main/sdk/go/config.go):

```go
package main

import (
    "context"
    "os"
    "github.com/tencentyun/cubesandbox/sdk/go"
)

func main() {
    // Load config: checks CUBE_API_URL then E2B_API_URL
    cfg := sdk.NewConfigFromEnv()
    client := sdk.NewClient(cfg)

    // Create sandbox using template ID from environment
    sandbox, err := client.CreateSandbox(context.Background(),
        sdk.CreateSandboxRequest{
            TemplateID: os.Getenv("CUBE_TEMPLATE_ID"),
        })
    // Handle error and use sandbox...
    _ = err
    _ = sandbox
}

```

### Bash Environment Setup

Create a `.env` file based on `examples/openai-agents-example/.env.example`:

```bash
E2B_API_URL="http://127.0.0.1:3000"
E2B_API_KEY="your-key-if-required"
CUBE_TEMPLATE_ID="e2b-code-interpreter-2"

```

Load the variables before execution:

```bash
source .env
python your_script.py

```

## Creating the Required Template

Before running the migrated SDK, you must create a template using the CubeMaster CLI to obtain the `CUBE_TEMPLATE_ID` value:

```bash
cubemastercli template create-from-image \
  --image cube-sandbox-image.tencentcloudcr.com/demo/e2b-code-interpreter:v1.1-data \
  --expose-port 49983 --expose-port 49999 \
  --probe 49983

```

This command registers the container image with CubeSandbox and returns the template ID needed for the `CUBE_TEMPLATE_ID` environment variable.

## Understanding the Configuration Logic

The [`sdk/go/config.go`](https://github.com/TencentCloud/CubeSandbox/blob/main/sdk/go/config.go) file implements the compatibility layer that enables this migration. The configuration loader uses a `firstEnv` helper that checks for Cube-specific variables before falling back to E2B equivalents:

```go
// Conceptual representation from config.go
apiURL := firstEnv("CUBE_API_URL", "E2B_API_URL")
apiKey := firstEnv("CUBE_API_KEY", "E2B_API_KEY")

```

This precedence ensures that CubeSandbox deployments can use distinct variables if needed, while standard E2B variables work transparently for migration scenarios.

## Summary

- CubeSandbox exposes the same HTTP API endpoints as E2B SaaS, making migration purely a configuration task.
- Set `E2B_API_URL` to your Cube API address (e.g., `http://<cube-host>:3000`) to redirect SDK traffic.
- Provide `CUBE_TEMPLATE_ID` to specify which sandbox image CubeSandbox should instantiate.
- No source code modifications are required; the SDK reads environment variables at runtime via `NewConfigFromEnv()`.
- Authentication uses the standard `E2B_API_KEY` variable if your CubeSandbox instance requires it.

## Frequently Asked Questions

### Do I need to modify my application code to use CubeSandbox?

No. The E2B SDK reads endpoint configuration from environment variables at runtime. As long as you set `E2B_API_URL` and `CUBE_TEMPLATE_ID`, existing code using `E2BSandboxClient` or `NewClient()` functions exactly as it does with the E2B SaaS service.

### Why does CubeSandbox require a template ID when E2B SaaS does not?

CubeSandbox is self-hosted infrastructure that needs to know which container image to provision for each sandbox. The template ID, created via `cubemastercli template create-from-image`, maps to a specific Docker image and configuration. This replaces the managed template system in the E2B cloud service.

### Can I use both E2B SaaS and CubeSandbox in the same application?

Yes, but not simultaneously in the same process using global environment variables. You would need to instantiate separate clients with explicit configuration objects rather than relying on `NewConfigFromEnv()`, or run different services/processes with different environment configurations.

### What happens if I set both CUBE_API_URL and E2B_API_URL?

According to the logic in [`sdk/go/config.go`](https://github.com/TencentCloud/CubeSandbox/blob/main/sdk/go/config.go), the SDK checks `CUBE_API_URL` first. If that variable is set, it takes precedence over `E2B_API_URL`. This allows you to explicitly target CubeSandbox while keeping E2B fallback values in your environment.