Skip to content

Refresh custom sandbox image base tag and document version compatibility #755

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
ak684 merged 1 commit into from
Aug 24, 2026
Merged

Refresh custom sandbox image base tag and document version compatibility #755

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
19 changes: 17 additions & 2 deletions enterprise/custom-sandbox-image.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
title: Custom Sandbox Images
description: Preload repos, dependencies, and tooling into a custom sandbox image to make your agents faster and more reliable.

Check warning on line 3 in enterprise/custom-sandbox-image.mdx

View check run for this annotation

Mintlify / Mintlify Validation (allhandsai) - vale-spellcheck

enterprise/custom-sandbox-image.mdx#L3 

Did you really mean 'Preload'?

Check warning on line 3 in enterprise/custom-sandbox-image.mdx

View check run for this annotation

Mintlify / Mintlify Validation (allhandsai) - vale-spellcheck

enterprise/custom-sandbox-image.mdx#L3 

Did you really mean 'repos'?
icon: box
---

Expand All @@ -10,7 +10,7 @@

## Why Use a Custom Image

Custom images eliminate cold-start setup work (clone, install, transpile, and bootstrap) so agents

Check warning on line 13 in enterprise/custom-sandbox-image.mdx

View check run for this annotation

Mintlify / Mintlify Validation (allhandsai) - vale-spellcheck

enterprise/custom-sandbox-image.mdx#L13 

Did you really mean 'transpile'?
spend their time on the actual task. They also reduce setup variance and lower sandbox memory requirements
by keeping only what the agent needs.

Expand All @@ -36,15 +36,30 @@
### 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)

@jpshackelford jpshackelford Aug 24, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think we may be able to refer customers to the release notes page to find the correct version of the agent-server for their release. If the release notes don't have that today it should be a simple fix to @mamoodi's automation to be sure it gets there.

@jpshackelford jpshackelford Aug 24, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

See https://docs.openhands.dev/enterprise/release-notes

@ak684 ak684 Aug 24, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Agreed. The release notes don't list component versions today, but the ohe-release-notes skill already derives the agent-server tag in step 1b/1c and just doesn't write it to the page, so emitting a per-release component table should be a small template change. I'll keep the Admin Console Sandbox Image Tag pointer (it's what customers see while configuring) and add a link to the release notes once the table is there. @mamoodi one note: the skill reads the agent-server tag from runtime-api/values.yaml; on main the pin now lives at charts/openhands/values.yaml → global.agentServerImage.tag, and the notes should print the full X.Y.Z-python tag.

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.

<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.
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.
</Note>

### Example: Build and Push
Expand All @@ -62,11 +77,11 @@

### What to Bake In

Good candidates for prebaking:

Check warning on line 80 in enterprise/custom-sandbox-image.mdx

View check run for this annotation

Mintlify / Mintlify Validation (allhandsai) - vale-spellcheck

enterprise/custom-sandbox-image.mdx#L80 

Did you really mean 'prebaking'?

- Pinned repository checkouts
- Package manager caches and installed dependencies (`node_modules`, Python virtualenvs, etc.)

Check warning on line 83 in enterprise/custom-sandbox-image.mdx

View check run for this annotation

Mintlify / Mintlify Validation (allhandsai) - vale-spellcheck

enterprise/custom-sandbox-image.mdx#L83 

Did you really mean 'virtualenvs'?
- Compiled or transpiled output

Check warning on line 84 in enterprise/custom-sandbox-image.mdx

View check run for this annotation

Mintlify / Mintlify Validation (allhandsai) - vale-spellcheck

enterprise/custom-sandbox-image.mdx#L84 

Did you really mean 'transpiled'?
- Native system packages (`xvfb`, `libkrb5-dev`, `pkg-config`, etc.)
- Browser or Electron artifacts
- Stable helper scripts such as `prepare-*` and `*-verify` wrappers
Expand Down Expand Up @@ -111,5 +126,5 @@

## 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.

Check warning on line 129 in enterprise/custom-sandbox-image.mdx

View check run for this annotation

Mintlify / Mintlify Validation (allhandsai) - vale-spellcheck

enterprise/custom-sandbox-image.mdx#L129 

Did you really mean 'Dockerfile'?
- [Agent-server sandbox guide](https://docs.openhands.dev/sdk/guides/agent-server/docker-sandbox): full SDK documentation on building and configuring custom sandbox images.
Loading