CubeSandbox Go SDK: E2B SDK Drop-In Compatibility and API Endpoint Mapping

The CubeSandbox Go SDK achieves seamless E2B SDK drop-in compatibility by internally mapping legacy E2B_* environment variables to newer CUBE_* equivalents and normalizing configuration data before any request reaches the control-plane API.

The TencentCloud/CubeSandbox repository provides a Go SDK engineered as a transparent replacement for the original E2B SDK. Through strategic environment variable precedence and configuration normalization, existing E2B deployments continue functioning without code changes while the SDK simultaneously supports modern CUBE_* naming conventions.

Environment Variable Precedence for Drop-In Compatibility

The SDK implements a fallback mechanism that prioritizes new variable names while maintaining backward compatibility with legacy E2B configurations.

The NewConfigFromEnv Entry Point

In sdk/go/config.go, the NewConfigFromEnv function (lines 34-42) constructs a Config struct by reading environment variables with a specific precedence hierarchy. The implementation first attempts to read the newer CUBE_* variables, then falls back to their E2B_* counterparts if the primary values are unset. This architecture provides existing E2B-style deployments with a transparent upgrade path.

The firstEnv Helper Implementation

Underpinning this precedence logic is the firstEnv utility function (lines 87-93 in sdk/go/config.go). This helper iterates over a slice of environment variable names and returns the first non-empty value encountered. By supplying ordered lists such as ["CUBE_API_URL", "E2B_API_URL"], the SDK elegantly implements variable fallback without complex conditional logic.

// config.go lines 87-93
func firstEnv(names ...string) string {
    for _, n := range names {
        if v := os.Getenv(n); v != "" {
            return v
        }
    }
    return ""
}

Configuration Normalization and API Endpoint Handling

After environment variable resolution, the SDK normalizes raw values to ensure consistent behavior regardless of which variable set was used.

The normalizeConfig Function

The normalizeConfig function (lines 53-71 in sdk/go/config.go) performs critical sanitization steps: trimming whitespace from string values, removing trailing slashes from API URLs, and supplying sensible defaults. When configuration values are absent, the SDK injects standard defaults including http://127.0.0.1:3000 for the API endpoint, cube.app for the domain, and appropriate timeout durations.

Proxy Scheme Detection

The SDK includes the normalizeProxyScheme helper (lines 75-84 in sdk/go/config.go) to intelligently determine whether connections should use http or https. This function analyzes the supplied URL scheme and automatically upgrades to HTTPS when the target port is 443, ensuring secure communication without explicit configuration.

Real-World Implementation Examples

The compatibility layer extends beyond the core SDK into command-line tools and example implementations. The cube-bench CLI tool in examples/cube-bench/main.go (lines 99-104 and 140-143) demonstrates how applications can read E2B_API_URL and E2B_API_KEY directly while relying on the same underlying Config logic. Similarly, the example client in CubeAPI/examples/go/client.go (lines 31-39) illustrates practical usage of the mapped environment variables in real-world scenarios.

package main

import (
    "fmt"
    "github.com/TencentCloud/CubeSandbox/sdk/go"
)

func main() {
    // Automatically resolves CUBE_* or E2B_* variables
    cfg := cubesandbox.NewConfigFromEnv()
    
    fmt.Printf("API endpoint: %s\n", cfg.APIURL)
    fmt.Printf("API key: %s\n", cfg.APIKey)
}

Whether the environment contains:

export CUBE_API_URL="http://my-cube:3000"
export CUBE_API_KEY="my-secret"

Or the legacy format:

export E2B_API_URL="http://my-cube:3000"
export E2B_API_KEY="my-secret"

The SDK resolves identical configuration values through the firstEnv precedence logic.

Testing E2B Backward Compatibility

The test suite in sdk/go/sdk_test.go explicitly validates the drop-in compatibility behavior. Lines 44-45 and 822-823 demonstrate test cases that set E2B_API_URL and E2B_API_KEY while ensuring CUBE_* variables are absent, verifying that NewConfigFromEnv correctly picks up the legacy variables. This test coverage guarantees that backward compatibility remains intact across SDK updates.

Summary

• Environment variable precedence: The SDK checks CUBE_* variables first, falling back to E2B_* equivalents via the firstEnv helper in sdk/go/config.go.
• Configuration normalization: The normalizeConfig function sanitizes input values and supplies defaults like http://127.0.0.1:3000 and cube.app.
• Automatic protocol detection: The normalizeProxyScheme helper intelligently selects HTTP or HTTPS based on port and scheme analysis.
• Validated compatibility: Unit tests in sdk/go/sdk_test.go explicitly verify that legacy E2B environment variables function correctly when modern CUBE variables are undefined.
• Production examples: Tools like cube-bench and the example Go client demonstrate the mapping works end-to-end in real applications.

Frequently Asked Questions

How does CubeSandbox maintain E2B SDK compatibility?

The SDK maintains compatibility through environment variable mapping in sdk/go/config.go. The NewConfigFromEnv function uses the firstEnv helper to check for CUBE_API_URL and CUBE_API_KEY first, then automatically falls back to E2B_API_URL and E2B_API_KEY if the newer variables are unset. This allows existing scripts and deployments to continue functioning without modification while supporting the new CUBE naming convention.

What environment variables does the CubeSandbox SDK support?

The SDK supports both modern and legacy variable sets. The primary variables are CUBE_API_URL, CUBE_API_KEY, and CUBE_DOMAIN, with fallbacks to E2B_API_URL, E2B_API_KEY, and E2B_DOMAIN. This dual-naming strategy ensures that existing E2B configurations work immediately while new deployments can adopt the clearer CUBE-prefixed variables.

How does the SDK handle API URL normalization?

After resolving environment variables, the normalizeConfig function in sdk/go/config.go (lines 53-71) sanitizes the API URL by removing trailing slashes and whitespace. The normalizeProxyScheme helper (lines 75-84) additionally ensures the correct HTTP scheme is applied, defaulting to HTTPS when port 443 is specified. This guarantees consistent endpoint formatting regardless of input variability.

Where is the E2B compatibility logic tested?

The compatibility layer is validated in sdk/go/sdk_test.go, specifically around lines 44-45 and 822-823. These test cases explicitly set legacy E2B_API_URL and E2B_API_KEY environment variables while ensuring CUBE equivalents are absent, verifying that NewConfigFromEnv correctly resolves the legacy values. Integration tests further ensure the SDK contacts the correct endpoints under both naming schemes.

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