E2B Python SDK

Agent Sandbox is a sandbox service for agentic workloads — reasoning evaluation, training rollouts, managed agents — with secure isolation and flexible deployment. E2B is the sandbox provider behind Manus, and envd is the runtime E2B provides; Agent Sandbox serves the E2B-compatible API, so the official SDK reaches it unchanged.

This page is the SDK side of the platform: how to point the SDK at a cluster, how to get a sandbox out of a warm pool, and what the create call takes. The platform side — environments, pools, autoscaling, quotas — is abx; see the CLI guide, and Concepts is the object model behind both.

Every deployment renders its own copy of this material with the real addresses filled in, and that copy is authoritative for the cluster you are using:

abx envs YOUR_ENV docs --cluster YOUR_CLUSTER

On the console it is the Env Docs panel on the environment's page, key included. This page keeps placeholders where that one has values.

1. Install

uv pip install 'agent-sandbox-e2b[e2b]'

The [e2b] extra pulls in the official e2b package. Two version notes worth knowing: agent-sandbox-e2b >= 0.0.6 is required for public access (older builds do not assemble the gateway path, so sandbox ports do not connect), and the server rejects clients below its minimum supported version with 426 Upgrade Required.

2. Quick start

patch_e2b() must run before from e2b import Sandbox; otherwise the SDK connects to the official E2B service instead of Agent Sandbox.

import os

os.environ["E2B_API_KEY"] = "agbx_..."                              # your API key
os.environ["E2B_API_URL"] = "https://YOUR_GATEWAY/agent-sandbox/api/e2b"
os.environ["E2B_DOMAIN"]  = "YOUR_GATEWAY/agent-sandbox/api/data"   # no scheme
os.environ["E2B_HTTPS"]   = "true"                                  # "false" for a plain-http data plane

from agent_sandbox_e2b import patch_e2b
patch_e2b()

from e2b import Sandbox

sbx = Sandbox.create("YOUR_ENV", timeout=3000, secure=False)
print(sbx.is_running())
sbx.kill()

The same three values can be passed as arguments instead, which take precedence over the environment:

patch_e2b(
    api_url="https://YOUR_GATEWAY/agent-sandbox/api/e2b",
    domain="YOUR_GATEWAY/agent-sandbox/api/data",
    https=True,
)

secure=False skips E2B's signed handshake: Agent Sandbox authenticates with an API key, so it stays False.

3. Access paths

There are three ways in, and they differ only in how much of the network the request crosses. The environment's own documentation names the values for the cluster you are on.

Public is the default and the one to reach for unless you know you are inside. It is the longest path, but it depends on nothing about where the caller runs.

Internal skips the public hop by resolving the gateway host to the cluster's internal IP. For a single machine, add the alias to /etc/hosts:

echo "YOUR_INNER_IP  YOUR_GATEWAY_HOST" | sudo tee -a /etc/hosts

For a workload that is itself a Pod, hostAliases does the same without touching a shared file:

spec:
  hostAliases:
    - ip: "YOUR_INNER_IP"
      hostnames:
        - "YOUR_GATEWAY_HOST"

In-cluster is the shortest path: leave E2B_API_URL, E2B_DOMAIN and E2B_HTTPS unset — patch_e2b() falls back to agentbox-e2b-api.agentbox-system.svc.cluster.local and agentbox-data-plane.agentbox-system.svc.cluster.local — and keep only E2B_API_KEY.

4. What a sandbox comes from: template, env, pool

A sandbox is not built from scratch at create time. The platform keeps a set of pre-warmed Pods, and Sandbox.create() claims one and swaps in your image, which is why it takes seconds rather than minutes.

Create them in the console: Sandbox Envs → new environment (name, template, optional overrides, autoscaling, image pull secrets, network policy), then add pool on the environment (quota, resource mode — instance type × multiplier, or explicit CPU and memory — and replica count). Replicas are the concurrency ceiling: tasks beyond the number of idle Pods queue.

The environment's page shows idle / running / desired per member pool. idle > 0 is the point at which Sandbox.create() returns immediately.

5. Sandbox.create() parameters

The first argument (E2B calls it template) has four spellings here:

The //IMAGE suffix composes with any of them, e.g. "CLUSTER_ID::YOUR_ENV//docker.io/library/ubuntu:24.04".

Other parameters:

Reserved metadata keys:

sbx = Sandbox.create(
    "YOUR_ENV",
    timeout=3000,
    secure=False,
    metadata={
        "agentbox.scitix.ai/scaling-group": "1c16gi",   # only 1c16gi pools
        "agentbox.scitix.ai/startup-timeout": "900",    # large image, give it time
        "run_id": "eval-2026-07-31",                    # ordinary label
    },
)

A scaling group the environment has no pool for fails the create (503) rather than falling back to another shape. That is deliberate: during an evaluation, a size that silently drifts is harder to find than a request that refuses.

6. Cross-cluster

An environment belongs to one cluster; same-named environments in different clusters federate, so the platform can route a create to whichever side has idle Pods.

The third form needs the environment to exist in every participating cluster: in the console, new environment → extend another cluster's environment, pick the existing one, and add member pools on the new side too.

Two prerequisites for cross-cluster scheduling:

1. The image must exist in every region. A sandbox lands where there is capacity, and it has to be able to pull from there — see section 7.
2. Team-to-namespace mapping must match across clusters, or federation cannot pair (namespace, env) and a bare name will not spread. Spell the target out ("other-cluster::YOUR_ENV") when that is the case.

7. Images and regions

Each cluster declares its own region's image registry. When the image you name belongs to another cluster's private registry, the platform rewrites the registry host to this cluster's equivalent, so a sandbox pulls from its own region instead of across the world:

you write:       registry-region-a.example.com/team/swebench:260328
actually pulled: YOUR_REGISTRY_HOST/team/swebench:260328

The rules, in short:

• only the host is rewritten — the path and tag survive, so the same image has to exist under the same path in each region's registry;
• the rewrite happens only between registries of the same type (the platform configuration's type); public registries such as docker.io are never rewritten;
• when no registry of that type exists in this cluster, the image is pulled from the address you wrote — possibly across regions, and possibly slowly.

So before a cross-cluster evaluation, confirm the image has been synced to every region you expect to run in.

8. Common operations

sbx.is_running()

# run commands — as the standard user, or as root
sbx.commands.run("echo hello && python --version")
sbx.commands.run("id", user="root")

# files
sbx.files.write("/tmp/script.py", b"print('hello from AgentBox')\n")
content = sbx.files.read("/tmp/script.py")

# extend the idle timeout
sbx.set_timeout(1800)

# always destroy it: a running sandbox holds a warm Pod
sbx.kill()

9. Troubleshooting