From b6c9d8412d1c8503ec055a7d001b7302d9f40217 Mon Sep 17 00:00:00 2001 From: openhands Date: Tue, 9 Jun 2026 12:37:52 +0000 Subject: [PATCH 1/4] Add custom sandbox image docs for Enterprise VM (Replicated) Adds enterprise/custom-sandbox-image.mdx covering: - Why to use custom sandbox images (speed, reliability, monorepo support) - Benchmark results from Enterprise Replicated VM (up to 43x speedup) - How to build and push a custom image from the agent-server base - What to bake in and what to keep out - How to configure the custom image in the Replicated Admin Console Content sourced from https://github.com/rajshah4/openhands-custom-image Co-authored-by: openhands --- docs.json | 1 + enterprise/custom-sandbox-image.mdx | 150 ++++++++++++++++++++++++++++ 2 files changed, 151 insertions(+) create mode 100644 enterprise/custom-sandbox-image.mdx diff --git a/docs.json b/docs.json index 59df76aa..7ba6f06e 100644 --- a/docs.json +++ b/docs.json @@ -466,6 +466,7 @@ "enterprise/index", "enterprise/enterprise-vs-oss", "enterprise/quick-start", + "enterprise/custom-sandbox-image", "enterprise/analytics", "enterprise/external-postgres" ] diff --git a/enterprise/custom-sandbox-image.mdx b/enterprise/custom-sandbox-image.mdx new file mode 100644 index 00000000..89717783 --- /dev/null +++ b/enterprise/custom-sandbox-image.mdx @@ -0,0 +1,150 @@ +--- +title: Custom Sandbox Images +description: Preload repos, dependencies, and tooling into a custom sandbox image to make your agents faster and more reliable. +icon: box +--- + +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. + +## Why Use a Custom Image + + + + Agents reach the real task quickly instead of burning time on clone, install, transpile, and bootstrap steps. + + + Repo checkout, dependencies, transpiled output, and helper tooling can already be present when the agent starts. + + + Each run does not need to rediscover the same bootstrap steps, which reduces stalls, OOMs, and half-finished setups. + + + Native packages, headless browser support, Electron artifacts, and org-specific wrappers can be prebaked. + + + +## Benchmark Results + +The following benchmark ran on an Enterprise OpenHands Replicated VM and compared a stock image against +a custom image built for a VS Code bug-fix task. The agent clones a repository, bootstraps a test harness, +fixes a bug, and verifies the fix. + +| Elapsed work | Stock image | Custom image | Speedup | +|---|---:|---:|---:| +| Repo setup until available in workspace | `115.2s` | `13.1s` | **8.8x** | +| Bootstrap from repo-ready to first useful test | `581.4s` | `13.5s` | **43.1x** | +| Fix, rerun, and final response after first useful test | `152.2s` | `212.4s` | `0.7x` | +| Full end-to-end task | `848.7s` | `238.9s` | **3.6x** | + +The biggest win is eliminating cold-start setup work. In the stock run, `npm install` alone took +approximately `525s`. The custom image moved that work into Docker build time, so task time starts +with the repo and harness already prepared. + + + The **Fix, rerun, and final response** row is conversation-dependent rather than image-dependent. + Both environments can run the test at that point, so the remaining time reflects agent reasoning and + retries. The custom image still won end-to-end because it removed most of the cold setup work. + + +In this benchmark, the stock image required a **6 GB** sandbox to complete the install and test flow, +while the custom image worked at **2 GB**. + +## Build Your Own Custom Image + +The [OpenHands agent-server sandbox guide](https://docs.openhands.dev/sdk/guides/agent-server/docker-sandbox) +provides full documentation on building custom sandbox images. The approach is the same for the Enterprise +Replicated VM deployment. + +### Basic Pattern + +1. Start from the OpenHands agent-server base image. +2. Keep the normal OpenHands entrypoint intact — **extend the image; do not replace the entrypoint**. +3. Add your repo, docs, tools, and verification wrappers. +4. Pre-run the expensive setup you do not want to repeat at task time. +5. Publish the image to a registry and point the Replicated installer at it. + + + Do not override the entrypoint or replace the runtime contract of the base image. The installer + expects standard OpenHands agent-server behavior. Only extend — do not replace. + + +### Base Image + +```dockerfile +FROM ghcr.io/openhands/agent-server:1.23.0-python +``` + +Pin a specific version tag to ensure reproducible builds. Check +[ghcr.io/openhands/agent-server](https://github.com/OpenHands/OpenHands/pkgs/container/agent-server) +for the latest available tags. + +### Example: Build and Push + +```bash +docker buildx build \ + --platform linux/amd64 \ + -f your-project/Dockerfile \ + -t ghcr.io//openhands-custom-image: \ + --push \ + . +``` + +Use `--platform linux/amd64` because the Enterprise Replicated VM runs on `x86-64`. + +### What to Bake In + +Good candidates for prebaking: + +- Pinned repository checkouts +- Package manager caches and installed dependencies (`node_modules`, Python virtualenvs, etc.) +- Compiled or transpiled output +- Native system packages (`xvfb`, `libkrb5-dev`, `pkg-config`, etc.) +- Browser or Electron artifacts +- Stable helper scripts such as `prepare-*` and `*-verify` wrappers + +### What to Keep Out + + + Do not bake the following into your image: + + - Secrets, API keys, or personal credentials + - Machine-specific paths or environment assumptions + - Uncommitted source changes or task-specific fixes + - Rapidly changing dependencies (use a lightweight `prepare-*` helper instead) + + +If the repository or dependencies change frequently, include a `prepare-*` script in the image +so the agent can refresh only the parts that need updating without a full rebuild. + +## Configure the Replicated VM Installer + +Once your image is built and pushed to a registry, point the Replicated Admin Console at it. + +1. Open the **Admin Console** at `https://:30000`. +2. Navigate to **Config** and find the **Sandbox Image** section. +3. Set the following fields: + +| Field | Value | +|---|---| +| **Use a Custom Sandbox Image** | Enabled | +| **Sandbox Image Repository** | Your image repository (e.g. `ghcr.io/your-org/openhands-custom-image`) | +| **Sandbox Image Tag** | Your image tag (e.g. `v1.2.0`) | +| **Registry Server** | If your registry requires authentication | +| **Registry Username** | If your registry requires authentication | +| **Registry Password or Credentials** | If your registry requires authentication | + +4. Click **Save config** and then **Deploy** to apply the change. + + + This setting applies to the **sandbox / agent-server image** only — the image that runs inside each + agent's isolated workspace. It does not replace the other OpenHands service images. + + +## Reference + +- [OpenHands custom image example repo](https://github.com/rajshah4/openhands-custom-image) — benchmark Dockerfile, + benchmark scripts, and analysis tooling for the VS Code custom image example. +- [Agent-server sandbox guide](https://docs.openhands.dev/sdk/guides/agent-server/docker-sandbox) — full SDK + documentation on building and configuring custom sandbox images. From d8c3d5315b181ce2e24886ba62024811307c1548 Mon Sep 17 00:00:00 2001 From: openhands Date: Tue, 9 Jun 2026 12:39:41 +0000 Subject: [PATCH 2/4] Simplify custom sandbox image docs: short why section, remove benchmark results --- enterprise/custom-sandbox-image.mdx | 43 ++--------------------------- 1 file changed, 3 insertions(+), 40 deletions(-) diff --git a/enterprise/custom-sandbox-image.mdx b/enterprise/custom-sandbox-image.mdx index 89717783..381c044b 100644 --- a/enterprise/custom-sandbox-image.mdx +++ b/enterprise/custom-sandbox-image.mdx @@ -10,46 +10,9 @@ on the actual task immediately. ## Why Use a Custom Image - - - Agents reach the real task quickly instead of burning time on clone, install, transpile, and bootstrap steps. - - - Repo checkout, dependencies, transpiled output, and helper tooling can already be present when the agent starts. - - - Each run does not need to rediscover the same bootstrap steps, which reduces stalls, OOMs, and half-finished setups. - - - Native packages, headless browser support, Electron artifacts, and org-specific wrappers can be prebaked. - - - -## Benchmark Results - -The following benchmark ran on an Enterprise OpenHands Replicated VM and compared a stock image against -a custom image built for a VS Code bug-fix task. The agent clones a repository, bootstraps a test harness, -fixes a bug, and verifies the fix. - -| Elapsed work | Stock image | Custom image | Speedup | -|---|---:|---:|---:| -| Repo setup until available in workspace | `115.2s` | `13.1s` | **8.8x** | -| Bootstrap from repo-ready to first useful test | `581.4s` | `13.5s` | **43.1x** | -| Fix, rerun, and final response after first useful test | `152.2s` | `212.4s` | `0.7x` | -| Full end-to-end task | `848.7s` | `238.9s` | **3.6x** | - -The biggest win is eliminating cold-start setup work. In the stock run, `npm install` alone took -approximately `525s`. The custom image moved that work into Docker build time, so task time starts -with the repo and harness already prepared. - - - The **Fix, rerun, and final response** row is conversation-dependent rather than image-dependent. - Both environments can run the test at that point, so the remaining time reflects agent reasoning and - retries. The custom image still won end-to-end because it removed most of the cold setup work. - - -In this benchmark, the stock image required a **6 GB** sandbox to complete the install and test flow, -while the custom image worked at **2 GB**. +Custom images eliminate cold-start setup work — clone, install, transpile, and bootstrap — so agents +spend their time on the actual task. They also reduce setup variance and lower sandbox memory requirements +by keeping only what the agent needs. ## Build Your Own Custom Image From 052aff44721aca864442588ab206ce224d79ba48 Mon Sep 17 00:00:00 2001 From: openhands Date: Tue, 9 Jun 2026 12:45:00 +0000 Subject: [PATCH 3/4] Remove em dashes throughout --- enterprise/custom-sandbox-image.mdx | 16 +++++++--------- 1 file changed, 7 insertions(+), 9 deletions(-) diff --git a/enterprise/custom-sandbox-image.mdx b/enterprise/custom-sandbox-image.mdx index 381c044b..30bfee57 100644 --- a/enterprise/custom-sandbox-image.mdx +++ b/enterprise/custom-sandbox-image.mdx @@ -10,7 +10,7 @@ on the actual task immediately. ## Why Use a Custom Image -Custom images eliminate cold-start setup work — clone, install, transpile, and bootstrap — so agents +Custom images eliminate cold-start setup work (clone, install, transpile, and bootstrap) so agents spend their time on the actual task. They also reduce setup variance and lower sandbox memory requirements by keeping only what the agent needs. @@ -23,14 +23,14 @@ Replicated VM deployment. ### Basic Pattern 1. Start from the OpenHands agent-server base image. -2. Keep the normal OpenHands entrypoint intact — **extend the image; do not replace the entrypoint**. +2. Keep the normal OpenHands entrypoint intact: extend the image, do not replace the entrypoint. 3. Add your repo, docs, tools, and verification wrappers. 4. Pre-run the expensive setup you do not want to repeat at task time. 5. Publish the image to a registry and point the Replicated installer at it. Do not override the entrypoint or replace the runtime contract of the base image. The installer - expects standard OpenHands agent-server behavior. Only extend — do not replace. + expects standard OpenHands agent-server behavior. Only extend, do not replace. ### Base Image @@ -101,13 +101,11 @@ Once your image is built and pushed to a registry, point the Replicated Admin Co 4. Click **Save config** and then **Deploy** to apply the change. - This setting applies to the **sandbox / agent-server image** only — the image that runs inside each - agent's isolated workspace. It does not replace the other OpenHands service images. + This setting applies to the **sandbox / agent-server image** only (the image that runs inside each + agent's isolated workspace). It does not replace the other OpenHands service images. ## Reference -- [OpenHands custom image example repo](https://github.com/rajshah4/openhands-custom-image) — benchmark Dockerfile, - benchmark scripts, and analysis tooling for the VS Code custom image example. -- [Agent-server sandbox guide](https://docs.openhands.dev/sdk/guides/agent-server/docker-sandbox) — full SDK - documentation on building and configuring custom sandbox images. +- [OpenHands custom image example repo](https://github.com/rajshah4/openhands-custom-image): Dockerfile, benchmark scripts, and analysis tooling for the VS Code custom image example. +- [Agent-server sandbox guide](https://docs.openhands.dev/sdk/guides/agent-server/docker-sandbox): full SDK documentation on building and configuring custom sandbox images. From c5c478e76adbc66aaf2583d4cbb0a00d58003955 Mon Sep 17 00:00:00 2001 From: openhands Date: Tue, 9 Jun 2026 19:50:42 +0000 Subject: [PATCH 4/4] Address review: add upgrade note, update repo link to OpenHands org Co-authored-by: openhands --- enterprise/custom-sandbox-image.mdx | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/enterprise/custom-sandbox-image.mdx b/enterprise/custom-sandbox-image.mdx index 30bfee57..85a2da67 100644 --- a/enterprise/custom-sandbox-image.mdx +++ b/enterprise/custom-sandbox-image.mdx @@ -43,6 +43,10 @@ Pin a specific version tag to ensure reproducible builds. Check [ghcr.io/openhands/agent-server](https://github.com/OpenHands/OpenHands/pkgs/container/agent-server) for the latest available tags. + + To get the latest features of OpenHands Enterprise, rebuild your custom image before each upgrade. The agent server base image is updated with every OHE release. + + ### Example: Build and Push ```bash @@ -107,5 +111,5 @@ Once your image is built and pushed to a registry, point the Replicated Admin Co ## Reference -- [OpenHands custom image example repo](https://github.com/rajshah4/openhands-custom-image): Dockerfile, benchmark scripts, and analysis tooling for the VS Code custom image example. +- [OpenHands custom image example repo](https://github.com/OpenHands/openhands-custom-image): Dockerfile, benchmark scripts, and analysis tooling for the VS Code custom image example. - [Agent-server sandbox guide](https://docs.openhands.dev/sdk/guides/agent-server/docker-sandbox): full SDK documentation on building and configuring custom sandbox images.