Principle:OpenHands OpenHands Sandbox Creation

Knowledge Sources	OpenHands
Domains	Cloud_Infrastructure, Runtime_Management
Last Updated	2026-02-11 21:00 GMT

Overview

Sandbox Creation is the principle of provisioning isolated cloud sandboxes with container images, workspace directories, and environment variables, following a consistent lifecycle across all supported providers.

Description

When an agent session begins, OpenHands must create an isolated execution environment (a "sandbox") in a cloud provider. Each sandbox is a containerized environment that includes a base image (typically the OpenHands runtime image), a mounted workspace directory, and a set of environment variables needed for agent operation.

OpenHands employs a template method pattern for sandbox creation. The base class ActionExecutionClient defines the high-level lifecycle as a sequence of steps:

1. create -- Provision the sandbox resource with the provider (container, VM, or managed environment).
2. start -- Boot the sandbox and start internal services (e.g., the action execution server).
3. wait_until_alive -- Poll the sandbox's health endpoint until it confirms readiness.

Each provider runtime overrides the creation and startup steps with provider-specific logic while inheriting the shared readiness-check mechanism. This guarantees that regardless of which provider is used, the orchestrator can rely on the same lifecycle contract: after connect() returns, the sandbox is fully operational.

Key configuration elements common to all providers:

• Container image: Specifies the base runtime image (e.g., openhands_runtime_image from sandbox config).
• Workspace directory: The path where agent files are mounted (typically /workspace).
• Environment variables: Injected into the sandbox for session identification, plugin configuration, and user-specific settings.
• Timeout: A maximum wait time (typically 120 seconds) for the sandbox to become alive, enforced via tenacity retry logic.

Usage

Sandbox Creation is triggered immediately after runtime initialization, when the orchestrator calls connect() on the runtime instance. It is the second phase of the runtime lifecycle, following authentication and preceding action execution.

Theoretical Basis

The template method pattern defines the skeleton of sandbox creation in the base class, deferring provider-specific steps to subclasses.

ABSTRACT CLASS ActionExecutionClient:
    method connect():
        CALL _create_sandbox()           # Provider-specific
        CALL _start_action_server()      # Provider-specific (or shared)
        CALL _wait_until_alive()         # Shared: retry with tenacity

    ABSTRACT method _create_sandbox() -> Sandbox
    method _wait_until_alive():
        RETRY with tenacity (timeout=120s, interval=1s):
            response = HTTP GET sandbox_url/alive
            ASSERT response.status == 200

CLASS DaytonaRuntime EXTENDS ActionExecutionClient:
    method _create_sandbox():
        params = CreateSandboxParams(image, env_vars, workspace_dir)
        sandbox = daytona_client.create(params)
        RETURN sandbox

CLASS E2BRuntime EXTENDS ActionExecutionClient:
    method _create_sandbox():
        sandbox = E2BSandbox.create(template, api_key, metadata, timeout)
        RETURN sandbox

CLASS ModalRuntime EXTENDS ActionExecutionClient:
    method _create_sandbox():
        modal_sandbox = modal.Sandbox.create(image, env_vars, mounts, timeout)
        RETURN modal_sandbox

CLASS RunloopRuntime EXTENDS ActionExecutionClient:
    method _create_sandbox():
        devbox = runloop_client.devboxes.create(image, env_vars, entrypoint)
        WAIT for devbox.status == "running"
        RETURN devbox

The invariant across all providers is that after connect() returns successfully, the sandbox is alive, the action server is responsive, and the runtime is ready to execute agent actions.

Related Pages

Implemented By

• Implementation:OpenHands_OpenHands_DaytonaRuntime_Connect