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).

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.27-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.

One useful feature here is the ability to connect to your local filesystem. To mount your filesystem into the runtime:

1. Set WORKSPACE_BASE:

   export WORKSPACE_BASE=/path/to/your/code
   
   # Linux and Mac Example
   # export WORKSPACE_BASE=$HOME/OpenHands
   # Will set $WORKSPACE_BASE to /home/<username>/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:

   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.

The All Hands Runtime is currently in beta. You can request access by joining the #remote-runtime-limited-beta channel on Slack (see the README for an invite).

To use the All Hands Runtime, set the following environment variables when starting OpenHands:

docker run # ...
    -e RUNTIME=remote \
    -e SANDBOX_REMOTE_RUNTIME_API_URL="https://runtime.app.all-hands.dev" \
    -e SANDBOX_API_KEY="your-all-hands-api-key" \
    -e SANDBOX_KEEP_RUNTIME_ALIVE="true" \
    # ...

Our partners at Modal have also provided a runtime for OpenHands.

To use the Modal Runtime, create an account, and then create an API key.

You'll then need to set the following environment variables when starting OpenHands:

docker run # ...
    -e RUNTIME=modal \
    -e MODAL_API_TOKEN_ID="your-id" \
    -e MODAL_API_TOKEN_SECRET="your-secret" \

Another option is using Daytona as a runtime provider:

1. Visit the Daytona Dashboard.
2. Click "Create Key".
3. Enter a name for your key and confirm the creation.
4. Once the key is generated, copy it.

Run the following command in your terminal, replacing <your-api-key> with the actual key you copied:

export DAYTONA_API_KEY="<your-api-key>"

This step ensures that OpenHands can authenticate with the Daytona platform when it runs.

To start the latest version of OpenHands on your machine, execute the following command in your terminal:

bash -i <(curl -sL https://get.daytona.io/openhands)

• 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