fix(docker): force-enable BuildKit in dockerBuild

[laitingsheng]

Summary

On hosts whose Docker daemon defaults to the legacy builder, nemoclaw onboard aborts when the sandbox-base local rebuild reaches Dockerfile.base's RUN --mount=type=bind step with "the --mount option requires BuildKit". Force-enable BuildKit inside dockerBuild so every callsite gets the BuildKit path regardless of daemon defaults.

Related Issue

Fixes #3583

Changes

• Inject DOCKER_BUILDKIT=1 in dockerBuild before invoking docker build; preserve a caller-supplied value when one is already set.
• Update the existing docker-helper test to reflect the new env injection and add coverage for the BuildKit-enable path plus the caller-override path.

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)

Verification

• `npx prek run --all-files` passes
• `npm test` passes
• Tests added or updated for new or changed behavior
• No secrets, API keys, or credentials committed
• Docs updated for user-facing behavior changes
• `make 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: Tinson Lai tinsonl@nvidia.com

Summary by CodeRabbit

• Bug Fixes

  • Docker builds now default to using BuildKit when not explicitly configured. User-supplied Docker configurations remain respected.

• Tests

  • Updated tests to verify Docker BuildKit default behavior and that custom configurations are preserved.

[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: 241e4b44-e8f8-4398-a49f-c675d3fea4b5

📥 Commits

Reviewing files that changed from the base of the PR and between e865fdf and 19127d1.

📒 Files selected for processing (2)

• src/lib/adapters/docker/image.ts
• src/lib/adapters/docker/index.test.ts

---

📝 Walkthrough

Walkthrough

The PR modifies dockerBuild to enforce Docker BuildKit enablement by setting DOCKER_BUILDKIT=1 in the environment when not already provided. The implementation merges caller-supplied env vars and passes the updated environment to dockerRun. Test coverage verifies the default behavior, custom stdio handling, and preservation of caller-supplied values.

Changes

BuildKit enforcement in docker build

Layer / File(s)	Summary
BuildKit enforcement in dockerBuild src/lib/adapters/docker/image.ts	dockerBuild creates a merged env from opts.env, sets env.DOCKER_BUILDKIT to "1" when undefined, and passes the updated env to dockerRun, replacing direct opts forwarding.
BuildKit enforcement test coverage src/lib/adapters/docker/index.test.ts	Test expectations updated so docker build includes DOCKER_BUILDKIT=1 via env. Two new tests verify BuildKit is forced (even with custom stdio) and that caller-supplied DOCKER_BUILDKIT values are preserved along with other env vars.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Poem

A builder needs the power of kits,
So NemoClaw always fits,
No --mount syntax shall fail,
BuildKit enabled—without fail! 🐇✨

🚥 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 and concisely summarizes the main change: forcing BuildKit enablement in the dockerBuild helper function.
Linked Issues check	✅ Passed	The PR fully addresses issue #3583 by injecting DOCKER_BUILDKIT=1 into the environment during dockerBuild, with proper tests covering both forced-enable and caller-override scenarios.
Out of Scope Changes check	✅ Passed	All code changes are directly scoped to the dockerBuild helper and its tests; no unrelated modifications are present.

_{✏️ 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/docker-build-enable-buildkit

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: rebuild-openclaw-e2e
Optional E2E: rebuild-hermes-e2e, upgrade-stale-sandbox-e2e

Dispatch hint: rebuild-openclaw-e2e

Auto-dispatched E2E: rebuild-openclaw-e2e via nightly-e2e.yaml at 19127d166d1b7f3672379b078ee794f9fc45714e — nightly run

Workflow run

Full advisor summary

E2E Recommendation Advisor

Base: origin/main
Head: HEAD
Confidence: high

Required E2E

• rebuild-openclaw-e2e (high): Directly exercises the OpenClaw sandbox base image rebuild path that uses Dockerfile.base with BuildKit-only RUN --mount semantics and validates the rebuilt sandbox still works.

Optional E2E

• rebuild-hermes-e2e (high): Useful shared-wrapper confidence for the Hermes agent-specific Docker build path, which also calls dockerBuild during base image/rebuild flows, though the PR’s stated BuildKit failure is centered on OpenClaw Dockerfile.base.
• upgrade-stale-sandbox-e2e (high): Adjacent sandbox lifecycle coverage for stale base image detection and rebuild behavior after upgrade; optional because rebuild-openclaw-e2e is the more targeted guard for this Docker build wrapper change.

New E2E recommendations

• docker-buildkit-legacy-daemon (medium): Existing rebuild E2Es validate rebuild behavior, but may not run on a host whose Docker daemon defaults to the legacy builder. Add targeted E2E/regression coverage that forces a legacy-builder-default environment, runs the local Dockerfile.base rebuild through the NemoClaw CLI, and asserts the wrapper-provided DOCKER_BUILDKIT=1 makes the BuildKit-only RUN --mount build succeed.
  • Suggested test: Add a BuildKit defaulting regression E2E for local sandbox-base rebuild on a legacy-builder-default Docker host

Dispatch hint

• Workflow: .github/workflows/nightly-e2e.yaml
• jobs input: rebuild-openclaw-e2e

[github-actions]

Selective E2E Results — ✅ All requested jobs passed

Run: 25916819564
Target ref: 19127d166d1b7f3672379b078ee794f9fc45714e
Workflow ref: main
Requested jobs: rebuild-openclaw-e2e
Summary: 1 passed, 0 failed, 0 skipped

Job	Result
rebuild-openclaw-e2e	✅ success