From 0fd022d1e97b92a21a1ba9c364d747f9635d17a7 Mon Sep 17 00:00:00 2001 From: Alona King Date: Mon, 24 Aug 2026 13:12:15 -0400 Subject: [PATCH] docs: refresh custom sandbox image base tag and document version compatibility --- enterprise/custom-sandbox-image.mdx | 19 +++++++++++++++++-- 1 file changed, 17 insertions(+), 2 deletions(-) diff --git a/enterprise/custom-sandbox-image.mdx b/enterprise/custom-sandbox-image.mdx index 692f59db0..0c74aca5c 100644 --- a/enterprise/custom-sandbox-image.mdx +++ b/enterprise/custom-sandbox-image.mdx @@ -36,15 +36,30 @@ Replicated VM deployment. ### Base Image ```dockerfile -FROM ghcr.io/openhands/agent-server:1.23.0-python +FROM ghcr.io/openhands/agent-server:1.41.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. +### Version Compatibility + +Each OpenHands Enterprise release expects a specific agent-server version. The base image tag you +build from must match the release you run: the `openhands-sdk` inside the sandbox and the one inside +the OpenHands application must agree on major and minor version. + +To find the expected tag, enable **Use a Custom Sandbox Image** in the Admin Console. The +**Sandbox Image Tag** field defaults to the tag the current release expects. + +When a conversation starts on a custom image, OpenHands checks the sandbox's agent-server version. +If it does not match the release, the conversation fails with an error naming the expected and +actual versions. Rebuild your image from the expected tag and update the **Sandbox Image Tag** +field to fix it. + - 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. + Rebuild your custom image before each upgrade. The agent-server base image changes with every + OHE release, and an image built for an older release will be rejected by the version check. ### Example: Build and Push