Walkthrough

This PR refactors sandbox Dockerfile patching to improve security and reusability. Symlink-safe file operations with O_NOFOLLOW are added to patchStagedDockerfile. Sandbox patch preparation logic is extracted into a new prepareSandboxDockerfilePatch flow module with optional base-image resolution and dependency injection. The flow is integrated into createSandbox, replacing the previous inline implementation.

Changes

Sandbox Dockerfile Patching Refactor

Sequence Diagram

sequenceDiagram
  participant createSandbox
  participant prepareSandboxDockerfilePatch
  participant pullAndResolveBaseImageDigest
  participant inspectDockerImage
  participant enforceDockerGpuPatchPreserveNetwork
  participant patchStagedDockerfile
  
  createSandbox->>prepareSandboxDockerfilePatch: call with stagedDockerfile, agent, provider, etc.
  alt agent present and custom Dockerfile
    prepareSandboxDockerfilePatch->>pullAndResolveBaseImageDigest: resolve base image digest
    alt resolution succeeds
      pullAndResolveBaseImageDigest-->>prepareSandboxDockerfilePatch: return resolved digest
      prepareSandboxDockerfilePatch->>inspectDockerImage: verify image available
    else resolution fails
      pullAndResolveBaseImageDigest-->>prepareSandboxDockerfilePatch: error
      prepareSandboxDockerfilePatch->>inspectDockerImage: check :latest fallback
      alt :latest exists
        inspectDockerImage-->>prepareSandboxDockerfilePatch: cached
        prepareSandboxDockerfilePatch-->>prepareSandboxDockerfilePatch: warn cached fallback
      else :latest missing
        prepareSandboxDockerfilePatch-->>prepareSandboxDockerfilePatch: warn with docker pull command
      end
    end
  else default Dockerfile or no agent
    prepareSandboxDockerfilePatch-->>prepareSandboxDockerfilePatch: skip resolution
  end
  prepareSandboxDockerfilePatch->>enforceDockerGpuPatchPreserveNetwork: enforce GPU patch
  prepareSandboxDockerfilePatch->>patchStagedDockerfile: patch with resolved base ref or null
  patchStagedDockerfile-->>prepareSandboxDockerfilePatch: return patched result
  prepareSandboxDockerfilePatch-->>createSandbox: return { buildId, resolvedBaseImage }

Estimated Code Review Effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Suggested Labels

area: sandbox

Suggested Reviewers

• prekshivyas

Poem

🐰 A rabbit hops through symlinks with care,
With O_NOFOLLOW flags floating in air,
Dockerfile patching flows, safe and refine,
The sandbox grows stronger, line by line!
hop hop ✨

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

E2E Recommendation Advisor

Base: origin/main
Head: HEAD
Confidence: high

Required E2E

• openclaw-onboard-security-posture-e2e (high): High-signal required coverage for the changed OpenClaw onboarding path: runs install/onboard, patches the staged Dockerfile, creates the sandbox, verifies inference.local/OpenClaw turn completion, and enables sandbox security-posture assertions.
• hermes-e2e (high): The new helper has agent-specific behavior that skips base-image resolution for agent default Dockerfiles and still patches Hermes/tool-gateway ARGs; run the real Hermes assistant onboard/runtime flow to cover that branch.

Optional E2E

• openclaw-plugin-runtime-exdev-e2e (medium): Useful adjacent confidence for the --from custom Dockerfile branch, which now resolves/pins the sandbox base image and patches the staged Dockerfile through the new helper before creating a live OpenClaw sandbox.
• gpu-e2e (very high): Optional because of GPU runner cost, but relevant: this PR moved the Docker GPU local-inference network-preservation call into the helper used before Dockerfile patching and sandbox create.
• credential-sanitization-e2e (high): Adjacent security regression coverage for symlink-safe host-file handling and credential/sandbox boundary checks, though it does not directly exercise the new staged-Dockerfile symlink guard.

