Skip to main content
These settings are only available in Local GUI. OpenHands Cloud uses managed sandbox environments.
Looking for the legacy SANDBOX_BASE_CONTAINER_IMAGE / base_container_image workflow? That only applies to OpenHands V0. See the V0 Custom Sandbox reference.
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.

​
How the sandbox works in V1

In OpenHands V1 the sandbox container is the OpenHands agent-server. By default OpenHands runs ghcr.io/openhands/agent-server:<release>-python, which already includes Python and Node.js. The image is resolved from two environment variables:
  • AGENT_SERVER_IMAGE_REPOSITORY (default ghcr.io/openhands/agent-server)
  • AGENT_SERVER_IMAGE_TAG (default <release>-python)
Because the sandbox is the agent-server, you can’t just swap in an arbitrary base image — the container has to keep running the agent-server. To add custom tooling you build a custom agent-server image on top of your chosen base image, then point OpenHands at it.

​
Building a custom agent-server image

The agent-server is built from a Dockerfile in the OpenHands SDK that accepts a BASE_IMAGE build argument. Any Debian-based image works as the base. For example, to layer the agent-server onto an image that has ruby installed, first build (or pick) your base image. To build one: 
# Dockerfile.base
FROM nikolaik/python-nodejs:python3.12-nodejs22

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

docker build -t my-base:latest -f Dockerfile.base .
Then build the agent-server image on top of it. Clone the OpenHands SDK and, from the repository root, run: 
docker buildx build \
  --build-arg BASE_IMAGE=my-base:latest \
  --target binary \
  -f openhands-agent-server/openhands/agent_server/docker/Dockerfile \
  -t my-agent-server:custom \
  --load \
  .
  • --build-arg BASE_IMAGE= selects the base image to layer the agent-server onto.
  • --target binary matches how the default published -python image is built — it bundles a self-contained agent-server binary (no Python virtual environment at runtime) and includes VSCode and VNC. Other targets are available if you need them: source runs the agent-server from a Python virtual environment (handy for development and debugging), and the binary-minimal / source-minimal targets drop VSCode and VNC for a smaller image.
  • --load makes the resulting image available to your local Docker daemon.
This produces a local image called my-agent-server:custom.

​
Pointing OpenHands at your image

Set both environment variables so OpenHands launches your image as the sandbox. They must be set together — if either is missing, OpenHands falls back to the default image: 
docker run -it --rm --pull=always \
    -e AGENT_SERVER_IMAGE_REPOSITORY=my-agent-server \
    -e AGENT_SERVER_IMAGE_TAG=custom \
    ...
If you start OpenHands with Docker Compose, set the same variables there: 
environment:
  - AGENT_SERVER_IMAGE_REPOSITORY=my-agent-server
  - AGENT_SERVER_IMAGE_TAG=custom
When the sandbox starts, OpenHands launches your image on port 8000 and polls /health until the agent-server is ready.
When you publish your image to a registry, set AGENT_SERVER_IMAGE_REPOSITORY to the fully qualified repository (e.g. ghcr.io/your-org/my-agent-server) and make sure the host running OpenHands can pull it.