Skip to main content

Custom Sandbox

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.

Note that in the configuration described in this document, OpenHands will run as user "openhands" inside the sandbox and thus all packages installed via the docker file should be available to all users on the system, not just root.

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