fix(images): support Docker Engine gateway builds

[apurvvkumaria]

Summary

Managed OpenClaw and Hermes onboarding can now complete on Docker Engine when OpenShell uses its gateway builder. The gateway-bound Dockerfiles use legacy-compatible grouped COPY payloads instead of BuildKit-only bind mounts while retaining the measured cold-onboard layer budget.

Related Issue

Fixes #7611

Changes

• Stage repository-owned OpenClaw and Hermes files in scratch payload images, then apply each group with a legacy-compatible cross-stage root COPY.
• Preserve the existing cache order, ownership fixes, integrity checks, completed-image scans, and four/five grouped payload-layer boundaries.
• Restore gateway fallback after a host-side Hermes prebuild failure because the managed Dockerfile no longer requires the BuildKit parser.
• Add source contracts that reject RUN --mount, pin the grouped copy counts and order, and keep package-remediation scans attached to the completed final images.
• Remove obsolete Hermes fail-fast troubleshooting text and document the Docker Engine compatibility fix in the v0.0.96 release entry.

Type of Change

• Code change (feature, bug fix, or refactor)
• Code change with doc updates
• Doc only (prose changes, no code sample modifications)
• Doc only (includes code sample changes)

Quality Gates

• Tests added or updated for changed behavior
• Existing tests cover changed behavior — justification:
• Tests not applicable — justification:
• Docs updated for user-facing behavior changes
• Docs not applicable — justification:
• Sensitive paths changed (security, policy, credentials, preflight, onboarding, inference, runner, sandbox, or messaging)
• Sensitive-path review completed or maintainer-approved waiver recorded — reviewer/approval link/justification: Codex Desktop reviewed the exact 8593925bc diff across all nine security categories. No findings were found. The change adds no inputs, dependencies, privileges, credentials, or network access; exact production-image builds preserve the final ownership, integrity, and package-scan assertions.
• Non-success, skipped, or missing CI check accepted by maintainer — check name, approval link, and follow-up issue:

Documentation Writer Review

• Documentation writer subagent reviewed the completed changes
• Result: docs-updated
• Evidence: docs/changelog/2026-07-25.mdx and docs/reference/troubleshooting.mdx; the exact-head layer-grouping follow-up required no additional docs and passed changelog validation 6/6
• Agent: Codex Desktop

DGX Station Hardware Evidence

• Tested on DGX Station
• Tested commit:
• Station profile/scenario:
• Result:
• Supporting evidence:

Verification

• PR description includes a Signed-off-by: line and every commit appears as Verified in GitHub
• Normal pre-commit, commit-msg, and pre-push hooks passed, or npm run check:diff passed when hooks were skipped or unavailable
• Targeted behavior tests pass for the current change set, or tests are marked not applicable above — exact head: 34/34 layout, completed-image scan, and build-context tests; earlier focused onboarding, permissions, preloads, dependency-review, and docs contracts also passed
• Applicable broad gate passed — exact head: npm run checks, CLI type-check through pre-push, source-shape, project-membership, test-title, test-size, Biome, hadolint, and secret-scanning checks passed
• Docker Engine legacy-builder acceptance passed — exact head: complete OpenClaw and Hermes production images built with DOCKER_BUILDKIT=0, including final metadata, integrity, and package-scan assertions
• Quality Gates section completed with required justifications or waivers
• No secrets, API keys, or credentials committed
• npm run docs builds without warnings (doc changes only)
• Doc pages follow the style guide (doc changes only)
• New doc pages include SPDX header and frontmatter (new pages only)

---

Signed-off-by: Apurv Kumaria akumaria@nvidia.com

Summary by CodeRabbit

• Bug Fixes
  • Improved OpenClaw and Hermes sandbox Docker image builds by switching payload installation to cross-stage copies (avoiding BuildKit-only bind/payload steps).
  • Prebuild/local-build failures now consistently fall back to the OpenShell gateway builder.
  • Updated Hermes onboarding/prebuild failure behavior to remove the special managed BuildKit failure handling path.
• Documentation
  • Updated the Docker build behavior changelog entry.
  • Removed outdated Hermes troubleshooting guidance for managed local image build failures.
• Tests
  • Updated final image layout and Dockerfile contract tests to validate legacy-compatible COPY-based payload boundaries.
  • Adjusted sandbox create/prebuild test coverage after the managed Hermes BuildKit failure handling removal.
• Chores
  • Refreshed source-shape test budget exception text for Hermes and OpenClaw final image layout contracts.

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

📝 Walkthrough

Walkthrough

OpenClaw and Hermes Dockerfiles replace BuildKit-only payload mounts with direct COPY instructions. Sandbox prebuilds remove managed Hermes failure preservation and fall back to the gateway builder after local failures. Layout tests and documentation are updated accordingly.

Changes

Docker Engine build compatibility