New E2E recommendations

• Dockerfile patch security (high): Existing new coverage is unit-level. There is no live CLI/E2E negative-path test that plants a symlinked Dockerfile in an onboard/custom-Dockerfile flow and proves the target file is not modified.
  • Suggested test: Add a live or hermetic CLI E2E that runs nemoclaw onboard --from <symlinked Dockerfile> or equivalent staged-context setup, expects a clear refusal, and verifies the symlink target remains unchanged.
• base image pinning (medium): The base-image pull/resolve/pin logic was extracted from createSandbox into a helper, but existing live E2E does not explicitly assert the patched Dockerfile/build uses the freshly resolved sandbox-base digest for custom Dockerfiles.
  • Suggested test: Add an E2E assertion around a custom --from onboard that captures the resolved sandbox-base digest and verifies the staged Dockerfile/build log uses that pinned ref instead of stale :latest.

Dispatch hint

• Workflow: nightly-e2e.yaml
• jobs input: openclaw-onboard-security-posture-e2e,hermes-e2e

Vitest E2E Scenario Advisor

Base: origin/main
Head: HEAD
Confidence: high

Required Vitest E2E scenarios

• ubuntu-repo-cloud-openclaw: The PR refactors the core onboarding sandbox Dockerfile patch path, including base-image pinning, Dockerfile mutation safety, and GPU-network preservation orchestration. The live-supported Ubuntu repo cloud OpenClaw scenario exercises the standard Docker-backed onboarding/create flow that reaches this patching surface.
  • Dispatch: gh workflow run e2e-vitest-scenarios.yaml --ref <pr-head-ref> --field scenarios=ubuntu-repo-cloud-openclaw

Optional Vitest E2E scenarios

• None.

Relevant changed files

• src/lib/onboard.ts
• src/lib/onboard/dockerfile-patch.ts
• src/lib/onboard/sandbox-dockerfile-patch-flow.ts
• src/lib/onboard/dockerfile-patch-security.test.ts
• src/lib/onboard/sandbox-dockerfile-patch-flow.test.ts

• **Runtime validation** — Runtime/integration: default onboard build writes a staged Dockerfile whose ARG BASE_IMAGE uses the resolved digest before openshell sandbox create.. Unit coverage is strong for the extracted helper and Dockerfile path guards, but the changed code participates in real Docker/OpenShell sandbox creation and Docker-driver GPU infrastructure where behavior depends on runtime state.
• **Runtime validation** — Runtime/integration: selected agent with custom --from resolves and passes the base-image ref into the staged Dockerfile patch.. Unit coverage is strong for the extracted helper and Dockerfile path guards, but the changed code participates in real Docker/OpenShell sandbox creation and Docker-driver GPU infrastructure where behavior depends on runtime state.
• **Runtime validation** — Runtime/integration: Docker-driver GPU local-inference host-network opt-in is downgraded to preserve bridge networking before sandbox create consumes the GPU patch network mode.. Unit coverage is strong for the extracted helper and Dockerfile path guards, but the changed code participates in real Docker/OpenShell sandbox creation and Docker-driver GPU infrastructure where behavior depends on runtime state.
• **Runtime validation** — Runtime/integration: offline/no-local-base path prints manual docker pull recovery guidance before the Docker build failure.. Unit coverage is strong for the extracted helper and Dockerfile path guards, but the changed code participates in real Docker/OpenShell sandbox creation and Docker-driver GPU infrastructure where behavior depends on runtime state.
• **Runtime validation** — Platform/unit if native Windows onboard is supported: patchStagedDockerfile fails closed with an actionable error when fs.constants.O_NOFOLLOW is unavailable.. Unit coverage is strong for the extracted helper and Dockerfile path guards, but the changed code participates in real Docker/OpenShell sandbox creation and Docker-driver GPU infrastructure where behavior depends on runtime state.