Add custom sandbox image docs for Enterprise VM (Replicated)

docs.json

@@ -466,6 +466,7 @@
               "enterprise/index",
               "enterprise/enterprise-vs-oss",
               "enterprise/quick-start",
+              "enterprise/custom-sandbox-image",
               "enterprise/analytics",
               "enterprise/external-postgres"
             ]

enterprise/custom-sandbox-image.mdx

@@ -0,0 +1,115 @@
+---
+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
+
+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
+
+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.
+
+<Warning>
+  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.
+</Warning>
+
+### 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.
+
+<Note>
+  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.
+</Note>
+
+### Example: Build and Push
+
+```bash
+docker buildx build \
+  --platform linux/amd64 \
+  -f your-project/Dockerfile \
+  -t ghcr.io/<your-org>/openhands-custom-image:<your-tag> \
+  --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
+
+<Warning>
+  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)
+</Warning>
+
+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://<your-base-domain>: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.
+
+<Note>
+  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.
+</Note>
+
+## Reference
+
+- [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.