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

> Discover how CubeSandbox ensures E2B SDK compatibility by translating E2B requests to its JSON schema. Learn about remaining API gaps and integrate seamlessly.

- Repository: [Tencent Cloud/CubeSandbox](https://github.com/TencentCloud/CubeSandbox)
- Tags: deep-dive
- Published: 2026-07-15

---

**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`](https://github.com/TencentCloud/CubeSandbox/blob/main/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`](https://github.com/TencentCloud/CubeSandbox/blob/main/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`](https://github.com/TencentCloud/CubeSandbox/blob/main/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`](https://github.com/TencentCloud/CubeSandbox/blob/main/_pty.py), which forwards calls to the underlying **envd Connect-JSON RPC** while maintaining the E2B API signature. Similarly, [`_commands.py`](https://github.com/TencentCloud/CubeSandbox/blob/main/_commands.py) wraps the command execution API with E2B-compatible signatures.

For command results, [`_models.py`](https://github.com/TencentCloud/CubeSandbox/blob/main/_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.

```python

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

```python

# 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`](https://github.com/TencentCloud/CubeSandbox/blob/main/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`](https://github.com/TencentCloud/CubeSandbox/blob/main/_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`](https://github.com/TencentCloud/CubeSandbox/blob/main/sdk/python/cubesandbox/_policy.py) (`_convert_e2b_per_host_rules`) and [`_models.py`](https://github.com/TencentCloud/CubeSandbox/blob/main/_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`](https://github.com/TencentCloud/CubeSandbox/blob/main/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`](https://github.com/TencentCloud/CubeSandbox/blob/main/sdk/python/cubesandbox/_policy.py) for network rules, [`sdk/python/cubesandbox/_models.py`](https://github.com/TencentCloud/CubeSandbox/blob/main/sdk/python/cubesandbox/_models.py) for response object aliases, and [`sdk/python/cubesandbox/_pty.py`](https://github.com/TencentCloud/CubeSandbox/blob/main/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`](https://github.com/TencentCloud/CubeSandbox/blob/main/tests/e2e/sdk_compat/adapters/e2b_adapter.py).