Skip to main content
These settings are only available in Local GUI. OpenHands Cloud uses managed sandbox environments.
A Runtime is an environment where the OpenHands agent can edit files and run commands. OpenHands supports multiple sandboxing options to fit different security requirements and deployment scenarios.

​
Choosing a Runtime

RuntimeSandbox TypeBest For
Docker RuntimeDocker containerMost users (default, recommended)
Remote RuntimeCloud sandboxParallel workloads, managed infrastructure
Local RuntimeNo sandboxCI/CD pipelines, development, controlled environments
Apptainer RuntimeApptainer containerHPC environments, no root required

​
Run in a Docker Sandbox (Default)

The Docker Runtime creates isolated Docker containers for the agent to execute commands. This is the recommended option for most users as it provides strong isolation while keeping everything local.
The Docker Runtime requires mounting the Docker socket (/var/run/docker.sock) so OpenHands can create sandbox containers. This gives OpenHands access to the Docker daemon. If you prefer not to expose the Docker daemon, consider the Remote Runtime for cloud-based sandboxing, the Apptainer Runtime for daemon-free sandboxing, or the Local Runtime for no sandboxing.
Using the SDK: 
from openhands.workspace import DockerWorkspace

with DockerWorkspace(
    server_image="ghcr.io/openhands/agent-server:latest-python",
    host_port=8000,
) as workspace:
    # Agent server is now running at http://localhost:8000
    result = workspace.execute_command("echo 'Hello from Docker sandbox!'")
    print(result.stdout)

​
Run on the Cloud

The Remote Runtime connects to cloud-based sandbox environments. This is ideal for parallel execution, managed infrastructure, or when you don’t want to run sandboxes locally. Using the SDK with OpenHands Cloud: 
from openhands.workspace import OpenHandsCloudWorkspace

with OpenHandsCloudWorkspace(
    cloud_api_url="https://app.all-hands.dev",
    cloud_api_key="your-api-key",  # Get from app.all-hands.dev
) as workspace:
    # Connected to cloud sandbox
    result = workspace.execute_command("echo 'Hello from cloud sandbox!'")
    print(result.stdout)

​
Run Without Sandboxing

The Local Runtime runs the agent directly on your machine (or inside the OpenHands container) without any sandbox isolation. This is useful for CI/CD pipelines, development workflows, or environments where container-based sandboxing is not available.
Running without sandboxing means the agent has direct access to your filesystem and can execute commands without isolation. Only use this in controlled environments where you understand the security implications.
Starting the agent server locally: 
# Install the SDK
pip install openhands-sdk openhands-agent-server

# Start the agent server (no sandbox)
python -m openhands.agent_server --port 8000 --host 127.0.0.1
Using the SDK: 
from openhands.sdk import Workspace

# Connect to a running agent server
workspace = Workspace(host="http://127.0.0.1:8000")
result = workspace.execute_command("echo 'Hello from local workspace!'")
print(result.stdout)

​
Run in an Apptainer Sandbox

Apptainer (formerly Singularity) is a container runtime designed for HPC environments that can run without root privileges and without exposing a daemon socket. The OpenHands SDK provides an ApptainerWorkspace for sandboxed execution without requiring Docker. Key benefits of Apptainer:
  • No root required: Runs as the invoking user without privilege escalation
  • No daemon: Doesn’t require a background daemon like Docker
  • HPC-friendly: Designed for shared computing environments
  • Secure: Better security model for multi-tenant systems
Using the SDK: 
from openhands.workspace import ApptainerWorkspace

with ApptainerWorkspace(
    server_image="ghcr.io/openhands/agent-server:latest-python",
    host_port=8000,
) as workspace:
    # Agent server is now running at http://localhost:8000
    result = workspace.execute_command("echo 'Hello from Apptainer sandbox!'")
    print(result.stdout)
Apptainer must be installed on your system. See the Apptainer installation guide for instructions.
See the SDK documentation for more details.

​
Available Runtimes

​
Third-Party Runtimes

The following third-party runtimes are available when you install the third_party_runtimes extra: 
pip install openhands-ai[third_party_runtimes]
Note: These third-party runtimes are supported by their respective developers, not by the OpenHands team. For issues specific to these runtimes, please refer to their documentation or contact their support teams.