fix(images): prefer versioned sandbox base images

[ericksoa]

Summary

• publish sandbox-base and hermes-sandbox-base images with release version tags on v* tag pushes
• make sandbox base resolution try matching version tags from install refs, exact git tags, or .version before falling back to SHA/latest
• add focused tests for versioned base-image tag derivation

Validation

• npm run build:cli
• npx vitest run src/lib/sandbox-base-image.test.ts
• npx @biomejs/biome check src/lib/sandbox-base-image.ts src/lib/sandbox-base-image.test.ts
• git diff --check
• extracted .github/actions/resolve-sandbox-base-image/action.yaml shell body and ran bash -n

Fixes #4080

Summary by CodeRabbit

• New Features

  • Support for versioned Docker image tags derived from Git release tags and a .version file, used when selecting sandbox base images.
  • Workflows now run on Git tag pushes and include tag-derived image metadata.

• Improvements

  • Sandbox resolver prefers version-tag candidates before SHA-based fallbacks.
  • Increased robustness of container runtime detection with an explicit probe timeout.

• Tests

  • Added tests covering versioned image tag derivation and selection.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 23c2a84a-9e5f-4bc0-8267-483bd142170f

📥 Commits

Reviewing files that changed from the base of the PR and between 0d953e6 and e54ca5a.

📒 Files selected for processing (2)

• src/lib/inference/local.ts
• src/lib/onboard/local-inference-topology.ts

---

📝 Walkthrough

Walkthrough

Adds discovery and normalization of release-style version tags (env, git exact-match, .version), publishes tags on v* push events, and makes the sandbox resolver prefer versioned GHCR images before falling back to SHA/latest. Also bounds dockerInfo runtime probes with a short timeout.

Changes

Version-tagged sandbox base image support

Layer / File(s)	Summary
Version tag normalization and discovery (TypeScript) src/lib/sandbox-base-image.ts, src/lib/sandbox-base-image.test.ts	Adds fs import, extends SandboxBaseImageResolution.source with "version-tag", implements normalization/derivation helpers and exported getVersionedBaseImageTags() aggregating env/git/.version candidates; adds tests for pinned-ref, .version normalization, and git-release-only selection.
Resolver integration for version tags src/lib/sandbox-base-image.ts	resolveSandboxBaseImage() iterates over getVersionedBaseImageTags() and attempts image:<tag> pulls with source: "version-tag" before existing SHA-based attempts.
CI workflow publishing of versioned tags .github/workflows/base-image.yaml	Adds push.tags filter for v* and extends docker/metadata-action tag generation to include tags from tag events for base-image and hermes-base-image jobs.
GitHub action version tag normalization .github/actions/resolve-sandbox-base-image/action.yaml	Adds normalize_version_tag bash helper (strip prefixes, validate, canonicalize to v<version>), and extends candidates to try normalized tags from GITHUB_REF, git describe --tags --exact-match, and .version before SHA fallbacks.
Docker runtime probe timeout src/lib/inference/local.ts, src/lib/onboard/local-inference-topology.ts	Introduce DOCKER_INFO_RUNTIME_PROBE_TIMEOUT_MS (1500ms), add ContainerRuntime type import, and call dockerInfo({ ignoreError: true, timeout }), casting result to ContainerRuntime for subsequent port selection.

Sequence Diagram

sequenceDiagram
  participant CI as "CI Workflow (push tag v*)"
  participant Metadata as "docker/metadata-action"
  participant GHCR as "GHCR (ghcr.io/nvidia/nemoclaw)"
  participant Resolver as "resolveSandboxBaseImage()"
  participant Tags as "getVersionedBaseImageTags()"
  participant Git as "git describe / GITHUB_REF / .version"

  CI->>Metadata: emit metadata tags (include type=ref,event=tag)
  Metadata->>GHCR: publish image:<tag>
  Resolver->>Tags: request normalized version candidates
  Tags->>Git: read GITHUB_REF, git describe, .version
  Tags->>Resolver: return normalized, deduped tags[]
  Resolver->>GHCR: attempt pull image:<tag> (source="version-tag")
  GHCR-->>Resolver: 200/404 (select next candidate or fallback)

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related issues

• Publish release-pinned sandbox base image refs #4052: Implements version-tag normalization and publishing/consumption which aligns with that issue's objective to publish and use release-pinned sandbox base images.

Suggested labels

fix, Docker, Sandbox

Suggested reviewers

• cv
• prekshivyas

Poem

🐰 I hop through tags both old and new,
I strip the v and make it true.
From .version, git, and env I glean,
A pinned sandbox—stable and clean. 🥕✨

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately summarizes the main change: adding support for versioned sandbox base images as a preference mechanism.
Linked Issues check	✅ Passed	The PR directly addresses all coding requirements from #4080: publishes versioned sandbox-base images on v* tag pushes, implements version-tag-based resolution with proper fallbacks, extends base image resolution to prefer matching versioned tags, and adds comprehensive test coverage for the new functionality.
Out of Scope Changes check	✅ Passed	All changes are directly related to versioned sandbox base image support: action/workflow updates for publishing versioned images, helper functions for tag normalization and resolution, and test coverage. The Docker runtime probe timeouts are minor supporting changes to ensure reliable container detection during the new resolution logic.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/versioned-sandbox-base-images

Warning

