From e848c9e59dfd0b452fbcb1ff09e832c026049ebf Mon Sep 17 00:00:00 2001 From: openhands Date: Thu, 1 Jan 2026 15:32:57 +0000 Subject: [PATCH 1/6] docs: Add instructions for running Docker without socket mount Add documentation for running OpenHands in Docker without mounting the Docker socket by using the Local/Process Runtime (RUNTIME=local). This addresses issue #1563 in OpenHands/OpenHands which requested a way to run OpenHands without granting access to the Docker socket. Changes: - local-setup.mdx: Add Option 3 for Docker without socket - local.mdx: Update prerequisites and add section for running inside Docker Co-authored-by: openhands --- openhands/usage/run-openhands/local-setup.mdx | 32 ++++++++++++++++++ openhands/usage/runtimes/local.mdx | 33 +++++++++++++++++-- 2 files changed, 63 insertions(+), 2 deletions(-) diff --git a/openhands/usage/run-openhands/local-setup.mdx b/openhands/usage/run-openhands/local-setup.mdx index 8722aa31..cb3af610 100644 --- a/openhands/usage/run-openhands/local-setup.mdx +++ b/openhands/usage/run-openhands/local-setup.mdx @@ -136,6 +136,38 @@ docker run -it --rm --pull=always \ +#### Option 3: Using Docker Without Docker Socket (Process Runtime) + +If you prefer not to mount the Docker socket for security reasons, you can use the process runtime which runs +the agent directly inside the OpenHands container without creating additional Docker containers. + + +**Security Note**: The process runtime runs without sandbox isolation. The agent executes commands directly +inside the container. While this avoids exposing the Docker socket, ensure you understand the security +implications. See the [Local Runtime documentation](/openhands/usage/runtimes/local) for more details. + + + + +```bash +docker run -it --rm --pull=always \ + -e RUNTIME=local \ + -e LOG_ALL_EVENTS=true \ + -v ~/.openhands:/.openhands \ + -v /path/to/your/workspace:/workspace \ + -p 3000:3000 \ + --name openhands-app \ + docker.openhands.dev/openhands/openhands:1.1 +``` + +Key differences from the standard Docker command: +- `-e RUNTIME=local`: Uses the process runtime instead of Docker runtime +- No `-v /var/run/docker.sock:/var/run/docker.sock`: Docker socket is not required +- `-v /path/to/your/workspace:/workspace`: Mount your project directory directly (optional but recommended) +- No `SANDBOX_RUNTIME_CONTAINER_IMAGE`: Not needed since we're not creating sandbox containers + + + > **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. You'll find OpenHands running at http://localhost:3000! diff --git a/openhands/usage/runtimes/local.mdx b/openhands/usage/runtimes/local.mdx index 4cbf0c90..62146be3 100644 --- a/openhands/usage/runtimes/local.mdx +++ b/openhands/usage/runtimes/local.mdx @@ -14,8 +14,8 @@ 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. +1. You can run OpenHands using the [Development workflow](https://github.com/OpenHands/OpenHands/blob/main/Development.md), OR you are running OpenHands inside a Docker container with `RUNTIME=local`. +2. For Linux and Mac, tmux is available on your system (pre-installed in the OpenHands Docker image). 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. @@ -70,3 +70,32 @@ The Local Runtime is particularly useful for: - CI/CD pipelines where Docker is not available. - Testing and development of OpenHands itself. - Environments where container usage is restricted (e.g. native Windows). +- **Running OpenHands in Docker without mounting the Docker socket** (see below). + +## Running Local Runtime Inside Docker + +If you want to run OpenHands in Docker but prefer not to mount the Docker socket (`/var/run/docker.sock`) for security +reasons, you can use the Local Runtime inside the OpenHands container. This avoids the need for Docker-in-Docker while +still providing a containerized environment. + +```bash +docker run -it --rm --pull=always \ + -e RUNTIME=local \ + -e LOG_ALL_EVENTS=true \ + -v ~/.openhands:/.openhands \ + -v /path/to/your/workspace:/workspace \ + -p 3000:3000 \ + --name openhands-app \ + docker.openhands.dev/openhands/openhands:1.1 +``` + +Key points: +- `-e RUNTIME=local`: Enables the Local Runtime instead of the default Docker Runtime +- No Docker socket mount required +- Mount your workspace directly with `-v /path/to/your/workspace:/workspace` +- The agent will execute commands directly inside the OpenHands container + + +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. + From a43a87d95220ce05fe40c6316790181ba9008fb5 Mon Sep 17 00:00:00 2001 From: openhands Date: Thu, 1 Jan 2026 15:33:53 +0000 Subject: [PATCH 2/6] docs: Add Remote Runtime option for running without Docker socket Also reorganize the 'Docker Without Socket' section to show both options: - Process Runtime (local execution, no sandbox isolation) - Remote Runtime (cloud execution, full sandbox isolation) Co-authored-by: openhands --- openhands/usage/run-openhands/local-setup.mdx | 41 +++++++++++++++++-- 1 file changed, 37 insertions(+), 4 deletions(-) diff --git a/openhands/usage/run-openhands/local-setup.mdx b/openhands/usage/run-openhands/local-setup.mdx index cb3af610..0be0f807 100644 --- a/openhands/usage/run-openhands/local-setup.mdx +++ b/openhands/usage/run-openhands/local-setup.mdx @@ -136,10 +136,13 @@ docker run -it --rm --pull=always \ -#### Option 3: Using Docker Without Docker Socket (Process Runtime) +#### Option 3: Using Docker Without Docker Socket -If you prefer not to mount the Docker socket for security reasons, you can use the process runtime which runs -the agent directly inside the OpenHands container without creating additional Docker containers. +If you prefer not to mount the Docker socket for security reasons, you have two alternatives: + +##### Process Runtime (Local Execution) + +The process runtime runs the agent directly inside the OpenHands container without creating additional Docker containers. **Security Note**: The process runtime runs without sandbox isolation. The agent executes commands directly @@ -147,7 +150,7 @@ inside the container. While this avoids exposing the Docker socket, ensure you u implications. See the [Local Runtime documentation](/openhands/usage/runtimes/local) for more details. - + ```bash docker run -it --rm --pull=always \ @@ -168,6 +171,36 @@ Key differences from the standard Docker command: +##### Remote Runtime (Cloud Execution) + +The remote runtime connects to a cloud-based sandbox service, avoiding the need for local Docker socket access entirely. +This provides full sandbox isolation without requiring Docker socket access. + + + +```bash +docker run -it --rm --pull=always \ + -e RUNTIME=remote \ + -e SANDBOX_API_KEY=your-api-key \ + -e SANDBOX_REMOTE_RUNTIME_API_URL=https://your-runtime-api.com \ + -e LOG_ALL_EVENTS=true \ + -v ~/.openhands:/.openhands \ + -p 3000:3000 \ + --name openhands-app \ + docker.openhands.dev/openhands/openhands:1.1 +``` + +Key differences: +- `-e RUNTIME=remote`: Uses the remote runtime +- `-e SANDBOX_API_KEY`: Your API key for the remote runtime service +- `-e SANDBOX_REMOTE_RUNTIME_API_URL`: URL of the remote runtime API +- No Docker socket mount required +- Sandboxes run in the cloud with full isolation + +See the [Remote Runtime documentation](/openhands/usage/runtimes/remote) for more details on obtaining API access. + + + > **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. You'll find OpenHands running at http://localhost:3000! From 533237c0b2ed6f4e9f725250eb718d212841fea6 Mon Sep 17 00:00:00 2001 From: openhands Date: Thu, 1 Jan 2026 15:48:19 +0000 Subject: [PATCH 3/6] Improve runtime/sandbox documentation framing - Update overview.mdx to frame options as sandbox types (Docker sandbox, cloud, no sandbox) - Simplify local-setup.mdx to point to Runtimes docs for alternative sandbox options - Update local.mdx to clarify tmux requirement and Docker image limitations - Use consistent terminology: 'sandbox' instead of 'Docker socket' Co-authored-by: openhands --- openhands/usage/run-openhands/local-setup.mdx | 70 ++----------------- openhands/usage/runtimes/local.mdx | 41 ++++++----- openhands/usage/runtimes/overview.mdx | 43 +++++++++--- 3 files changed, 61 insertions(+), 93 deletions(-) diff --git a/openhands/usage/run-openhands/local-setup.mdx b/openhands/usage/run-openhands/local-setup.mdx index 0be0f807..541a1036 100644 --- a/openhands/usage/run-openhands/local-setup.mdx +++ b/openhands/usage/run-openhands/local-setup.mdx @@ -136,73 +136,13 @@ docker run -it --rm --pull=always \ -#### Option 3: Using Docker Without Docker Socket - -If you prefer not to mount the Docker socket for security reasons, you have two alternatives: - -##### Process Runtime (Local Execution) - -The process runtime runs the agent directly inside the OpenHands container without creating additional Docker containers. - - -**Security Note**: The process runtime runs without sandbox isolation. The agent executes commands directly -inside the container. While this avoids exposing the Docker socket, ensure you understand the security -implications. See the [Local Runtime documentation](/openhands/usage/runtimes/local) for more details. - - - - -```bash -docker run -it --rm --pull=always \ - -e RUNTIME=local \ - -e LOG_ALL_EVENTS=true \ - -v ~/.openhands:/.openhands \ - -v /path/to/your/workspace:/workspace \ - -p 3000:3000 \ - --name openhands-app \ - docker.openhands.dev/openhands/openhands:1.1 -``` - -Key differences from the standard Docker command: -- `-e RUNTIME=local`: Uses the process runtime instead of Docker runtime -- No `-v /var/run/docker.sock:/var/run/docker.sock`: Docker socket is not required -- `-v /path/to/your/workspace:/workspace`: Mount your project directory directly (optional but recommended) -- No `SANDBOX_RUNTIME_CONTAINER_IMAGE`: Not needed since we're not creating sandbox containers - - - -##### Remote Runtime (Cloud Execution) - -The remote runtime connects to a cloud-based sandbox service, avoiding the need for local Docker socket access entirely. -This provides full sandbox isolation without requiring Docker socket access. - - - -```bash -docker run -it --rm --pull=always \ - -e RUNTIME=remote \ - -e SANDBOX_API_KEY=your-api-key \ - -e SANDBOX_REMOTE_RUNTIME_API_URL=https://your-runtime-api.com \ - -e LOG_ALL_EVENTS=true \ - -v ~/.openhands:/.openhands \ - -p 3000:3000 \ - --name openhands-app \ - docker.openhands.dev/openhands/openhands:1.1 -``` - -Key differences: -- `-e RUNTIME=remote`: Uses the remote runtime -- `-e SANDBOX_API_KEY`: Your API key for the remote runtime service -- `-e SANDBOX_REMOTE_RUNTIME_API_URL`: URL of the remote runtime API -- No Docker socket mount required -- Sandboxes run in the cloud with full isolation - -See the [Remote Runtime documentation](/openhands/usage/runtimes/remote) for more details on obtaining API access. - - - > **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. + +**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). + + You'll find OpenHands running at http://localhost:3000! ### Setup diff --git a/openhands/usage/runtimes/local.mdx b/openhands/usage/runtimes/local.mdx index 62146be3..a364d8dc 100644 --- a/openhands/usage/runtimes/local.mdx +++ b/openhands/usage/runtimes/local.mdx @@ -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. --- @@ -14,11 +13,16 @@ 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), OR you are running OpenHands inside a Docker container with `RUNTIME=local`. -2. For Linux and Mac, tmux is available on your system (pre-installed in the OpenHands Docker image). +1. You can run OpenHands using the [Development workflow](https://github.com/OpenHands/OpenHands/blob/main/Development.md). +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. + +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. + + ## Configuration To use the Local Runtime, besides required configurations like the LLM provider, model and API key, you'll need to set @@ -67,33 +71,36 @@ 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 in Docker without mounting the Docker socket** (see below). +- Running OpenHands inside a container without nested sandboxing (see below). -## Running Local Runtime Inside Docker +## Running Without Sandbox Inside Docker + + +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. + -If you want to run OpenHands in Docker but prefer not to mount the Docker socket (`/var/run/docker.sock`) for security -reasons, you can use the Local Runtime inside the OpenHands container. This avoids the need for Docker-in-Docker while -still providing a containerized environment. +If you have a Docker image with tmux installed, you can run OpenHands without nested sandboxing: ```bash -docker run -it --rm --pull=always \ +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 \ - docker.openhands.dev/openhands/openhands:1.1 + your-custom-openhands-image:tag ``` Key points: -- `-e RUNTIME=local`: Enables the Local Runtime instead of the default Docker Runtime -- No Docker socket mount required +- `-e RUNTIME=local`: Runs without sandbox isolation - Mount your workspace directly with `-v /path/to/your/workspace:/workspace` -- The agent will execute commands directly inside the OpenHands container +- The agent executes commands directly inside the container When using Local Runtime inside Docker, the agent operates within the container's filesystem. Any files you want the diff --git a/openhands/usage/runtimes/overview.mdx b/openhands/usage/runtimes/overview.mdx index 47ef4eee..6db88052 100644 --- a/openhands/usage/runtimes/overview.mdx +++ b/openhands/usage/runtimes/overview.mdx @@ -1,6 +1,6 @@ --- 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. --- @@ -8,21 +8,42 @@ description: This section is for users that would like to use a runtime other th 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 | -## 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. + +### Run on the Cloud + +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. -OpenHands supports several different runtime environments: +### 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. + + +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. + + +## 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 From 55a25d9a96770bd57afaf993c45145a90363ee7f Mon Sep 17 00:00:00 2001 From: openhands Date: Thu, 1 Jan 2026 16:17:26 +0000 Subject: [PATCH 4/6] Clarify Docker socket concern and mention Apptainer as future option - Add note explaining Docker socket requirement and alternatives - Add section about Apptainer as a potential community contribution - Apptainer can provide sandboxed execution without daemon socket exposure Co-authored-by: openhands --- openhands/usage/runtimes/overview.mdx | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/openhands/usage/runtimes/overview.mdx b/openhands/usage/runtimes/overview.mdx index 6db88052..ab0ed35b 100644 --- a/openhands/usage/runtimes/overview.mdx +++ b/openhands/usage/runtimes/overview.mdx @@ -23,6 +23,12 @@ commands. OpenHands supports multiple sandboxing options to fit different securi 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. + +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 or the [Local Runtime](/usage/runtimes/local) for no sandboxing. + + ### Run on the Cloud The [Remote Runtime](/usage/runtimes/remote) connects to cloud-based sandbox environments. @@ -39,6 +45,13 @@ Running without sandboxing means the agent has direct access to your filesystem without isolation. Only use this in controlled environments where you understand the security implications. +### 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. OpenHands does not currently have a built-in Apptainer runtime, +but this would be a welcome community contribution. See the [third-party runtimes](#third-party-runtimes) section for how +custom runtimes can be integrated. + ## Available Runtimes - [Docker Runtime](/usage/runtimes/docker) - Run in a Docker sandbox (recommended for most users). From bab361723a7e305b39d91d533272c69695d49ef6 Mon Sep 17 00:00:00 2001 From: openhands Date: Thu, 1 Jan 2026 16:19:08 +0000 Subject: [PATCH 5/6] Update Apptainer section to reference existing SDK implementation The OpenHands SDK already has ApptainerWorkspace - link to it instead of suggesting it as a future contribution. Co-authored-by: openhands --- openhands/usage/runtimes/overview.mdx | 14 +++++++++++--- 1 file changed, 11 insertions(+), 3 deletions(-) diff --git a/openhands/usage/runtimes/overview.mdx b/openhands/usage/runtimes/overview.mdx index ab0ed35b..caad64ee 100644 --- a/openhands/usage/runtimes/overview.mdx +++ b/openhands/usage/runtimes/overview.mdx @@ -48,9 +48,17 @@ without isolation. Only use this in controlled environments where you understand ### 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. OpenHands does not currently have a built-in Apptainer runtime, -but this would be a welcome community contribution. See the [third-party runtimes](#third-party-runtimes) section for how -custom runtimes can be integrated. +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 + +See the [SDK documentation](https://github.com/OpenHands/software-agent-sdk/blob/main/openhands-workspace/openhands/workspace/apptainer/README.md) +for usage details. ## Available Runtimes From ccdcd47357e82d614f9977a3034d05ac39434215 Mon Sep 17 00:00:00 2001 From: openhands Date: Thu, 1 Jan 2026 16:27:32 +0000 Subject: [PATCH 6/6] Add concrete SDK commands for each workspace type - Docker sandbox: DockerWorkspace example - Cloud sandbox: OpenHandsCloudWorkspace example - Local (no sandbox): agent server CLI and Workspace example - Apptainer sandbox: ApptainerWorkspace example All commands verified to work with the software-agent-sdk. Co-authored-by: openhands --- openhands/usage/runtimes/overview.mdx | 74 ++++++++++++++++++++++++++- 1 file changed, 72 insertions(+), 2 deletions(-) diff --git a/openhands/usage/runtimes/overview.mdx b/openhands/usage/runtimes/overview.mdx index caad64ee..c2bd7c18 100644 --- a/openhands/usage/runtimes/overview.mdx +++ b/openhands/usage/runtimes/overview.mdx @@ -17,6 +17,7 @@ commands. OpenHands supports multiple sandboxing options to fit different securi | [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 | ### Run in a Docker Sandbox (Default) @@ -26,14 +27,43 @@ This is the recommended option for most users as it provides strong isolation wh 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 or the [Local Runtime](/usage/runtimes/local) for no sandboxing. +[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. +**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 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) @@ -45,6 +75,27 @@ Running without sandboxing means the agent has direct access to your filesystem without isolation. Only use this in controlled environments where you understand the security implications. +**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 @@ -57,8 +108,27 @@ Key benefits of Apptainer: - **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) +``` + + +Apptainer must be installed on your system. See the [Apptainer installation guide](https://apptainer.org/docs/admin/main/installation.html) +for instructions. + + See the [SDK documentation](https://github.com/OpenHands/software-agent-sdk/blob/main/openhands-workspace/openhands/workspace/apptainer/README.md) -for usage details. +for more details. ## Available Runtimes