E2B

e2b is the official Python SDK for E2B, an open-source infrastructure for running AI-generated code in secure, isolated cloud sandboxes. It gives agents and AI applications short- or long-lived Linux environments with filesystem access, command execution, PTY support, and outbound networking - the same tools a human developer would use, safely walled off from the host infrastructure.

Beyond spinning up a bare sandbox, the SDK exposes Volumes for persistent storage across sandbox lifecycles, Templates for building and versioning custom sandbox images, and Secrets for injecting credentials without hardcoding them. Every resource class ships in matching sync and async variants, and a newer E2B client class lets callers bind distinct API keys or domains to isolated client instances instead of relying on a single set of environment variables.

What You Get

• A Sandbox class (plus AsyncSandbox) for creating, listing, and killing cloud sandboxes with configurable timeouts.
• Filesystem, command, and PTY modules (sandbox.files, sandbox.commands, sandbox.pty) for interacting with the running environment.
• Template/AsyncTemplate classes for building custom, versioned sandbox images with configurable ready-checks.
• Volume/AsyncVolume classes for durable storage attached to sandboxes.
• Secret/AsyncSecret classes for injecting credentials into sandboxes without hardcoding them.
• An E2B client class for binding explicit API keys or domains instead of relying on process-wide environment variables.

Common Use Cases

• Running AI-agent-generated code safely, isolated from the host machine.
• Powering code-interpreter features in AI chat products (pairs with the separate e2b-code-interpreter package).
• Building reproducible, versioned sandbox templates for repeatable agent tasks.
• Isolating multiple tenants or API keys within a single backend process via the E2B client.

Under The Hood

Architecture The package structures around a central SandboxApi base class extended by separate sync (sandbox_sync/main.py) and async (sandbox_async/main.py) sandbox implementations that share common configuration and exception layers (connection_config.py, exceptions.py); parallel module trees for filesystem, commands, pty, and git operations under sandbox_sync/ and sandbox_async/ mirror each other to keep the sync and async APIs at parity. A generated OpenAPI client (api/client_sync, api/client_async) plus a separate envd/ layer (wrapping the sandbox’s in-VM daemon over Connect-RPC) form two distinct communication tiers - control-plane calls to the E2B API and RPC calls into the running sandbox. The newer E2B client class (client.py) binds explicit ApiParams into per-client bound subclasses of Sandbox, Volume, Template, and Secret via a dynamic type() call, allowing multiple isolated client instances instead of a single environment-variable-configured global. Changing the core ConnectionConfig/ApiParams abstraction would ripple through every resource module since all of them inherit connection and auth handling from it.

Tech Stack Built for Python 3.10+ using the uv_build backend. Runtime dependencies include httpx (with HTTP/2 via h2) for REST calls to the E2B control plane, connectrpc and protobuf-py for RPC calls into the sandbox’s envd daemon, attrs for typed data classes, packaging for version comparisons, dockerfile-parse for template Dockerfile parsing, rich for terminal output, and wcmatch for filesystem-watch globbing. Dev tooling covers pytest with pytest-xdist, pytest-asyncio, pytest-dotenv, and pytest-timeout for the test suite, ruff for linting and formatting, and ty (Astral’s type checker) for static typing. A dedicated codegen dependency group regenerates the OpenAPI and Connect-RPC clients from the platform’s shared API spec, keeping the generated layer in sync with the service.

Code Quality The test suite splits into sync/, async/, and shared/ fixture directories with dedicated files per concern - transport, codec, interceptors, retries, and timeout behavior of the envd RPC layer each get their own test file, alongside coverage for connection config, API keys, and the new E2B client binding. A dedicated GitHub Actions workflow runs the suite on every change. Exceptions are typed and hierarchical, all deriving from SandboxException rather than bare Exception raises, and public classes and methods carry docstrings including explicit deprecation notices where relevant (e.g. the legacy Sandbox() constructor).

API Design The entrypoint is deliberately minimal: from e2b import Sandbox; with Sandbox.create() as sandbox: sandbox.commands.run(...), using a context manager for automatic cleanup. Sync and async APIs are near-identical in shape (AsyncSandbox mirrors Sandbox method-for-method), and naming stays consistent across resources (Sandbox/AsyncSandbox, Volume/AsyncVolume, Template/AsyncTemplate, Secret/AsyncSecret). The newer E2B client class addresses a concrete pain point - needing several API keys or domains active in one process - without disturbing the simpler top-level, environment-variable-configured exports most users start with.