OpenHands/.agents/skills/update-sdk/references/docker-image-locations.md

Docker Image Locations — Complete Inventory

Every file in the OpenHands repository containing a hardcoded Docker image tag, repository, or version-pinned image reference. Organized by update cadence.

Updated During SDK Bump (must change)

These files contain image tags that must be updated whenever the SDK version or pinned commit changes.

openhands/app_server/sandbox/sandbox_spec_service.py

• Line: AGENT_SERVER_IMAGE = 'ghcr.io/openhands/agent-server:<tag>-python'
• Format: <sdk-version>-python for releases (e.g., 1.12.0-python), <7-char-commit-hash>-python for dev pins
• Source of truth for which agent-server image the app server pulls at runtime
• ⚠️ Gotcha: When pinning to an SDK PR, the image tag is the merge-commit SHA from GitHub Actions, not the PR head-commit SHA. Check the SDK PR description or CI logs for the correct tag.

docker-compose.yml

• Lines:

  - AGENT_SERVER_IMAGE_REPOSITORY=${AGENT_SERVER_IMAGE_REPOSITORY:-ghcr.io/openhands/agent-server}
  - AGENT_SERVER_IMAGE_TAG=${AGENT_SERVER_IMAGE_TAG:-<tag>-python}
  

• Used by docker compose up for local development

containers/dev/compose.yml

• Lines:

  - AGENT_SERVER_IMAGE_REPOSITORY=${AGENT_SERVER_IMAGE_REPOSITORY:-ghcr.io/openhands/agent-server}
  - AGENT_SERVER_IMAGE_TAG=${AGENT_SERVER_IMAGE_TAG:-<tag>-python}
  

• Used by the dev container setup
• Known issue: On main as of 1.4.0, this file still points to ghcr.io/openhands/runtime instead of agent-server, and the tag is 1.2-nikolaik (stale from the V0 era). The check-version-consistency.yml CI workflow catches this.

Updated During Release Commit (version string only)

pyproject.toml

• Line: version = "X.Y.Z" under [tool.poetry]
• The Python version is derived from this at runtime via openhands/version.py

frontend/package.json

• Line: "version": "X.Y.Z"

frontend/package-lock.json

• Two places: root "version": "X.Y.Z" and packages[""].version

Dynamic References (auto-derived, no manual update)

openhands/version.py

• Reads version from pyproject.toml at runtime → openhands.__version__

openhands/resolver/issue_resolver.py

• Builds ghcr.io/openhands/runtime:{openhands.__version__}-nikolaik dynamically

openhands/runtime/utils/runtime_build.py

• Base repo URL ghcr.io/openhands/runtime is a constant; version comes from elsewhere

.github/scripts/update_pr_description.sh

• Uses ${SHORT_SHA} variable at CI runtime, not hardcoded

enterprise/Dockerfile

• ARG BASE="ghcr.io/openhands/openhands" — base image, version supplied at build time

V0 Legacy Files (separate update cadence)

These reference the V0 runtime image (ghcr.io/openhands/runtime:X.Y-nikolaik) for local Docker/Kubernetes paths. They are not updated as part of a V1 release but may be updated independently.

Development.md

• export SANDBOX_RUNTIME_CONTAINER_IMAGE=ghcr.io/openhands/runtime:X.Y-nikolaik

openhands/runtime/impl/kubernetes/README.md

• runtime_container_image = "docker.openhands.dev/openhands/runtime:X.Y-nikolaik"

enterprise/enterprise_local/README.md

• Uses ghcr.io/openhands/runtime:main-nikolaik (points to main, not versioned)

third_party/runtime/impl/daytona/README.md

• Uses ${OPENHANDS_VERSION} variable, not hardcoded

Image Registries

Registry	Usage
ghcr.io/openhands/agent-server	V1 agent-server (sandbox) — built by SDK repo CI
ghcr.io/openhands/openhands	Main app image — built by ghcr-build.yml
ghcr.io/openhands/runtime	V0 runtime sandbox — built by ghcr-build.yml
docker.openhands.dev/openhands/*	Mirror/CDN for the above images