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

> Discover how the CubeSandbox Go SDK ensures E2B SDK drop-in compatibility through internal environment variable mapping and config normalization for seamless control-plane API integration.

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

---

**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`](https://github.com/TencentCloud/CubeSandbox/blob/main/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`](https://github.com/TencentCloud/CubeSandbox/blob/main/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.

```go
// 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`](https://github.com/TencentCloud/CubeSandbox/blob/main/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`](https://github.com/TencentCloud/CubeSandbox/blob/main/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`](https://github.com/TencentCloud/CubeSandbox/blob/main/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`](https://github.com/TencentCloud/CubeSandbox/blob/main/CubeAPI/examples/go/client.go) (lines 31-39) illustrates practical usage of the mapped environment variables in real-world scenarios.

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

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

```

Or the legacy format:

```bash
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`](https://github.com/TencentCloud/CubeSandbox/blob/main/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`](https://github.com/TencentCloud/CubeSandbox/blob/main/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`](https://github.com/TencentCloud/CubeSandbox/blob/main/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`](https://github.com/TencentCloud/CubeSandbox/blob/main/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`](https://github.com/TencentCloud/CubeSandbox/blob/main/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`](https://github.com/TencentCloud/CubeSandbox/blob/main/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.