agent-sandbox-e2b

A one-line patch that redirects the E2B Python SDK to a self-hosted Agent Sandbox deployment — no code changes to your existing E2B workflows required.

Agent Sandbox is a Kubernetes-native sandbox service for agentic AI scenarios (reasoning evaluation, training rollouts, code execution). It exposes an E2B-compatible API so you can reuse the E2B SDK while running on your own infrastructure.

Installation

pip install e2b agent-sandbox-e2b

Quick Start

Call patch_e2b() before importing Sandbox. It redirects all SDK requests to your Agent Sandbox cluster.

import os

os.environ["E2B_API_KEY"] = "agbx_your_api_key"

from agent_sandbox_e2b import patch_e2b
patch_e2b()  # zero-argument: uses default in-cluster addresses

from e2b import Sandbox

sandbox = Sandbox.create("POOL_NAME", timeout=3600, secure=False)
sandbox.commands.run("echo hello")
sandbox.kill()

Note: patch_e2b() must be called before any e2b import; otherwise the SDK connects to the official E2B service.

Cross-Cluster Usage

Prefix the pool name with a cluster ID to route requests across clusters:

sandbox = Sandbox.create("CLUSTER_ID::POOL_NAME", timeout=3600, secure=False)

Custom Image Override

Override the pool's default image at creation time:

# Using metadata key
sandbox = Sandbox.create(
    "POOL_NAME",
    timeout=3600,
    secure=False,
    metadata={"agentbox.scitix.ai/image": "registry.example.com/my-env:v2"},
)

# Shorthand syntax
sandbox = Sandbox.create(
    "CLUSTER_ID::POOL_NAME//registry.example.com/my-env:v2",
    timeout=3600,
    secure=False,
)

Configuration

patch_e2b() accepts optional arguments to override the target addresses:

Priority: explicit argument > E2B_HTTPS / E2B_DOMAIN / E2B_API_URL environment variables > built-in defaults. E2B_HTTPS is truthy for 1/true/yes/on (case-insensitive).

# Local debugging via port-forward
patch_e2b(https=False, domain="localhost:9081", api_url="http://localhost:9082")

# Via environment variables (CI/CD)
# export E2B_DOMAIN=agent-sandbox-data-plane.agentbox-system.svc.cluster.local
# export E2B_API_URL=http://agent-sandbox-e2b-api.agentbox-system.svc.cluster.local
# export E2B_API_KEY=agbx_your_key
# export E2B_HTTPS=true   # required when the data plane is behind an HTTPS ingress
patch_e2b()

When using the Helm chart in a namespace other than agentbox-system, pass the installed namespace explicitly:

from agent_sandbox_e2b import patch_e2b

patch_e2b(
    domain="agent-sandbox-data-plane.my-namespace.svc.cluster.local",
    api_url="http://agent-sandbox-e2b-api.my-namespace.svc.cluster.local",
)

API key format (agbx_ keys)

Agent Sandbox issues API keys with an agbx_ prefix. Newer E2B SDKs (>= ~2.24.0) added a client-side key-format check (e2b.api.validate_api_key, pattern \Ae2b_[0-9a-f]+\Z) that rejects any key not starting with e2b_, raising AuthenticationException before a request is ever sent. patch_e2b() automatically neutralizes this local check (the real authentication happens at the Agent Sandbox gateway), so agbx_ keys work across both old and new E2B SDKs with no extra configuration:

os.environ["E2B_API_KEY"] = "agbx_..."   # accepted after patch_e2b()
patch_e2b()

The override is applied inside patch_e2b() and is a no-op on older SDKs that don't have the check. If you ever need the original behavior, do not call patch_e2b() (or re-assign e2b.api.validate_api_key back yourself).

Compatibility

Release builds verify the patch against the latest E2B SDK from PyPI before publishing (verified through E2B SDK 2.28.0). After patching, all standard E2B SDK operations work unchanged:

sandbox.commands.run("python --version")
sandbox.commands.run("id", user="root")
sandbox.files.write("/tmp/hello.py", b"print('hello')\n")
sandbox.files.read("/tmp/hello.py")
sandbox.set_timeout(1800)   # extend idle timeout dynamically
sandbox.kill()

Links

• Agent Sandbox documentation
• E2B SDK reference
• License: Apache-2.0