This skill should be used when the user asks to "update SDK", "bump SDK version", "pin SDK to a commit", "test unreleased SDK", "update agent-server image", "bump the version", "prepare a release", "what files change for a release", or needs to know how SDK packages are managed in the OpenHands repository. For detailed reference material, see references/docker-image-locations.md and references/sdk-pinning-examples.md in this skill directory.
Bump SDK packages (openhands-sdk, openhands-agent-server, openhands-tools), pin them to unreleased commits for testing, and cut an OpenHands release.
| Activity | Manual edits | Auto-regenerated | Total |
|---|---|---|---|
| SDK bump (released PyPI version) | 2 | 3 | 5 |
| SDK pin (unreleased git commit) | 3 | 3 | 6 |
| Release commit (version bump) | 3 | 0 | 3 |
The 3 auto-regenerated files are always: poetry.lock, uv.lock, .
enterprise/poetry.lockLand as a separate PR before the release. Examples: 929dcc3 (SDK 1.11.5), cd235cc (SDK 1.11.4).
| File | What to change |
|---|---|
pyproject.toml | openhands-sdk, openhands-agent-server, openhands-tools in two sections: the dependencies array (PEP 508) and [tool.poetry.dependencies] |
openhands/app_server/sandbox/sandbox_spec_service.py | AGENT_SERVER_IMAGE constant — set to ghcr.io/openhands/agent-server:<version>-python |
Then regenerate lock files:
poetry lock && uv lock && cd enterprise && poetry lock && cd ..
For the complete inventory of every file containing a hardcoded Docker image tag or repository, see references/docker-image-locations.md. Key files that must stay in sync during an SDK bump:
| File | Image reference | Updated during SDK bump? |
|---|---|---|
openhands/app_server/sandbox/sandbox_spec_service.py | AGENT_SERVER_IMAGE = 'ghcr.io/openhands/agent-server:<tag>-python' | ✅ Yes |
docker-compose.yml | AGENT_SERVER_IMAGE_TAG default | ✅ Should be |
containers/dev/compose.yml | AGENT_SERVER_IMAGE_REPOSITORY + _TAG defaults | ✅ Should be |
CI enforcement:
.github/workflows/check-version-consistency.ymlvalidates version consistency and compose file image references on every PR and push to main.
The SDK CI in software-agent-sdk repo tags Docker images with the GitHub Actions merge-commit SHA, NOT the PR head-commit SHA. When pinning to an SDK PR branch:
AGENT_SERVER_IMAGES section)"short_sha": "<tag>"For released SDK versions, images use a version tag (e.g., 1.12.0-python) — no merge-commit ambiguity.
A release commit updates the version string across 3 files. Gold-standard examples: 1.3.0 (d063c8c), 1.4.0 (495f48b).
| File | What to change |
|---|---|
pyproject.toml | version = "X.Y.Z" under [tool.poetry] |
frontend/package.json | "version": "X.Y.Z" |
frontend/package-lock.json | "version": "X.Y.Z" in two places (root object and packages[""]) |
Note:
openhands/version.pyreads the version frompyproject.tomlat runtime — no manual edit needed there.
Both compose files should use ghcr.io/openhands/agent-server with the current SDK version tag.
| File | What to verify |
|---|---|
docker-compose.yml | AGENT_SERVER_IMAGE_REPOSITORY defaults to agent-server, AGENT_SERVER_IMAGE_TAG is current |
containers/dev/compose.yml | Same — must use agent-server, not runtime |
grep -n "openhands-sdk\|openhands-agent-server\|openhands-tools" pyproject.toml
grep -n "AGENT_SERVER_IMAGE" openhands/app_server/sandbox/sandbox_spec_service.py
grep "AGENT_SERVER_IMAGE_TAG" docker-compose.yml containers/dev/compose.yml
# Edit pyproject.toml, frontend/package.json, frontend/package-lock.json
git add pyproject.toml frontend/package.json frontend/package-lock.json
git commit -m "Release X.Y.Z"
git tag X.Y.Z
Create a saas-rel-X.Y.Z branch from the tagged commit for the SaaS deployment pipeline.
The ghcr-build.yml workflow triggers on tag pushes and produces:
ghcr.io/openhands/openhands:X.Y.Z, X.Y, X, latestghcr.io/openhands/runtime:X.Y.Z-nikolaik, X.Y-nikolaikThe tagging logic lives in containers/build.sh — when GITHUB_REF_NAME matches a semver pattern (^[0-9]+\.[0-9]+\.[0-9]+$), it auto-generates major, major.minor, and latest tags.
For detailed examples of all pinning formats (commit, branch, uv-only), see references/sdk-pinning-examples.md.
| File | What to change |
|---|---|
pyproject.toml | Pin all 3 SDK packages in both dependencies and [tool.poetry.dependencies] |
openhands/app_server/sandbox/sandbox_spec_service.py | AGENT_SERVER_IMAGE — use the merge-commit SHA tag, NOT the head-commit SHA |
docker-compose.yml | AGENT_SERVER_IMAGE_TAG default (for local development) |
poetry.lock | Auto-regenerated via poetry lock |
uv.lock | Auto-regenerated via uv lock |
enterprise/poetry.lock | Auto-regenerated via cd enterprise && poetry lock |
The check-package-versions.yml workflow blocks merging to main if [tool.poetry.dependencies] contains any rev fields. This ensures unreleased SDK pins do not accidentally ship in a release.