There were issues while running some tools. Please review the errors and either fix the tool's configuration or disable the tool if it's a critical failure.

🔧 ESLint

If the error stems from missing dependencies, add them to the package.json file. For unrecoverable errors (e.g., due to private dependencies), disable the tool in the CodeRabbit configuration.

ESLint skipped: no ESLint configuration detected in root package.json. To enable, add eslint to devDependencies.

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[github-actions]

E2E Advisor Recommendation

Required E2E: test-e2e-sandbox, cloud-onboard-e2e, gpu-e2e, upgrade-stale-sandbox-e2e
Optional E2E: gpu-double-onboard-e2e, ollama-proxy-e2e, rebuild-openclaw-e2e, openclaw-onboard-security-posture-e2e

Dispatch hint: cloud-onboard-e2e,gpu-e2e,upgrade-stale-sandbox-e2e

Auto-dispatched E2E: cloud-onboard-e2e, gpu-e2e, upgrade-stale-sandbox-e2e via nightly-e2e.yaml at e54ca5a03952cbfbf9d60c31c980b2222e2ba01e — nightly run

Workflow run

Full advisor summary

E2E Recommendation Advisor

Base: origin/main
Head: HEAD
Confidence: high

Required E2E

• test-e2e-sandbox (medium): Validates that the changed resolve-sandbox-base-image action can select a compatible base image, build the production sandbox image, and run the sandbox E2E test image.
• cloud-onboard-e2e (medium): Covers the real install/onboard path, sandbox creation, policy setup, and inference.local probe after changes to sandbox base image resolution used during onboarding.
• gpu-e2e (high): Directly exercises local Ollama onboarding and inference on the provider path affected by getContainerRuntime/getOllamaContainerPort timeout and proxy/topology selection changes.
• upgrade-stale-sandbox-e2e (high): Exercises upgrade/stale-sandbox rebuild behavior where versioned base image tags and source/latest/local fallback choices can change whether the sandbox is rebuilt with the intended image.

Optional E2E

• gpu-double-onboard-e2e (high): Additional confidence for local Ollama proxy behavior across re-onboard after topology/proxy-selection changes.
• ollama-proxy-e2e (medium): Useful adjacent coverage for Ollama auth proxy token validation and container-to-proxy reachability, although it does not fully exercise the changed TypeScript topology resolver.
• rebuild-openclaw-e2e (high): Provides extra coverage for rebuild flows that may re-resolve the sandbox base image and verify workspace state survives image changes.
• openclaw-onboard-security-posture-e2e (high): Full OpenClaw onboard/inference path with runtime guard assertions; useful because base image choice can affect sandbox ABI and startup posture.

New E2E recommendations

• release-tagged sandbox base image resolution (high): Existing E2E coverage does not appear to force a v* tag/.version/NEMOCLAW_INSTALL_REF path and assert that the resolver pulls ghcr.io/nvidia/nemoclaw/sandbox-base: before falling back to SHA/latest/local.
  • Suggested test: Add an E2E or workflow-level integration test that dispatches a tag-like install context with a temporary/mock GHCR image tag and asserts the selected BASE_IMAGE/source is version-tag.
• WSL Docker Desktop local Ollama topology (medium): The changed runtime probe timeout affects the branch where WSL + Docker Desktop containers can reach host loopback directly, but existing local Ollama E2E is GPU/Linux-oriented.
  • Suggested test: Add a WSL local-Ollama topology scenario that verifies shouldFrontOllamaWithProxy/getOllamaContainerPort behavior under Docker Desktop runtime detection.

Dispatch hint

• Workflow: nightly-e2e.yaml
• jobs input: cloud-onboard-e2e,gpu-e2e,upgrade-stale-sandbox-e2e

[github-actions]

PR Review Advisor

Findings: 2 needs attention, 3 worth checking, 0 nice ideas
Since last review: 2 prior items resolved, 3 still apply, 1 new item found

Workflow run details

This is an automated advisory review. A human maintainer must make the final merge decision.

[github-actions]

Selective E2E Results — ✅ All requested jobs passed

Run: 26304292817
Target ref: 0d953e6eecb749c15bd1f6e93257f1d023838f32
Workflow ref: main
Requested jobs: cloud-onboard-e2e,rebuild-openclaw-e2e
Summary: 2 passed, 0 failed, 0 skipped

Job	Result
cloud-onboard-e2e	✅ success
rebuild-openclaw-e2e	✅ success

[github-actions]

E2E Scenario Advisor Recommendation

Required scenario E2E: None
Optional scenario E2E: None

Workflow run

Full scenario advisor summary

E2E Scenario Advisor

Base: origin/main
Head: HEAD
Confidence: high

Required scenario E2E

• None. No scenario workflow, scenario metadata, scenario runtime, or validation-suite files changed.

Optional scenario E2E

• None.

Relevant changed files

• None.

[github-actions]

Selective E2E Results — ✅ All requested jobs passed

Run: 26310708838
Target ref: e54ca5a03952cbfbf9d60c31c980b2222e2ba01e
Workflow ref: main
Requested jobs: cloud-onboard-e2e,gpu-e2e,upgrade-stale-sandbox-e2e
Summary: 2 passed, 0 failed, 1 skipped

Job	Result
cloud-onboard-e2e	✅ success
gpu-e2e	⏭️ skipped
upgrade-stale-sandbox-e2e	✅ success