OpenHands · neubig · Jan 1, 2026 · Jan 1, 2026 · Jan 1, 2026 · Jan 1, 2026
@@ -138,6 +138,11 @@ docker run -it --rm --pull=always \
 
 > **Note**: If you used OpenHands before version 0.44, you may want to run `mv ~/.openhands-state ~/.openhands` to migrate your conversation history to the new location.
 
+<Note>
+**Alternative Sandbox Options**: The default setup uses Docker containers for sandboxing. For other options
+(run on the cloud, run without sandboxing, etc.), see the [Runtimes documentation](/openhands/usage/runtimes/overview).
+</Note>
+
 You'll find OpenHands running at http://localhost:3000!
 
 ### Setup

@@ -1,8 +1,7 @@
 ---
-title: Local Runtime
-description: The Local Runtime allows the OpenHands agent to execute actions directly on your local machine without
-  using Docker. This runtime is primarily intended for controlled environments like CI pipelines or testing scenarios
-  where Docker is not available.
+title: Local Runtime (No Sandbox)
+description: The Local Runtime allows the OpenHands agent to execute actions directly on your machine without
+  sandbox isolation. This runtime is intended for controlled environments like CI pipelines or development scenarios.
 ---
 
 <Warning>
@@ -15,10 +14,15 @@ files on your machine. Only use this runtime in controlled environments or when
 Before using the Local Runtime, ensure that:
 
 1. You can run OpenHands using the [Development workflow](https://github.com/OpenHands/OpenHands/blob/main/Development.md).
-2. For Linux and Mac, tmux is available on your system.
+2. For Linux and Mac, tmux must be installed and available on your system.
 3. For Windows, PowerShell is available on your system.
     - Only [CLI mode](/openhands/usage/run-openhands/cli-mode) and [headless mode](/openhands/usage/run-openhands/headless-mode) are supported in Windows with Local Runtime.
 
+<Note>
+The standard OpenHands Docker image does not include tmux. If you want to use Local Runtime inside Docker,
+see the [Running Without Sandbox Inside Docker](#running-without-sandbox-inside-docker) section below.
+</Note>
+
 ## Configuration
 
 To use the Local Runtime, besides required configurations like the LLM provider, model and API key, you'll need to set
@@ -67,6 +71,38 @@ poetry run python -m openhands.core.main -t "write a bash script that prints hi"
 
 The Local Runtime is particularly useful for:
 
-- CI/CD pipelines where Docker is not available.
+- CI/CD pipelines where container-based sandboxing is not available.
 - Testing and development of OpenHands itself.
 - Environments where container usage is restricted (e.g. native Windows).
+- Running OpenHands inside a container without nested sandboxing (see below).
+
+## Running Without Sandbox Inside Docker
+
+<Warning>
+The standard OpenHands Docker image (`docker.openhands.dev/openhands/openhands`) does not include tmux, which is required
+for the Local Runtime. To use Local Runtime inside Docker, you need to use the
+[Development workflow](https://github.com/OpenHands/OpenHands/blob/main/Development.md) or build a custom image with tmux installed.
+</Warning>
+
+If you have a Docker image with tmux installed, you can run OpenHands without nested sandboxing:
+
+```bash
+docker run -it --rm \
+    -e RUNTIME=local \
+    -e LOG_ALL_EVENTS=true \
+    -v ~/.openhands:/.openhands \
+    -v /path/to/your/workspace:/workspace \
+    -p 3000:3000 \
+    --name openhands-app \
+    your-custom-openhands-image:tag
+```
+
+Key points:
+- `-e RUNTIME=local`: Runs without sandbox isolation
+- Mount your workspace directly with `-v /path/to/your/workspace:/workspace`
+- The agent executes commands directly inside the container
+
+<Note>
+When using Local Runtime inside Docker, the agent operates within the container's filesystem. Any files you want the
+agent to access should be mounted into the container.
+</Note>
@@ -1,28 +1,140 @@
 ---
 title: Overview
-description: This section is for users that would like to use a runtime other than Docker for OpenHands.
+description: This section covers the different sandbox and runtime options available for OpenHands.
 ---
 
 <Note>
   These settings are only available in [Local GUI](/openhands/usage/run-openhands/local-setup). OpenHands Cloud uses managed sandbox environments.
 </Note>
 
 A Runtime is an environment where the OpenHands agent can edit files and run
-commands.
+commands. OpenHands supports multiple sandboxing options to fit different security requirements and deployment scenarios.
 
-By default, OpenHands uses a [Docker-based runtime](/usage/runtimes/docker), running on your local computer.
-This means you only have to pay for the LLM you're using, and your code is only ever sent to the LLM.
+## Choosing a Runtime
 
-Additionally, we provide a [Local Runtime](/usage/runtimes/local) that runs directly on your machine without Docker,
-which can be useful in controlled environments like CI pipelines.
+| Runtime | Sandbox Type | Best For |
+|---------|-------------|----------|
+| [Docker Runtime](/usage/runtimes/docker) | Docker container | Most users (default, recommended) |
+| [Remote Runtime](/usage/runtimes/remote) | Cloud sandbox | Parallel workloads, managed infrastructure |
+| [Local Runtime](/usage/runtimes/local) | No sandbox | CI/CD pipelines, development, controlled environments |
+| [Apptainer Runtime](#run-in-an-apptainer-sandbox) | Apptainer container | HPC environments, no root required |
 
-## Available Runtimes
+### Run in a Docker Sandbox (Default)
+
+The [Docker Runtime](/usage/runtimes/docker) 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.
+
+<Note>
+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](/usage/runtimes/remote) for cloud-based sandboxing, the [Apptainer Runtime](#run-in-an-apptainer-sandbox) for
+daemon-free sandboxing, or the [Local Runtime](/usage/runtimes/local) for no sandboxing.
+</Note>
+
+**Using the SDK:**
+
+```python
+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
 
-OpenHands supports several different runtime environments:
+The [Remote Runtime](/usage/runtimes/remote) 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:**
+
+```python
+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](/usage/runtimes/local) 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.
+
+<Warning>
+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.
+</Warning>
+
+**Starting the agent server locally:**
+
+```bash
+# 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:**
+
+```python
+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](https://apptainer.org/) (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](https://github.com/OpenHands/software-agent-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:**
+
+```python
+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)
+```
+
+<Note>
+Apptainer must be installed on your system. See the [Apptainer installation guide](https://apptainer.org/docs/admin/main/installation.html)
+for instructions.
+</Note>
+
+See the [SDK documentation](https://github.com/OpenHands/software-agent-sdk/blob/main/openhands-workspace/openhands/workspace/apptainer/README.md)
+for more details.
+
+## Available Runtimes
 
-- [Docker Runtime](/usage/runtimes/docker) - The default runtime that uses Docker containers for isolation (recommended for most users).
-- [OpenHands Remote Runtime](/usage/runtimes/remote) - Cloud-based runtime for parallel execution (beta).
-- [Local Runtime](/usage/runtimes/local) - Direct execution on your local machine without Docker.
+- [Docker Runtime](/usage/runtimes/docker) - Run in a Docker sandbox (recommended for most users).
+- [Remote Runtime](/usage/runtimes/remote) - Run on the cloud with managed sandboxes (beta).
+- [Local Runtime](/usage/runtimes/local) - Run without sandboxing, directly on your machine.
 
 ### Third-Party Runtimes