Run E2B code on Spaces

Point the unmodified E2B Python or TypeScript SDK at Cua: sandboxes become Spaces on your own machines. What maps, what answers with E2B's own error, and how it is tested.

The E2B SDKs (e2b for Python, sync and async, e2b for TypeScript, e2b-code-interpreter; 2.42.0, 2.56.0 and the latest release) run against a local Cua gateway with no code change. Every sandbox is a Space on your machines, your pool or your BYOC clouds.

cua run --compat e2b -- python agent.py

cua run --compat e2b starts the gateway for the life of the job and sets E2B_API_URL, E2B_API_KEY, E2B_DOMAIN, E2B_SANDBOX_URL and SSL_CERT_FILE (and NODE_EXTRA_CA_CERTS for Node). For a long-running gateway use cua compat serve --provider e2b, then eval "$(cua compat env --provider e2b)".

from e2b import Sandbox
 
with Sandbox.create(metadata={"cua.kind": "vm"}) as sbx:
    print(sbx.commands.run("uname -a").stdout)

With no flags the sandboxes run where every Cua create runs by default (this machine, or its overflow when a cloud is linked), as a VM where the machine has KVM or Hypervisor.framework and as a container where it does not, at E2B's default size (2 vCPU, 2 GiB). The first create boots one base sandbox for that shape and every create after it (concurrent ones included) forks it, so creates take about a second.

Metadata places a sandbox: cua.on (local, host:<machine>, a pool, a BYOC cloud), cua.kind (vm, container, microvm), cua.cpus, cua.memory_mb. Forks, snapshots and pauses are copy-on-write.

What is covered#

Every public method of both SDKs is either implemented or answers with E2B's own error and a reason; the matrix, with the case or test that exercises each row, is generated from the SDK packages at libs/cua/crates/cua-compat/maps/e2b-coverage.md, and a method that appears in a new SDK release fails the weekly drift job until it is mapped.

Sandboxes: create (templates, snapshots, metadata, env, timeout, lifecycle, auto-resume, network policy), connect, list with filters and pages, get info and metrics, set timeout, pause, resume, snapshots, kill; kill, pause and resume are idempotent as on E2B.
Commands: run, background processes, connect, list, signals, stdin streaming, PTYs, user, working directory and environment, exit codes and error shapes as Go reports them.
Files: read and write (text, bytes, streams, large files), lists, metadata, symlinks, permissions, rename, remove, watch, signed upload and download URLs.
Network: allow_out and deny_out with addresses and CIDR blocks (allow wins), update_network, traffic access tokens, get_host URLs.
Templates: Template.build boots a Cua Linux image, applies the steps and takes a memory checkpoint; tags, aliases, list, delete. Secrets: create, update, list, delete.
Code interpreter: e2b-code-interpreter runs against the code-interpreter-v1 template with contexts, streaming output, results and errors for Python and bash.

Where Cua differs, and why#

E2B	On Cua
Rewriting outbound requests (`network.rules`, egress proxy, host masking, HTTPS ports), `mcp=`, `iam=`	Answers with E2B's 400 naming the field: these need hosted services or an inspecting proxy that Cua Spaces do not have. Address and CIDR rules are enforced in the guest routing table.
Domain names in `allow_out` / `deny_out`	Refused with a reason: rules are addresses and CIDR blocks.
Volumes	Answers with E2B's 403 `use of volumes is not enabled`. Use Cua Volume.
Other OCI base images in a template	The build fails with E2B's build error: Cua Spaces boot images that carry cua-spacesd (the default Linux image, or a Cua image reference).
Code interpreter kernels	Python and bash. Other languages answer 400 naming the available ones.
`allow_internet_access=False`	No network at all, which is stricter than E2B (it still lets raw TCP connect).
Hardware	The VM is a Cua Space of the size you configure, not a 512 MB x86_64 Firecracker.

How it is tested#

The same cases run through the Python SDK (2.42.0, 2.56.0, latest) and the TypeScript SDK, over mock Spaces on every pull request and on real Spaces nightly, and their observations are compared with goldens recorded from the real E2B. A weekly job runs the latest SDK releases and fails on a changed signature. Wire translation is covered by property tests, and a nightly guard fails when the gateway's own overhead grows by more than 1.5x its recorded baseline.