docs: rewrite Custom Sandbox guide for v1, archive v0 content

[VascoSch92]

Problem

usage/advanced/custom-sandbox-guide.mdx ("Custom Sandbox") was never migrated from v0. It lives in the current docs tree (Local GUI → Advanced), has no version banner, and is linked from the v1 Docker sandbox page — yet it documents v0-only settings that don't exist in 1.x:

• -e SANDBOX_BASE_CONTAINER_IMAGE=custom-image
• base_container_image="custom-image" in config.toml
• the v0 default image nikolaik/python-nodejs:python3.12-nodejs22

SANDBOX_BASE_CONTAINER_IMAGE is read nowhere in v1, so the custom image is silently ignored and users hit Sandbox failed to start (reported in OpenHands/OpenHands#15018).

Changes

Per the issue, this both archives the v0 content and puts a correct v1 guide in place:

• Rewrote usage/advanced/custom-sandbox-guide.mdx for v1. In v1 the sandbox container is the agent-server, so customization means building a custom agent-server image on top of your base via --build-arg BASE_IMAGE= against the SDK Dockerfile, then pointing OpenHands at it with AGENT_SERVER_IMAGE_REPOSITORY / AGENT_SERVER_IMAGE_TAG.
• Moved the original v0 content to usage/v0/advanced/V0_custom-sandbox-guide.mdx and added it to the V0 Reference group in docs.json, with the standard legacy banner.
• Updated the V0 Docker runtime page link to point at the new V0 reference page.

The link in usage/sandboxes/docker.mdx keeps the same path and now resolves to the corrected v1 guide.

Verification

• v1 facts checked against source: get_agent_server_image() resolves AGENT_SERVER_IMAGE_REPOSITORY+AGENT_SERVER_IMAGE_TAG (default ghcr.io/openhands/agent-server:<release>-python); the agent-server Dockerfile accepts ARG BASE_IMAGE; the container runs on port 8000 and is polled at /health.
• docs.json is valid JSON.
• mint broken-links reports no new broken links (the 2 pre-existing ones are in untouched SDK files).

Closes #597

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
all-hands-ai	🟢 Ready	View Preview	Jun 29, 2026, 9:49 AM

💡 Tip: Enable Workflows to automatically generate PRs for you.

[all-hands-bot]

✅ Review complete.

This review was performed through OpenHands Cloud Automation. You can log in and view the conversation here.

[all-hands-bot]

🟡 Taste Rating: Acceptable — The V0 archive plus V1 replacement is the right structure, but one source-verified accuracy issue needs correction before merge.

[CRITICAL ISSUES]

• [openhands/usage/advanced/custom-sandbox-guide.mdx, Line 67] Docs Accuracy: The guide says --target source matches the default -python image, but the SDK publishes the python variant with TARGET: binary, and build.py defaults to binary. Fix the command/prose to use --target binary as the default-equivalent build, or explicitly describe source as a dev/debug alternative.

[IMPROVEMENT OPPORTUNITIES]

• [Overall PR] Stale entry points: This PR fixes the main Custom Sandbox page, but there are still unversioned/current docs references that can send users toward old sandbox-image terminology (openhands/usage/environment-variables.mdx lists SANDBOX_BASE_CONTAINER_IMAGE, and openhands/usage/run-openhands/github-action.mdx links “Custom Sandbox” from OPENHANDS_BASE_CONTAINER_IMAGE). If those are valid for a separate product path, add product/version-specific wording; otherwise this leaves another path to the broken V0-era guidance.

Source Verification

Documentation claim	Verified?	Source evidence
V1 resolves the default/custom agent-server image from AGENT_SERVER_IMAGE_REPOSITORY + AGENT_SERVER_IMAGE_TAG, falling back when either is absent	✅	sandbox_spec_service.py#L101-L106
Docker sandbox exposes the agent server on container port 8000 and uses /health for readiness	✅	docker_sandbox_service.py#L605-L638, docker_sandbox_service.py#L254-L257
SDK Dockerfile accepts ARG BASE_IMAGE and has source / binary agent-server targets	✅	Dockerfile#L6-L7, Dockerfile#L350-L372
--target source matches the default published -python image	❌	The publish workflow sets TARGET: binary for the image matrix (server.yml#L317-L324), and build.py makes binary the default target (build.py#L386, build.py#L536-L538).

[TESTING GAPS]

• CI status is healthy for the docs checks I inspected: Mintlify deployment, Mintlify internal links, and Mintlify link-rot all passed. No additional runtime test is required for this docs-only PR, but the incorrect source claim above should be fixed.

[RISK ASSESSMENT]

• [Overall PR] ⚠️ Risk Assessment: 🟡 MEDIUM
  This is documentation-only and has passing docs checks, but it is user-facing setup guidance for custom sandbox images. A wrong build-target/default-image claim can lead users to build and maintain a non-default agent-server image shape, so the accuracy issue should be fixed before merge.

VERDICT:
❌ Needs rework: The structure is sound, but the default image/build target mismatch needs correction first.

KEY INSIGHT:
The PR correctly moves users from V0 runtime-image customization to V1 agent-server image customization, but the V1 guide must mirror the actual published binary image pipeline.

Improve this review? If any feedback above seems incorrect or irrelevant to this repository, you can teach the reviewer to do better:

1. Add a .agents/skills/custom-codereview-guide.md file to your branch (or edit it if one already exists) with the /codereview trigger and the context the reviewer is missing. See the customization docs for the required frontmatter format.
2. Re-request a review - the reviewer reads guidelines from the PR branch, so your changes take effect immediately.
3. When your PR is merged, the guideline file goes through normal code review by repository maintainers.

Resolve with AI? Install the iterate skill in your agent and run /iterate to automatically drive this PR through CI, review, and QA until it's merge-ready.

Was this review helpful? React with 👍 or 👎 to give feedback.

This review was generated by an AI agent (OpenHands) on behalf of the user through OpenHands Automation. View conversation

[VascoSch92]

Fixed the critical accuracy issue in 824988f.

The build command now uses --target binary to match how the default published <release>-python image is actually built — verified against the SDK: server.yml sets TARGET: binary for the whole publish matrix (with CUSTOM_TAGS: <variant>, so the python variant → <version>-python tag), and build.py defaults target to binary and only suffixes non-binary targets. The prose now describes source (runs from a Python venv; dev/debug) and the *-minimal targets (no VSCode/VNC) as alternatives.

Re: the stale-entry-points improvement — SANDBOX_BASE_CONTAINER_IMAGE in environment-variables.mdx and the OPENHANDS_BASE_CONTAINER_IMAGE "Custom Sandbox" link in github-action.mdx are outside the scope of #597. Happy to clean those up in a follow-up if desired.