How E2B SDK Compatibility Works with CubeSandbox and What API Gaps Remain

CubeSandbox implements a drop-in compatibility layer that translates E2B-specific request shapes into its native JSON schema, allowing the standard E2B Python SDK to operate against CubeSandbox backends without code changes.

The TencentCloud/CubeSandbox project provides a Python SDK that mirrors the E2B SDK surface, bridging the two APIs through runtime translation of per-host network rules, authentication headers, and data models. While most core functionality is supported, several convenience methods and advanced networking features remain unimplemented, raising descriptive errors when accessed.

Core Compatibility Mechanics

The E2B SDK compatibility layer functions as an adapter pattern that intercepts E2B-style calls and converts them to CubeSandbox's native wire format. This translation happens transparently during sandbox creation and command execution.

Network Rules Translation

E2B represents network rules as a host-keyed mapping where each hostname maps to a list of transforms. CubeSandbox uses a list of L7 egress rule dataclasses.

In sdk/python/cubesandbox/_policy.py, the function _convert_e2b_per_host_rules parses the E2B dictionary structure, validates each entry, and emits a list of rule dictionaries that CubeSandbox's Rule objects can serialize. The helper _serialize_rule alongside normalizers _normalize_match_dict and _normalize_action_dict convert these dataclass objects or plain dictionaries to the wire format expected by CubeSandbox, translating snake_case keys to camelCase for JSON transmission.

For transform injection specifically, _convert_e2b_transform_to_inject parses E2B's {transform: {headers: {...}}} shape into CubeSandbox Inject instances that populate the Rule.action.inject list.

Environment Variables and Authentication

Environment variable handling requires minimal translation. The field _normalize_envs in sdk/python/cubesandbox/_template.py passes the envs parameter through unchanged, as CubeSandbox already uses the compatible env field name.

Authentication leverages the e2b-traffic-access-token header. When the E2B_API_KEY environment variable is present, client.py automatically adds this header via _add_auth_header, allowing existing E2B authentication patterns to function against CubeSandbox deployments.

PTY and Command Execution Namespaces

The PTY namespace is mirrored in _pty.py, which forwards calls to the underlying envd Connect-JSON RPC while maintaining the E2B API signature. Similarly, _commands.py wraps the command execution API with E2B-compatible signatures.

For command results, _models.py supplies backward-compatible aliases for the json and line fields in CommandResult, ensuring that E2B-style response objects work without modification.

Drop-In SDK Usage

To use the E2B SDK compatibility layer, configure the environment variables and import the standard E2B SDK. The compatibility layer automatically detects E2B-shaped inputs through _is_e2b_per_host_rules and performs the necessary conversions.

# Example: using the E2B SDK against a self-hosted CubeSandbox

import os
from e2b import Sandbox  # E2B SDK import (compatible)

# Set environment variables required by the compatibility layer

os.environ["E2B_API_KEY"] = "<your-e2b-api-key>"
os.environ["CUBE_API_URL"] = "https://your-cubesandbox.example.com"

# Create a sandbox with an E2B-style per-host network rule

sandbox = Sandbox.create(
    network={
        "rules": {
            "api.example.com": [
                {"transform": {"headers": {"X-Secret": "my-token"}}}
            ]
        }
    }
)

# Run a command; the injected header will be applied by CubeSandbox

result = sandbox.exec.run("curl https://api.example.com")
print(result.stdout)

For comparison, the equivalent native CubeSandbox SDK implementation exposes the underlying rule structure explicitly:

# Example: directly using CubeSandbox SDK (equivalent to the above)

import os
from cubesandbox import CubeSandbox

cs = CubeSandbox(api_url=os.getenv("CUBE_API_URL"))
sandbox = cs.sandbox.create(
    network={"rules": [
        {
            "name": "e2b-transform-api.example.com-0",
            "match": {"host": "api.example.com"},
            "action": {"allow": True,
                       "inject": [{"header": "X-Secret", "secret": "my-token"}]},
        }
    ]}
)

Remaining API Gaps and Limitations

While the compatibility layer covers most common operations, several E2B features are not yet implemented. When these gaps are encountered, the adapter raises descriptive RuntimeError messages prompting developers to use CubeAPI directly or file feature requests.

Sandbox Lifecycle Methods

Sandbox.list() is not wrapped in the compatibility layer. The adapter implementation in tests/e2e/sdk_compat/adapters/e2b_adapter.py raises RuntimeError when E2BAdapter.list is called, recommending direct use of the CubeAPI for listing active sandboxes.

TLS Verification and Security

E2B disables TLS verification by default in some configurations, while CubeSandbox enforces it. The adapter only forwards the SSL_CERT_FILE environment variable for certificate configuration; disabling verification must be handled manually by the user and is not supported through the compatibility layer.

Advanced Network Transformations

Currently, only transform.headers is supported in network rule transformations. Keys such as transform.body or other custom extensions are rejected with a clear error indicating unsupported keys. The _convert_e2b_transform_to_inject function explicitly limits translation to header injection only.

File System Convenience Methods

CubeSandbox's file API is lower-level than E2B's, and the adapter maps only a subset of functionality. While read, write, and write_file are supported, methods such as push or pull are not yet emulated. Users requiring these operations must use the native CubeSandbox file API.

PTY Event Handling

The PTY wrapper in _pty.py forwards exit codes but does not expose all PTY-specific events. Operations such as resize and signal handling are not currently implemented in the compatibility layer, limiting advanced terminal management capabilities.

Summary

• CubeSandbox provides drop-in E2B SDK compatibility by translating E2B request shapes into native L7 egress rules and camelCase JSON.
• The compatibility layer handles authentication via the e2b-traffic-access-token header and normalizes environment variables automatically.
• Key translation functions reside in sdk/python/cubesandbox/_policy.py (_convert_e2b_per_host_rules) and _models.py (field aliases).
• Remaining gaps include Sandbox.list(), TLS verification toggles, transform.body injection, file push/pull methods, and PTY resize/signal events.
• When unsupported features are accessed, the adapter raises RuntimeError with guidance to use CubeAPI directly.

Frequently Asked Questions

Can I use the standard E2B Python SDK with CubeSandbox?

Yes. After setting E2B_API_KEY and CUBE_API_URL environment variables, importing from e2b import Sandbox will use CubeSandbox's compatibility layer automatically. The layer translates E2B-specific constructs like per-host network rules into CubeSandbox's native list-based L7 egress rules without requiring code changes.

What happens when I call an unsupported E2B method?

The adapter raises a descriptive RuntimeError with a message indicating the feature is not implemented and suggesting alternatives. For example, calling Sandbox.list() returns an error recommending direct CubeAPI usage, while attempting to use unsupported transform keys like transform.body results in an unsupported keys error.

Do I need to modify my existing E2B code to run on CubeSandbox?

No modifications are required for supported features. The compatibility layer in sdk/python/cubesandbox/_policy.py automatically detects E2B-shaped inputs using _is_e2b_per_host_rules and converts them to CubeSandbox's expected format. However, you may need to adjust code that relies on unsupported features like file push/pull methods or PTY signal handling.

Where is the compatibility layer implemented in the source code?

The core translation logic resides in sdk/python/cubesandbox/_policy.py for network rules, sdk/python/cubesandbox/_models.py for response object aliases, and sdk/python/cubesandbox/_pty.py for PTY namespace mirroring. The adapter pattern implementation and gap documentation can be found in tests/e2e/sdk_compat/adapters/e2b_adapter.py.

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