Implementation:OpenHands OpenHands E2BBox Execute
| Knowledge Sources | |
|---|---|
| Domains | Cloud_Infrastructure, Runtime_Management |
| Last Updated | 2026-02-11 21:00 GMT |
Overview
Concrete tool for executing shell commands inside an E2B cloud sandbox, provided by the OpenHands third-party runtime layer.
Description
E2BBox.execute runs a shell command inside an E2B sandbox using the E2B SDK's native process execution API. Unlike the Daytona, Modal, and Runloop runtimes (which dispatch commands to an action execution server via HTTP), E2B uses direct SDK calls to execute commands. The E2BBox class wraps the E2B sandbox's process API, providing a simplified interface that returns exit codes and combined stdout/stderr output.
The E2BBox class is initialized with a SandboxConfig and an optional sandbox_id for attaching to an existing sandbox. The execute() method starts a process inside the sandbox, waits for it to complete (with an optional timeout), and returns the result as a tuple of (exit_code, output_string).
At the runtime level, E2BRuntime uses E2BBox.execute in two higher-level methods:
- E2BRuntime.run() (e2b_runtime.py:L179-193) executes shell commands by calling self.sandbox.execute() and wrapping the result in a CmdOutputObservation.
- E2BRuntime.run_ipython() (e2b_runtime.py:L195-221) executes IPython code by writing it to a temporary file and running it through the IPython kernel inside the sandbox.
Note: The Daytona, Modal, and Runloop runtimes do not use E2BBox. They inherit run() and run_ipython() from ActionExecutionClient, which sends HTTP requests to the action execution server running inside their respective sandboxes.
Usage
Use E2BBox.execute when you need to run a shell command inside an E2B sandbox and retrieve the exit code and output. In practice, this is called indirectly through E2BRuntime.run() or E2BRuntime.run_ipython() during agent action execution.
Code Reference
Source Location
- Repository: OpenHands
- File:
third_party/runtime/impl/e2b/sandbox.py - Lines: L92-110
Signature
class E2BBox:
def __init__(
self,
config: SandboxConfig,
sandbox_id: str | None = None,
):
...
def execute(
self,
cmd: str,
timeout: int | None = None,
) -> tuple[int, str]:
Import
from third_party.runtime.impl.e2b.sandbox import E2BBox
I/O Contract
Inputs
| Name | Type | Required | Description |
|---|---|---|---|
| cmd | str | Yes | The shell command string to execute inside the E2B sandbox |
| timeout | None | No | Maximum execution time in seconds. If None, uses the sandbox's default timeout. |
Outputs
| Name | Type | Description |
|---|---|---|
| exit_code | int | The process exit code (0 indicates success, non-zero indicates failure) |
| output | str | Combined stdout and stderr output from the executed command |
Usage Examples
Basic Usage
from third_party.runtime.impl.e2b.sandbox import E2BBox
from openhands.core.config import SandboxConfig
# Create an E2BBox instance:
sandbox_config = SandboxConfig(
e2b_api_key="your-api-key",
timeout=300,
)
box = E2BBox(config=sandbox_config)
# Execute a shell command:
exit_code, output = box.execute("ls -la /workspace", timeout=30)
print(f"Exit code: {exit_code}")
print(f"Output:\n{output}")
Through E2BRuntime
from third_party.runtime.impl.e2b.e2b_runtime import E2BRuntime
# After connecting the runtime:
runtime = E2BRuntime(config=openhands_config, event_stream=event_stream)
await runtime.connect()
# E2BRuntime.run() internally calls E2BBox.execute():
from openhands.events.action import CmdRunAction
action = CmdRunAction(command="python --version")
observation = await runtime.run(action)
print(observation.content) # e.g., "Python 3.11.6"
print(observation.exit_code) # 0