diff --git a/openhands/usage/run-openhands/local-setup.mdx b/openhands/usage/run-openhands/local-setup.mdx index 8722aa31..541a1036 100644 --- a/openhands/usage/run-openhands/local-setup.mdx +++ b/openhands/usage/run-openhands/local-setup.mdx @@ -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. + +**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 4cbf0c90..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. --- @@ -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. + +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,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 + + +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 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 + + +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. + diff --git a/openhands/usage/runtimes/overview.mdx b/openhands/usage/runtimes/overview.mdx index 47ef4eee..c2bd7c18 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,133 @@ 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 | +| [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. + + +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. + + +**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. + + +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:** + +```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) +``` + + +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 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