E2B SDK Migration Path for CubeSandbox: Endpoint Configuration Guide

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, 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, 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, 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 demonstrates zero-code-change migration:

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:

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:

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:

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:

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 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:

// 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, 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}