> ## Documentation Index
> Fetch the complete documentation index at: https://allhandsai-docs-observability-span-signals.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Custom Sandbox

> Build and use your own agent-server image when you need extra tools, system packages, or language runtimes pre-installed in the sandbox.

<Note>
  These settings are only available in [Local GUI](/openhands/usage/run-openhands/local-setup). OpenHands Cloud uses managed sandbox environments.
</Note>

<Note>
  Looking for the legacy `SANDBOX_BASE_CONTAINER_IMAGE` / `base_container_image`
  workflow? That only applies to OpenHands V0. See the
  [V0 Custom Sandbox reference](/openhands/usage/v0/advanced/V0_custom-sandbox-guide).
</Note>

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](https://github.com/OpenHands/software-agent-sdk/blob/main/openhands-agent-server/openhands/agent_server/docker/Dockerfile)
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 theme={null}
# Dockerfile.base
FROM nikolaik/python-nodejs:python3.12-nodejs22

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

```bash theme={null}
docker build -t my-base:latest -f Dockerfile.base .
```

Then build the agent-server image on top of it. Clone the
[OpenHands SDK](https://github.com/OpenHands/software-agent-sdk) and, from the repository root, run:

```bash theme={null}
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:

```bash theme={null}
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:

```yaml theme={null}
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.

<Note>
  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.
</Note>

## Related

* [Docker Sandbox](/openhands/usage/sandboxes/docker) — the default sandbox provider for Local GUI.
* [Agent Server in Docker (SDK)](/sdk/guides/agent-server/docker-sandbox) — deeper details on the
  agent-server image and how it is built.