Skip to main content
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. 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

Configuring Custom Sandbox Images

One warm pool per image, selectable per user. Changes take effect within a minute with no restarts. Recommended.

Single Image via Admin Console

Deprecated. Configures one image for the whole installation via the Replicated Admin Console. Superseded by the warm runtime pool approach.

​
Reference

Building a Custom Image

Dockerfile pattern, version pinning, and what to bake in

Using Custom Images

How users select an image and how to target one via the API

Conversations and Sandboxes

How conversations, sandboxes, and their lifecycle fit together

Sizing Guide

Capacity planning, including headroom for warm pools