Custom Sandbox

This guide is for users that would like to use their own custom Docker image for the runtime. For example, with certain tools or programming languages pre-installed.

This page documents legacy OpenHands V0 behavior. For the current V1 sandbox model, see Custom Sandbox (V1).

These settings are only available in Local GUI. OpenHands Cloud uses managed sandbox environments.

The sandbox is where the agent performs its tasks. Instead of running commands directly on your computer (which could be risky), the agent runs them inside a Docker container.

The default OpenHands sandbox (python-nodejs:python3.12-nodejs22 from nikolaik/python-nodejs) comes with some packages installed such as python and Node.js but may need other software installed by default.

You have two options for customization:

• Use an existing image with the required software.
• Create your own custom Docker image.

If you choose the first option, you can skip the Create Your Docker Image section.

Create Your Docker Image

To create a custom Docker image, it must be Debian based.

For example, if you want OpenHands to have ruby installed, you could create a Dockerfile with the following content:

FROM nikolaik/python-nodejs:python3.12-nodejs22

# Install required packages
RUN apt-get update && apt-get install -y ruby

Or you could use a Ruby-specific base image:

FROM ruby:latest

Save this file in a folder. Then, build your Docker image (e.g., named custom-image) by navigating to the folder in the terminal and running::

docker build -t custom-image .

This will produce a new image called custom-image, which will be available in Docker.

Using the Docker Command

When running OpenHands using the docker command, set -e SANDBOX_BASE_CONTAINER_IMAGE=<custom image name>:

docker run -it --rm --pull=always \
    -e SANDBOX_BASE_CONTAINER_IMAGE=custom-image \
    ...

Using the Development Workflow

Setup

First, ensure you can run OpenHands by following the instructions in Development.md.

Specify the Base Sandbox Image

In the config.toml file within the OpenHands directory, set the base_container_image to the image you want to use. This can be an image you’ve already pulled or one you’ve built:

[core]
...
[sandbox]
base_container_image="custom-image"

Additional Configuration Options

The config.toml file supports several other options for customizing your sandbox:

[core]
# Install additional dependencies when the runtime is built
# Can contain any valid shell commands
# If you need the path to the Python interpreter in any of these commands, you can use the $OH_INTERPRETER_PATH variable
runtime_extra_deps = """
pip install numpy pandas
apt-get update && apt-get install -y ffmpeg
"""

# Set environment variables for the runtime
# Useful for configuration that needs to be available at runtime
runtime_startup_env_vars = { DATABASE_URL = "postgresql://user:pass@localhost/db" }

# Specify platform for multi-architecture builds (e.g., "linux/amd64" or "linux/arm64")
platform = "linux/amd64"

Run

Run OpenHands by running make run in the top level directory.