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

# Custom Sandbox Images

> Prebake your repository, dependencies, and tooling into custom sandbox images so agents start on the actual task instead of spending time on setup.

Custom sandbox images let you prebake the repository, dependencies, compiled
output, and test harness your agents need. Instead of spending minutes
provisioning a workspace on every run, your agents start on the actual task
immediately.

## How Sandbox Pools Work

Each custom sandbox image can be kept ready in its own **pool** of
pre-started sandboxes (called warm runtime pools internally). When a user
starts a conversation, it claims a waiting sandbox from the pool in seconds
instead of cold-starting one from scratch (which takes 20 seconds or more).
Each configuration names one image and a pool size; a reconciler runs every
minute to maintain that count. Multiple pools run side by side, each
independently selectable by users.

## Prerequisites

Before configuring any custom image, the following must be in place:

**An image registry reachable from your OpenHands cluster.** The cluster must
be able to pull your custom image at pod start time. Public registries (GitHub
Container Registry, Docker Hub) work without extra configuration. Private
registries require credentials — either set via **Config → Sandbox
Configuration → Registry Server / Username / Password** in the Admin Console,
or via the `RUNTIME_IMAGE_PULL_SECRETS` setting on Helm installs.

**A custom image built from the correct agent-server base.** See
[Building a Custom Image](/enterprise/custom-sandbox-images/building-custom-images).
The image must be pushed to your registry before you configure it.

**OpenHands Enterprise 0.64.0 or later** for the warm runtime pool approach.

**`kubectl` access** for initial setup, with different requirements by install type:

* **Replicated VM installs:** kubectl is needed once to read the initial
  credentials. After that the management script calls the runtime-api HTTPS
  endpoint directly and can run from any machine without cluster access.
* **Helm installs:** kubectl is required for every management operation.
  Use your normal kubeconfig.

## Configuration Approaches

<CardGroup cols={2}>
  <Card title="Configuring Custom Sandbox Images" icon="layer-group" href="/enterprise/custom-sandbox-images/multiple-images-warm-pools">
    One warm pool per image, selectable per user. Changes take effect within a
    minute with no restarts. **Recommended.**
  </Card>

  <Card title="Single Image via Admin Console" icon="triangle-exclamation" href="/enterprise/custom-sandbox-images/single-image-admin-console">
    **Deprecated.** Configures one image for the whole installation via the
    Replicated Admin Console. Superseded by the warm runtime pool approach.
  </Card>
</CardGroup>

## Reference

<CardGroup cols={2}>
  <Card title="Building a Custom Image" icon="docker" href="/enterprise/custom-sandbox-images/building-custom-images">
    Dockerfile pattern, version pinning, and what to bake in
  </Card>

  <Card title="Using Custom Images" icon="play" href="/enterprise/custom-sandbox-images/using-custom-images">
    How users select an image and how to target one via the API
  </Card>

  <Card title="Conversations and Sandboxes" icon="comments" href="/enterprise/conversations-and-sandboxes">
    How conversations, sandboxes, and their lifecycle fit together
  </Card>

  <Card title="Sizing Guide" icon="gauge-high" href="/enterprise/sizing-guide">
    Capacity planning, including headroom for warm pools
  </Card>
</CardGroup>