E2B Python SDK

Scitix AgentBox is a sandbox service designed for Agentic scenarios, offering secure isolation and flexible deployment to support various use cases such as reasoning evaluation and training rollouts.E2B is the sandbox provider behind Manus, and envd is the runtime environment provided by E2B. Scitix AgentBox provides compatibility and enhancements for the E2B SDK. This document guides you on how to access Scitix AgentBox resources using the E2B SDK.

By reading this document, we assume you have already completed the sandbox pool pre-warming and API Key application process. To use resources from the sandbox env ${AGBX_ENV_NAME}, first install the E2B SDK and the AgentBox patch package:

uv pip install e2b agent-sandbox-e2b

Quick Start

You must apply the patch before importing Sandbox; otherwise, the SDK will connect to the official E2B service instead of AgentBox:

import os

# Replace with your actual AgentBox API Key
os.environ["E2B_API_KEY"] = "YOUR_API_KEY"

from agent_sandbox_e2b import patch_e2b  # Must be called before importing Sandbox
patch_e2b()

from e2b import Sandbox

# Create a sandbox from an env (ENV_NAME may also be a concrete pool name)
sandbox = Sandbox.create("CLUSTER_ID::ENV_NAME//docker.io/library/ubuntu:22.04", timeout=3000, secure=False)
print(sandbox.is_running())
sandbox.kill()

Cross-Cluster Usage

To access sandbox resources from a different cluster, prefix the templateID with the cluster ID in the format clusterId::name. The name is resolved env-first on the target cluster, so an env name gets you its member-pool selection; a concrete pool name pins one pool:

# Standard mode: use an env in the current cluster
sandbox = Sandbox.create("ENV_NAME", timeout=3000, secure=False)

# Cross-cluster mode: same lookup, pinned to one cluster
sandbox = Sandbox.create("CLUSTER_ID::ENV_NAME", timeout=3000, secure=False)

# Cross-cluster mode: pin one specific member pool
sandbox = Sandbox.create("CLUSTER_ID::POOL_NAME", timeout=3000, secure=False)

Cross-cluster requests are automatically routed by AgentBox, requiring no extra configuration. If you encounter authentication errors, please re-apply for your API Key via the platform.

Sandbox Operations

Once the sandbox is successfully created, you can use the standard E2B SDK operations:

# Check if the sandbox is running (poll until True after creation)
sandbox.is_running()

# Execute commands (as standard user)
sandbox.commands.run("echo 'hello' && python --version")

# Execute commands (as root user)
sandbox.commands.run('id', user='root')

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

# Dynamically extend idle timeout (in seconds)
sandbox.set_timeout(1800)

# Destroy the sandbox (always call this when finished)
sandbox.kill()

For more detailed command documentation, refer to the official E2B documentation.

If you need session features similar to tmux, please refer to the official PTY configuration guide.

The default user for command execution in E2B is a standard user (UID=1001). To switch to root, use the user parameter in sandbox.commands.run("id", user='root') or configure it via PTY session startup parameters.

Parameter Reference

Scitix AgentBox supports two types of timeout controls that can be combined as needed.

Idle Timeout

The timeout parameter controls the idle lifespan of the sandbox (in seconds). If there are no active gRPC/WebSocket/HTTP connections within this period after the sandbox is created, it will be automatically reclaimed.

# Sandbox will be destroyed after 1 hour of inactivity
sandbox = Sandbox.create("POOL_NAME", timeout=3600, secure=False)

During the sandbox session, you can dynamically extend the lifespan using set_timeout:

# Reset remaining timeout to 1800 seconds
sandbox.set_timeout(1800)

Startup Timeout

The Startup Timeout controls the maximum wait time for sandbox creation (in seconds), defaulting to 120s. If creation fails within this time (e.g., due to resource insufficiency), Sandbox.create() will raise an exception.

Set this via the metadata dictionary using the reserved key agentbox.scitix.ai/startup-timeout:

sandbox = Sandbox.create(
    "POOL_NAME",
    timeout=3000,
    secure=False,
    metadata={"agentbox.scitix.ai/startup-timeout": "120"},  # Max 120 seconds to start
)

Custom Images

You can override the pool's default image at creation time using the agentbox.scitix.ai/image reserved key in metadata:

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

Alternatively, use the shorthand poolName//image syntax:

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

Scaling Group

When the target SandboxEnv fronts pools of several sizes (each tagged with a scaling group such as 1c2Gi or 2c4Gi), you can pin a create to one group using the agentbox.scitix.ai/scaling-group reserved key in metadata. The sandbox is then only placed on member pools in that group:

sandbox = Sandbox.create(
    "ENV_NAME",
    secure=False,
    metadata={"agentbox.scitix.ai/scaling-group": "1c2Gi"},  # only 1c2Gi pools
)

This is a hard constraint: if the env has no pool in the requested group the create fails (HTTP 503) rather than falling back to another group. When the group has no idle pod, the create blocks until one becomes available (up to the startup timeout) — and if that group has autoscaling enabled, the request also drives it to scale up. Omit the key to let the scheduler pick any member pool (the default).

Complete Example

sandbox = Sandbox.create(
    "CLUSTER_ID::POOL_NAME//registry.example.com/my-env:v2",
    timeout=3600,           # Idle timeout: 1 hour
    secure=False,
    metadata={
        "agentbox.scitix.ai/startup-timeout": "120",          # Startup timeout: 2 mins
        "agentbox.scitix.ai/scaling-group": "1c2Gi",          # Pin to the 1c2Gi group (optional)
        "my-custom-key": "my-value",                          # Custom user metadata (optional)
    },
)

FAQ

Q: Sandbox.create() hangs for a long time without returning?

The sandbox is waiting for the Pod to become ready (either from the pre-warmed pool or a cold start). It is recommended to set a reasonable startup timeout using agentbox.scitix.ai/startup-timeout (default 120s) to prevent the program from waiting indefinitely.

Q: Sandbox is destroyed unexpectedly?

Check if the timeout is set too short. If there are long intervals without active connections during tasks like training, be sure to call sandbox.set_timeout() before the interval begins to extend the session.