Layer / File(s)	Summary
Direct-copy image assembly Dockerfile, agents/hermes/Dockerfile	Payloads are copied directly into the final images, replacing bind-mounted tar extraction while retaining subsequent runtime checks.
Generic prebuild fallback src/lib/onboard/sandbox-prebuild.ts, src/lib/onboard/sandbox-create-launch.ts, src/lib/onboard/*.test.ts	Managed Hermes failure capabilities are removed, and local build failures consistently use the gateway-builder fallback.
Layout contracts and documentation test/*-final-image-layout.test.ts, test/node-tar-dockerfile-contract.test.ts, ci/source-shape-test-budget.json, docs/...	Tests require direct COPY boundaries and updated ordering, while build documentation reflects the new behavior.

Estimated code review effort: 4 (Complex) | ~45 minutes

Possibly related PRs

• NVIDIA/NemoClaw#7486: Overlaps the OpenClaw and Hermes payload materialization and layout contract changes.
• NVIDIA/NemoClaw#7586: Directly overlaps the managed Hermes BuildKit-failure handling path.
• NVIDIA/NemoClaw#7591: Overlaps MCP tool-discovery runtime verification in the image build flow.

Suggested labels: integration: openclaw, integration: hermes, area: packaging, area: sandbox, bug-fix, platform: container

Suggested reviewers: prekshivyas, senthilr-nv

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	[#7611] The Dockerfiles now replace BuildKit-only bind mounts with COPY and the related tests/docs were updated accordingly.
Out of Scope Changes check	✅ Passed	The edits stay focused on Docker Engine build compatibility, gateway fallback, and supporting tests/docs without obvious unrelated scope creep.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately summarizes the main change: making image builds work on Docker Engine via the gateway builder.

✨ 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 codex/7611-docker-engine-compat

---

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

[github-code-quality]

Code Coverage Overview

Languages: TypeScript

TypeScript / code-coverage/plugin

The overall coverage in commit 8593925 in the codex/7611-docker-en... branch remains at 96%, unchanged from commit d7b15dd in the main branch.

TypeScript / code-coverage/cli

The overall coverage in commit 8593925 in the codex/7611-docker-en... branch is 81%. The coverage in commit 921e1b0 in the main branch is 80%.

Show a code coverage summary of the most impacted files.

File	main 921e1b0	codex/7611-docker-en... 8593925	+/-
src/lib/onboard/docker-cdi.ts	80%	70%	-10%
src/lib/shields/index.ts	71%	67%	-4%
src/lib/onboard...host-anchors.ts	94%	90%	-4%
src/lib/actions...e-validation.ts	81%	84%	+3%
src/lib/actions...x/mcp-bridge.ts	35%	41%	+6%
src/lib/actions...lution-probe.ts	88%	95%	+7%
src/lib/actions...-add-restart.ts	10%	19%	+9%
src/lib/actions...confirmation.ts	69%	79%	+10%
src/lib/actions...ocker-health.ts	65%	82%	+17%
src/lib/onboard...box-prebuild.ts	73%	92%	+19%

---

_{Updated July 27, 2026 09:33 UTC}

[github-actions]

🌿 Preview your docs: https://nvidia-preview-pr-7622.docs.buildwithfern.com/nemoclaw

[coderabbitai]

Actionable comments posted: 2

🧹 Nitpick comments (1)

src/lib/onboard/sandbox-create-launch.test.ts (1)

397-401: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Consider keeping a managed-Hermes case for this fallback.

Switching agent from the OpenClaw agent to null makes this the generic path only. The behavior actually being retired is Hermes-specific fail-fast, so a case with the managed Hermes agent would directly prove the cutover — that a local build failure now falls back to the gateway builder instead of throwing.

As per path instructions, "Tests must prove that public entrypoints reach the new path and that the old path is deleted or cannot execute."

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/lib/onboard/sandbox-create-launch.test.ts` around lines 397 - 401, Extend
the fallback test in prepareSandboxCreateLaunchWithPrebuild to use the managed
Hermes agent, not only agent: null. Assert that a local build failure reaches
the gateway builder and returns the original Dockerfile without throwing,
directly covering removal of the Hermes-specific fail-fast path.

Source: Path instructions

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@Dockerfile`:
- Around line 95-106: The copied scripts lack the executable modes required by
the metadata checks. In Dockerfile lines 95-106, add a chmod 755 step for both
patch-bundled npm scripts and the node-tar image scan script copied at line
1616; in agents/hermes/Dockerfile lines 324 and 693, chmod hermes-wrapper.py and
node-tar-image-scan.mts to 755 before their respective checks.

In `@test/hermes-final-image-layout.test.ts`:
- Around line 161-185: Add a shared indexOfRequired helper that asserts each
searched needle exists before returning its index, then use it for every COPY
needle and comparison anchor in test/hermes-final-image-layout.test.ts lines
161-185, the dependency/plugin/patch/runtime lookups and anchors in
test/openclaw-final-image-layout.test.ts lines 46-49, and the RUN
check_metadata() anchor at line 74; preserve the existing ordering assertions
while preventing missing anchors from producing valid comparisons.

---

Nitpick comments:
In `@src/lib/onboard/sandbox-create-launch.test.ts`:
- Around line 397-401: Extend the fallback test in
prepareSandboxCreateLaunchWithPrebuild to use the managed Hermes agent, not only
agent: null. Assert that a local build failure reaches the gateway builder and
returns the original Dockerfile without throwing, directly covering removal of
the Hermes-specific fail-fast path.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 043ea2a4-acc7-4e11-a945-566aae5674ff

📥 Commits

Reviewing files that changed from the base of the PR and between 77e6e38 and 5620acf.

📒 Files selected for processing (11)

• Dockerfile
• agents/hermes/Dockerfile
• ci/source-shape-test-budget.json
• docs/changelog/2026-07-25.mdx
• docs/reference/troubleshooting.mdx
• src/lib/onboard/sandbox-create-launch.test.ts
• src/lib/onboard/sandbox-create-launch.ts
• src/lib/onboard/sandbox-prebuild.test.ts
• src/lib/onboard/sandbox-prebuild.ts
• test/hermes-final-image-layout.test.ts
• test/openclaw-final-image-layout.test.ts

💤 Files with no reviewable changes (2)

• src/lib/onboard/sandbox-create-launch.ts
• docs/reference/troubleshooting.mdx

[github-actions]

PR Review Advisor — Informational

Advisor assessment: Informational / low confidence
Next action: No advisor follow-up needed.
Findings: 0 blockers · 0 warnings · 0 suggestions
Status: Same-session synthesis validation failed; the advisor result is incomplete.

Model lanes

• GPT-5.6 Terra (primary): Completed · low confidence · 0 blockers · 0 warnings · 0 suggestions
• Nemotron 3 Ultra (second opinion): Completed · high confidence · 0 blockers · 2 warnings · 0 suggestions
• Model comparison: normalized findings differ; normalized E2E selections differ; Nemotron reported the same number of blockers, 2 more warnings, the same number of suggestions.

Nemotron output stays in workflow artifacts and does not change the assessment above.

E2E guidance

Advisory only. E2E / PR Gate selects and runs jobs independently.

Recommended E2E: cloud-onboard, full-e2e, hermes-e2e, security-posture, onboard-repair, onboard-resume, state-backup-restore, upgrade-stale-sandbox

1 optional E2E recommendation

• onboard-negative-paths

Workflow run details

This automated review informs maintainers. Warnings and suggestions do not require a response. A maintainer decides whether to merge.

[coderabbitai]

🧹 Nitpick comments (1)

src/lib/onboard/sandbox-create-launch.test.ts (1)

397-401: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Avoid bypassing the agent type in this regression test.

as any allows this test to keep passing if the Hermes agent contract gains required fields. Use the repository’s typed Hermes fixture/factory, or construct a value that satisfies the actual agent type, so contract changes fail during type-checking instead of silently reducing test confidence.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/lib/onboard/sandbox-create-launch.test.ts` around lines 397 - 401,
Replace the `agent: { name: "hermes" } as any` value in the `renders the
original Dockerfile for Hermes after a local build failure` test with the
repository’s typed Hermes fixture or factory, or construct a fully valid value
matching the actual agent type. Preserve the test setup while ensuring future
required Hermes agent fields produce type-checking failures.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@src/lib/onboard/sandbox-create-launch.test.ts`:
- Around line 397-401: Replace the `agent: { name: "hermes" } as any` value in
the `renders the original Dockerfile for Hermes after a local build failure`
test with the repository’s typed Hermes fixture or factory, or construct a fully
valid value matching the actual agent type. Preserve the test setup while
ensuring future required Hermes agent fields produce type-checking failures.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 63ae7c54-f89c-4d2d-8da9-ee2405bb6f5a

📥 Commits

Reviewing files that changed from the base of the PR and between 5620acf and 9f146f2.

📒 Files selected for processing (3)

• src/lib/onboard/sandbox-create-launch.test.ts
• test/hermes-final-image-layout.test.ts
• test/openclaw-final-image-layout.test.ts

🚧 Files skipped from review as they are similar to previous changes (2)

• test/hermes-final-image-layout.test.ts
• test/openclaw-final-image-layout.test.ts

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@test/hermes-final-image-layout.test.ts`:
- Around line 164-165: Update the dockerfile assertion in the final image layout
test to normalize line continuations and detect RUN instructions
case-insensitively despite repeated whitespace. Replace the literal substring
check with instruction-level parsing or an equivalent regex that reliably
rejects any BuildKit-only mount syntax.
- Around line 151-170: Update the payload assertions in the final-stage layout
test to validate the exact approved COPY source and destination for each payload
stage, not just the count returned by stage.match. Define the expected COPY
lines or source/destination pairs alongside payloads, then assert the stage’s
COPY entries and finalStage contents match those expectations exactly while
preserving the existing per-stage copy counts.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: d4350674-3faf-469e-b468-5286cd9537bd

📥 Commits

Reviewing files that changed from the base of the PR and between 4f4aace and 8593925.

📒 Files selected for processing (6)

• Dockerfile
• agents/hermes/Dockerfile
• ci/source-shape-test-budget.json
• test/hermes-final-image-layout.test.ts
• test/node-tar-dockerfile-contract.test.ts
• test/openclaw-final-image-layout.test.ts

🚧 Files skipped from review as they are similar to previous changes (2)

• ci/source-shape-test-budget.json
• agents/hermes/Dockerfile