From 99aa9bef704cadb04bf3095edc815abf820a81bf Mon Sep 17 00:00:00 2001 From: Robert Brennan Date: Sat, 22 Mar 2025 18:35:47 -0700 Subject: [PATCH] Refactor runtime documentation and add hardened Docker installation guide (#7429) Co-authored-by: openhands Co-authored-by: Engel Nyst --- README.md | 4 + docs/modules/usage/runtimes-index.md | 24 ++++ docs/modules/usage/runtimes.md | 180 +------------------------ docs/modules/usage/runtimes/daytona.md | 32 +++++ docs/modules/usage/runtimes/docker.md | 88 ++++++++++++ docs/modules/usage/runtimes/local.md | 62 +++++++++ docs/modules/usage/runtimes/modal.md | 13 ++ docs/modules/usage/runtimes/remote.md | 6 + docs/sidebars.ts | 35 ++++- 9 files changed, 268 insertions(+), 176 deletions(-) create mode 100644 docs/modules/usage/runtimes-index.md create mode 100644 docs/modules/usage/runtimes/daytona.md create mode 100644 docs/modules/usage/runtimes/docker.md create mode 100644 docs/modules/usage/runtimes/local.md create mode 100644 docs/modules/usage/runtimes/modal.md create mode 100644 docs/modules/usage/runtimes/remote.md diff --git a/README.md b/README.md index 5fd11dbad6..904cdc738c 100644 --- a/README.md +++ b/README.md @@ -56,6 +56,10 @@ docker run -it --rm --pull=always \ docker.all-hands.dev/all-hands-ai/openhands:0.29 ``` +> [!WARNING] +> On a public network? See our [Hardened Docker Installation](https://docs.all-hands.dev/modules/usage/runtimes/docker#hardened-docker-installation) guide +> to secure your deployment by restricting network binding and implementing additional security measures. + You'll find OpenHands running at [http://localhost:3000](http://localhost:3000)! Finally, you'll need a model provider and API key. diff --git a/docs/modules/usage/runtimes-index.md b/docs/modules/usage/runtimes-index.md new file mode 100644 index 0000000000..c29dfebe27 --- /dev/null +++ b/docs/modules/usage/runtimes-index.md @@ -0,0 +1,24 @@ +# Runtime Configuration + +A Runtime is an environment where the OpenHands agent can edit files and run +commands. + +By default, OpenHands uses a Docker-based runtime, 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. + +We also support "remote" runtimes, which are typically managed by third-parties. +They can make setup a bit simpler and more scalable, especially +if you're running many OpenHands conversations in parallel (e.g. to do evaluation). + +Additionally, we provide a "local" runtime that runs directly on your machine without Docker, +which can be useful in controlled environments like CI pipelines. + +## Available Runtimes + +OpenHands supports several different runtime environments: + +- [Docker Runtime](./runtimes/docker.md) - The default runtime that uses Docker containers for isolation (recommended for most users) +- [OpenHands Remote Runtime](./runtimes/remote.md) - Cloud-based runtime for parallel execution (beta) +- [Modal Runtime](./runtimes/modal.md) - Runtime provided by our partners at Modal +- [Daytona Runtime](./runtimes/daytona.md) - Runtime provided by Daytona +- [Local Runtime](./runtimes/local.md) - Direct execution on your local machine without Docker \ No newline at end of file diff --git a/docs/modules/usage/runtimes.md b/docs/modules/usage/runtimes.md index f003f51ec7..f20cdf97c8 100644 --- a/docs/modules/usage/runtimes.md +++ b/docs/modules/usage/runtimes.md @@ -1,176 +1,8 @@ -# Runtime Configuration +--- +title: Runtime Configuration +slug: /usage/runtimes +--- -A Runtime is an environment where the OpenHands agent can edit files and run -commands. +import { Redirect } from '@docusaurus/router'; -By default, OpenHands uses a Docker-based runtime, 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. - -We also support "remote" runtimes, which are typically managed by third-parties. -They can make setup a bit simpler and more scalable, especially -if you're running many OpenHands conversations in parallel (e.g. to do evaluation). - -Additionally, we provide a "local" runtime that runs directly on your machine without Docker, -which can be useful in controlled environments like CI pipelines. - -## Docker Runtime -This is the default Runtime that's used when you start OpenHands. You might notice -some flags being passed to `docker run` that make this possible: - -``` -docker run # ... - -e SANDBOX_RUNTIME_CONTAINER_IMAGE=docker.all-hands.dev/all-hands-ai/runtime:0.29-nikolaik \ - -v /var/run/docker.sock:/var/run/docker.sock \ - # ... -``` - -The `SANDBOX_RUNTIME_CONTAINER_IMAGE` from nikolaik is a pre-built runtime image -that contains our Runtime server, as well as some basic utilities for Python and NodeJS. -You can also [build your own runtime image](how-to/custom-sandbox-guide). - -### Connecting to Your filesystem -One useful feature here is the ability to connect to your local filesystem. To mount your filesystem into the runtime: -1. Set `WORKSPACE_BASE`: - - ```bash - export WORKSPACE_BASE=/path/to/your/code - - # Linux and Mac Example - # export WORKSPACE_BASE=$HOME/OpenHands - # Will set $WORKSPACE_BASE to /home//OpenHands - # - # WSL on Windows Example - # export WORKSPACE_BASE=/mnt/c/dev/OpenHands - # Will set $WORKSPACE_BASE to C:\dev\OpenHands - ``` -2. Add the following options to the `docker run` command: - - ```bash - docker run # ... - -e SANDBOX_USER_ID=$(id -u) \ - -e WORKSPACE_MOUNT_PATH=$WORKSPACE_BASE \ - -v $WORKSPACE_BASE:/opt/workspace_base \ - # ... - ``` - -Be careful! There's nothing stopping the OpenHands agent from deleting or modifying -any files that are mounted into its workspace. - -This setup can cause some issues with file permissions (hence the `SANDBOX_USER_ID` variable) -but seems to work well on most systems. - -## OpenHands Remote Runtime - -OpenHands Remote Runtime is currently in beta (read [here](https://runtime.all-hands.dev/) for more details), it allows you to launch runtimes in parallel in the cloud. -Fill out [this form](https://docs.google.com/forms/d/e/1FAIpQLSckVz_JFwg2_mOxNZjCtr7aoBFI2Mwdan3f75J_TrdMS1JV2g/viewform) to apply if you want to try this out! - -NOTE: This runtime is specifically designed for agent evaluation purposes only through [OpenHands evaluation harness](https://github.com/All-Hands-AI/OpenHands/tree/main/evaluation). It should not be used to launch production OpenHands applications. - -## Modal Runtime -Our partners at [Modal](https://modal.com/) have also provided a runtime for OpenHands. - -To use the Modal Runtime, create an account, and then [create an API key.](https://modal.com/settings) - -You'll then need to set the following environment variables when starting OpenHands: -```bash -docker run # ... - -e RUNTIME=modal \ - -e MODAL_API_TOKEN_ID="your-id" \ - -e MODAL_API_TOKEN_SECRET="your-secret" \ -``` - -## Daytona Runtime - -Another option is using [Daytona](https://www.daytona.io/) as a runtime provider: - -### Step 1: Retrieve Your Daytona API Key -1. Visit the [Daytona Dashboard](https://app.daytona.io/dashboard/keys). -2. Click **"Create Key"**. -3. Enter a name for your key and confirm the creation. -4. Once the key is generated, copy it. - -### Step 2: Set Your API Key as an Environment Variable -Run the following command in your terminal, replacing `` with the actual key you copied: -```bash -export DAYTONA_API_KEY="" -``` - -This step ensures that OpenHands can authenticate with the Daytona platform when it runs. - -### Step 3: Run OpenHands Locally Using Docker -To start the latest version of OpenHands on your machine, execute the following command in your terminal: -```bash -bash -i <(curl -sL https://get.daytona.io/openhands) -``` - -#### What This Command Does: -- Downloads the latest OpenHands release script. -- Runs the script in an interactive Bash session. -- Automatically pulls and runs the OpenHands container using Docker. - -Once executed, OpenHands should be running locally and ready for use. - -For more details and manual initialization, view the entire [README.md](https://github.com/All-Hands-AI/OpenHands/blob/main/openhands/runtime/impl/daytona/README.md) - -## Local Runtime - -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. - -:::caution -**Security Warning**: The Local Runtime runs without any sandbox isolation. The agent can directly access and modify files on your machine. Only use this runtime in controlled environments or when you fully understand the security implications. -::: - -### Prerequisites - -Before using the Local Runtime, ensure you have the following dependencies installed: - -1. You have followed the [Development setup instructions](https://github.com/All-Hands-AI/OpenHands/blob/main/Development.md). -2. tmux is available on your system. - -### Configuration - -To use the Local Runtime, besides required configurations like the model, API key, you'll need to set the following options via environment variables or the [config.toml file](https://github.com/All-Hands-AI/OpenHands/blob/main/config.template.toml) when starting OpenHands: - -- Via environment variables: - -```bash -# Required -export RUNTIME=local - -# Optional but recommended -export WORKSPACE_BASE=/path/to/your/workspace -``` - -- Via `config.toml`: - -```toml -[core] -runtime = "local" -workspace_base = "/path/to/your/workspace" -``` - -If `WORKSPACE_BASE` is not set, the runtime will create a temporary directory for the agent to work in. - -### Example Usage - -Here's an example of how to start OpenHands with the Local Runtime in Headless Mode: - -```bash -# Set the runtime type to local -export RUNTIME=local - -# Optionally set a workspace directory -export WORKSPACE_BASE=/path/to/your/project - -# Start OpenHands -poetry run python -m openhands.core.main -t "write a bash script that prints hi" -``` - -### Use Cases - -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. -- Scenarios where direct file system access is required. + diff --git a/docs/modules/usage/runtimes/daytona.md b/docs/modules/usage/runtimes/daytona.md new file mode 100644 index 0000000000..7424241f05 --- /dev/null +++ b/docs/modules/usage/runtimes/daytona.md @@ -0,0 +1,32 @@ +# Daytona Runtime + +You can use [Daytona](https://www.daytona.io/) as a runtime provider: + +## Step 1: Retrieve Your Daytona API Key +1. Visit the [Daytona Dashboard](https://app.daytona.io/dashboard/keys). +2. Click **"Create Key"**. +3. Enter a name for your key and confirm the creation. +4. Once the key is generated, copy it. + +## Step 2: Set Your API Key as an Environment Variable +Run the following command in your terminal, replacing `` with the actual key you copied: +```bash +export DAYTONA_API_KEY="" +``` + +This step ensures that OpenHands can authenticate with the Daytona platform when it runs. + +## Step 3: Run OpenHands Locally Using Docker +To start the latest version of OpenHands on your machine, execute the following command in your terminal: +```bash +bash -i <(curl -sL https://get.daytona.io/openhands) +``` + +### What This Command Does: +- Downloads the latest OpenHands release script. +- Runs the script in an interactive Bash session. +- Automatically pulls and runs the OpenHands container using Docker. + +Once executed, OpenHands should be running locally and ready for use. + +For more details and manual initialization, view the entire [README.md](https://github.com/All-Hands-AI/OpenHands/blob/main/openhands/runtime/impl/daytona/README.md) \ No newline at end of file diff --git a/docs/modules/usage/runtimes/docker.md b/docs/modules/usage/runtimes/docker.md new file mode 100644 index 0000000000..2beef62ac0 --- /dev/null +++ b/docs/modules/usage/runtimes/docker.md @@ -0,0 +1,88 @@ +# Docker Runtime + +This is the default Runtime that's used when you start OpenHands. + +## Image +The `SANDBOX_RUNTIME_CONTAINER_IMAGE` from nikolaik is a pre-built runtime image +that contains our Runtime server, as well as some basic utilities for Python and NodeJS. +You can also [build your own runtime image](../how-to/custom-sandbox-guide). + +## Connecting to Your filesystem +One useful feature here is the ability to connect to your local filesystem. To mount your filesystem into the runtime: +1. Set `WORKSPACE_BASE`: + + ```bash + export WORKSPACE_BASE=/path/to/your/code + + # Linux and Mac Example + # export WORKSPACE_BASE=$HOME/OpenHands + # Will set $WORKSPACE_BASE to /home//OpenHands + # + # WSL on Windows Example + # export WORKSPACE_BASE=/mnt/c/dev/OpenHands + # Will set $WORKSPACE_BASE to C:\dev\OpenHands + ``` +2. Add the following options to the `docker run` command: + + ```bash + docker run # ... + -e SANDBOX_USER_ID=$(id -u) \ + -e WORKSPACE_MOUNT_PATH=$WORKSPACE_BASE \ + -v $WORKSPACE_BASE:/opt/workspace_base \ + # ... + ``` + +Be careful! There's nothing stopping the OpenHands agent from deleting or modifying +any files that are mounted into its workspace. + +This setup can cause some issues with file permissions (hence the `SANDBOX_USER_ID` variable) +but seems to work well on most systems. + +## Hardened Docker Installation + +When deploying OpenHands in environments where security is a priority, you should consider implementing a hardened Docker configuration. This section provides recommendations for securing your OpenHands Docker deployment beyond the default configuration. + +### Security Considerations + +The default Docker configuration in the README is designed for ease of use on a local development machine. If you're running on a public network (e.g. airport WiFi), +you should implement additional security measures. + +### Network Binding Security + +By default, OpenHands binds to all network interfaces (`0.0.0.0`), which can expose your instance to all networks the host is connected to. For a more secure setup: + +1. **Restrict Network Binding**: + + Use the `runtime_binding_address` configuration to restrict which network interfaces OpenHands listens on: + + ```bash + docker run # ... + -e SANDBOX_RUNTIME_BINDING_ADDRESS=127.0.0.1 \ + # ... + ``` + + This configuration ensures OpenHands only listens on the loopback interface (`127.0.0.1`), making it accessible only from the local machine. + +2. **Secure Port Binding**: + + Modify the `-p` flag to bind only to localhost instead of all interfaces: + + ```bash + docker run # ... \ + -p 127.0.0.1:3000:3000 \ + ``` + + This ensures that the OpenHands web interface is only accessible from the local machine, not from other machines on the network. + +### Network Isolation + +Use Docker's network features to isolate OpenHands: + +```bash +# Create an isolated network +docker network create openhands-network + +# Run OpenHands in the isolated network +docker run # ... \ + --network openhands-network \ +``` diff --git a/docs/modules/usage/runtimes/local.md b/docs/modules/usage/runtimes/local.md new file mode 100644 index 0000000000..2fb1ec4f78 --- /dev/null +++ b/docs/modules/usage/runtimes/local.md @@ -0,0 +1,62 @@ +# Local Runtime + +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. + +:::caution +**Security Warning**: The Local Runtime runs without any sandbox isolation. The agent can directly access and modify files on your machine. Only use this runtime in controlled environments or when you fully understand the security implications. +::: + +## Prerequisites + +Before using the Local Runtime, ensure that: + +1. You have followed the [Development setup instructions](https://github.com/All-Hands-AI/OpenHands/blob/main/Development.md). +2. tmux is available on your system. + +## Configuration + +To use the Local Runtime, besides required configurations like the model, API key, you'll need to set the following options via environment variables or the [config.toml file](https://github.com/All-Hands-AI/OpenHands/blob/main/config.template.toml) when starting OpenHands: + +- Via environment variables: + +```bash +# Required +export RUNTIME=local + +# Optional but recommended +export WORKSPACE_BASE=/path/to/your/workspace +``` + +- Via `config.toml`: + +```toml +[core] +runtime = "local" +workspace_base = "/path/to/your/workspace" +``` + +If `WORKSPACE_BASE` is not set, the runtime will create a temporary directory for the agent to work in. + +## Example Usage + +Here's an example of how to start OpenHands with the Local Runtime in Headless Mode: + +```bash +# Set the runtime type to local +export RUNTIME=local + +# Optionally set a workspace directory +export WORKSPACE_BASE=/path/to/your/project + +# Start OpenHands +poetry run python -m openhands.core.main -t "write a bash script that prints hi" +``` + +## Use Cases + +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. +- Scenarios where direct file system access is required. \ No newline at end of file diff --git a/docs/modules/usage/runtimes/modal.md b/docs/modules/usage/runtimes/modal.md new file mode 100644 index 0000000000..590fbc8c64 --- /dev/null +++ b/docs/modules/usage/runtimes/modal.md @@ -0,0 +1,13 @@ +# Modal Runtime + +Our partners at [Modal](https://modal.com/) have provided a runtime for OpenHands. + +To use the Modal Runtime, create an account, and then [create an API key.](https://modal.com/settings) + +You'll then need to set the following environment variables when starting OpenHands: +```bash +docker run # ... + -e RUNTIME=modal \ + -e MODAL_API_TOKEN_ID="your-id" \ + -e MODAL_API_TOKEN_SECRET="your-secret" \ +``` \ No newline at end of file diff --git a/docs/modules/usage/runtimes/remote.md b/docs/modules/usage/runtimes/remote.md new file mode 100644 index 0000000000..c6688136ba --- /dev/null +++ b/docs/modules/usage/runtimes/remote.md @@ -0,0 +1,6 @@ +# OpenHands Remote Runtime + +OpenHands Remote Runtime is currently in beta (read [here](https://runtime.all-hands.dev/) for more details), it allows you to launch runtimes in parallel in the cloud. +Fill out [this form](https://docs.google.com/forms/d/e/1FAIpQLSckVz_JFwg2_mOxNZjCtr7aoBFI2Mwdan3f75J_TrdMS1JV2g/viewform) to apply if you want to try this out! + +NOTE: This runtime is specifically designed for agent evaluation purposes only through [OpenHands evaluation harness](https://github.com/All-Hands-AI/OpenHands/tree/main/evaluation). It should not be used to launch production OpenHands applications. \ No newline at end of file diff --git a/docs/sidebars.ts b/docs/sidebars.ts index f41c65df50..e222e814c5 100644 --- a/docs/sidebars.ts +++ b/docs/sidebars.ts @@ -156,9 +156,40 @@ const sidebars: SidebarsConfig = { ], }, { - type: 'doc', + type: 'category', label: 'Runtime Configuration', - id: 'usage/runtimes', + items: [ + { + type: 'doc', + label: 'Overview', + id: 'usage/runtimes-index', + }, + { + type: 'doc', + label: 'Docker Runtime', + id: 'usage/runtimes/docker', + }, + { + type: 'doc', + label: 'Remote Runtime', + id: 'usage/runtimes/remote', + }, + { + type: 'doc', + label: 'Modal Runtime', + id: 'usage/runtimes/modal', + }, + { + type: 'doc', + label: 'Daytona Runtime', + id: 'usage/runtimes/daytona', + }, + { + type: 'doc', + label: 'Local Runtime', + id: 'usage/runtimes/local', + }, + ], }, { type: 'doc',