perf(sandbox): reduce image build time by skipping broad permission repair

[zyang-dev]

Summary

This PR reduces sandbox image build time by avoiding broad recursive .openclaw permission repair on current unified-layout sandbox bases. It keeps the conservative repair path for legacy .openclaw-data migrations and adds Docker build step timing to make future build bottlenecks visible.
DGX Spark build-time comparison:

• Original/restored Dockerfile: 178.1s
• Optimized Dockerfile: 68.0s

Changes

• Gate legacy .openclaw-data symlink verification so it only runs when legacy migration occurs.
• Replace unconditional recursive .openclaw permission repair with a legacy-only broad repair and a targeted fast path for current unified layouts. The fast path relies on the current unified .openclaw layout being provisioned earlier in the image: Dockerfile.base creates the known state directories as sandbox:sandbox with group-write/setgid permissions, and openclaw plugins install runs as USER sandbox, so plugin-runtime-deps contents are already owned by sandbox:sandbox before the final repair step.
• Add behavior-based regression coverage for the .openclaw repair path: current layouts use targeted permission repair, while legacy .openclaw-data migrations still use broad recursive repair.
• Add an explicit .openclaw layout contract check so future directory/file layout changes fail tests until the targeted permission repair assumptions are reviewed.
• Add classic Docker build step timing to sandbox create progress output.

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)

Additional validation:

• Verified in a freshly built sandbox that /sandbox/.openclaw/plugin-runtime-deps and sampled contents are owned by sandbox:sandbox; no non-sandbox:sandbox entries were found, and a sandbox-user write probe in plugin-runtime-deps succeeded.

---

Signed-off-by: zyang-dev 267119621+zyang-dev@users.noreply.github.com

Summary by CodeRabbit

• New Features

  • Adds per-step and overall build timing to Docker build output for clearer build progress.

• Chores

  • Makes legacy layout cleanup conditional and adds stricter post-cleanup validation.
  • Changes permission normalization to a conditional, targeted approach to avoid unnecessary wide updates.

• Tests

  • Adds regression tests verifying targeted vs. legacy permission repair behavior and the legacy-marker workflow.

[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: e961021f-3c65-4b23-b83d-993d9ed0d4d7

📥 Commits

Reviewing files that changed from the base of the PR and between 2048db9 and 65e281a.

📒 Files selected for processing (1)

• test/sandbox-provisioning.test.ts

---

📝 Walkthrough

Walkthrough

Refactors Dockerfile cleanup to record legacy migrations via a marker and apply conditional permission repairs; tightens OpenClaw directory/file initialization; adds classic Docker build-step timing in the stream processor; and adds a regression test covering modern vs legacy permission repair behavior.

Changes

Legacy OpenClaw Layout Migration & Conditional Permissions

Layer / File(s)	Summary
Legacy layout tracking and marker file Dockerfile	Introduces legacy_layout flag and /tmp/nemoclaw-legacy-openclaw-layout marker file to record whether legacy cleanup ran.
Post-cleanup validation and directory initialization Dockerfile	Enforces legacy data directory removal, verifies no legacy symlinks remain when migration ran, writes marker for permission layer, and initializes OpenClaw directories/metadata with consistent owner/group and setgid via loops.
Conditional permissions layer keyed off legacy marker Dockerfile	Replaces unconditional recursive chown/chmod with conditional logic: perform broad normalization when marker exists (then remove it); otherwise perform targeted ownership/mode changes and skip expensive filesystem walks.
Regression test for legacy layout behavior test/sandbox-provisioning.test.ts	Extracts Dockerfile RUN blocks and asserts modern path uses targeted permission updates while legacy path creates marker and triggers broader recursive repairs and setgid fixes.

Build Step Timing Instrumentation

Layer / File(s)	Summary
Classic Docker step detection and state initialization src/lib/sandbox/create-stream.ts	Adds CLASSIC_DOCKER_STEP_RE to detect Step X/Y : ... lines and introduces build-timing state variables (overall start timestamp, finalization flag, active step tracking).
Build timing utilities and step tracking src/lib/sandbox/create-stream.ts	Adds duration formatting utilities and orchestration helpers to manage overall timing lifecycle and finish active classic steps with completed/stopped wording.
Stream output handling and build completion detection src/lib/sandbox/create-stream.ts	Integrates timing into streamed output: marks build start, parses classic step lines to record step timings, detects successful build completion, and finalizes timing at stream termination.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

Suggested labels

Docker, fix

Suggested reviewers

• ericksoa

Poem

🐰
I nibbled through old layouts, found the marker there,
Tidied paths and set the bits with very gentle care,
Steps now tick and whisper how long each one has run,
Legacy sleeps, new paths shine bright beneath the sun,
Hoppity-hop, the build is trimmed and neatly done.

🚥 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 'perf(sandbox): reduce image build time by skipping broad permission repair' directly reflects the main change: optimizing sandbox image build by conditional permission repair instead of unconditional recursive operations.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ 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/sandbox-build-perf

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: openclaw-onboard-security-posture-e2e, openclaw-plugin-runtime-exdev-e2e
Optional E2E: rebuild-openclaw-e2e, sandbox-operations-e2e

Workflow run

Full advisor summary

E2E Recommendation Advisor

Base: origin/main
Head: HEAD
Confidence: high

Required E2E

• openclaw-onboard-security-posture-e2e (high): Required because the Dockerfile changes affect .openclaw ownership/mode defaults and runtime guard/security posture for a non-root OpenClaw onboard. This job performs a full OpenClaw install/onboard/inference path with security posture assertions.
• openclaw-plugin-runtime-exdev-e2e (medium): Required because the Dockerfile now avoids broad recursive repair on modern layouts while explicitly chmod/chowning plugin-runtime-deps. This regression job validates that a fresh sandbox can run the first OpenClaw CLI/plugin bootstrap without plugin runtime dependency failures.

Optional E2E

• rebuild-openclaw-e2e (high): Useful confidence for the changed image layout and permissions across an OpenClaw rebuild/upgrade path, especially because the Dockerfile changes are intended to preserve state while optimizing permission repair.
• sandbox-operations-e2e (high): Optional broader lifecycle coverage for sandbox creation, logs/exec/status, recovery, and isolation. It can catch regressions if the create stream or image permissions break operational sandbox flows beyond initial onboard.

New E2E recommendations

• legacy .openclaw-data base-image migration (medium): The PR adds unit-level simulation for the stale legacy .openclaw-data migration marker and permission fallback, but there does not appear to be a live E2E that builds from a deliberately legacy OpenClaw layout base image and asserts the resulting sandbox has no legacy symlinks, correct group-writable permissions, and working OpenClaw runtime config mutation.
  • Suggested test: stale-openclaw-layout-migration-e2e

[github-actions]

PR Review Advisor

Recommendation: blocked
Confidence: high
Analyzed HEAD: 65e281ac8d332e396493adb1287612571fed9000
Findings: 3 blocker(s), 4 warning(s), 0 suggestion(s)

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

Limitations: Review used trusted metadata and the provided diff only; no PR scripts, package-manager commands, Docker builds, or tests were executed by this advisor.; The diff was provided as truncated-if-large context; conclusions focus on visible changed hunks and trusted metadata.; No full workflow logs were reviewed, so successful CI context internals were not independently inspected.; No passed required E2E runs for head 65e281a were available in trusted context.; PR body validation claims, build timing measurements, and freshly built sandbox validation claims were treated as untrusted evidence only.; Review thread state was not fully available beyond the provided trusted metadata.

Workflow run

Full advisor summary

PR Review Advisor

Base: origin/main
Head: HEAD
Analyzed SHA: 65e281ac8d332e396493adb1287612571fed9000
Recommendation: blocked
Confidence: high

Blocked by GitHub mergeStateStatus=BLOCKED, missing required sandbox/OpenClaw E2E evidence for this head SHA, and unoffset create-stream.ts monolith growth; required CI contexts are currently green.

Gate status

• CI: pass — 5 required status context(s) completed with no failures for head 65e281a: checks, commit-lint, dco-check, check-hash, changes. Non-required contexts still pending: 4; failed: 0.
• Mergeability: fail — GitHub GraphQL mergeStateStatus=BLOCKED and REST mergeable_state=blocked for PR perf(sandbox): reduce image build time by skipping broad permission repair #4018 at head 65e281a.
• Review threads: unknown — No review thread state was available in trusted gate context; GraphQL reviewThreads.nodes is empty but reviewDecision is REVIEW_REQUIRED.
• Risky code tested: warning — Path heuristic reported no risky code areas, but the actual diff changes Dockerfile sandbox permissions and src/lib/sandbox/create-stream.ts runtime progress handling. Unit/snippet tests exist, while E2E Advisor required sandbox/OpenClaw runtime jobs are not shown passed for this SHA.

🔴 Blockers

• PR mergeability is blocked: GitHub reports mergeStateStatus=BLOCKED / mergeable_state=blocked for the current head SHA. This is a hard gate even though required status contexts are green.
  • Recommendation: Resolve the branch protection or review requirement causing BLOCKED and re-check mergeability for 65e281a before merge consideration.
  • Evidence: Trusted gate status: mergeability.status=fail, evidence=mergeStateStatus=BLOCKED; PR REST metadata reports mergeable_state=blocked.
• Required sandbox/OpenClaw E2E has not passed for this head SHA (Dockerfile:548): The PR changes security-sensitive .openclaw ownership/mode repair and plugin-runtime-deps assumptions. E2E Advisor required openclaw-onboard-security-posture-e2e and openclaw-plugin-runtime-exdev-e2e, but trusted status evidence does not show those jobs passed for head 65e281a.
  • Recommendation: Run and require successful openclaw-onboard-security-posture-e2e and openclaw-plugin-runtime-exdev-e2e for this exact SHA; consider the optional rebuild-openclaw-e2e and sandbox-operations-e2e for extra coverage.
  • Evidence: E2E Advisor comment: Required E2E: openclaw-onboard-security-posture-e2e, openclaw-plugin-runtime-exdev-e2e. e2eAdvisorStatus has passedForHeadSha=[] and missingForHeadSha includes both required jobs.
• create-stream.ts monolith grew beyond the repository budget (src/lib/sandbox/create-stream.ts:1): Trusted monolith analysis reports src/lib/sandbox/create-stream.ts grew from 385 to 459 lines, a +74 line increase. The repository budget flags current monolith growth of 20 or more lines as a blocker.
  • Recommendation: Extract the Docker build timing parser/state machine/helpers into a focused module or offset the growth before merge.
  • Evidence: monolithDeltas: file=src/lib/sandbox/create-stream.ts, baseLines=385, headLines=459, delta=74, severity=blocker.

🟡 Warnings

• High active-work overlap on Dockerfile and sandbox provisioning tests (Dockerfile:434): The changed files still exist, but Dockerfile and sandbox provisioning tests overlap with several open PRs touching sandbox, OpenClaw runtime, policy/provider, dependency, and proxy behavior. This increases drift/rebase risk in a security-sensitive image path.
  • Recommendation: Coordinate with overlapping work and re-run CI/E2E after any rebase, especially for Dockerfile permissions, OpenClaw runtime dependencies, proxy/provider changes, and sandbox provisioning behavior.
  • Evidence: Trusted openPrOverlaps include PRs feat(hermes): request network access through policy local #3750, feat(sandbox): install provider access tools #3747, feat(hermes): request network access through policy local #3748, feat(plugin): add provider-first access tools #3749, fix(openclaw): bump runtime deps EXDEV fix #3820, Upgrade OpenClaw to 2026.5.18 #3825, chore: upgrade agent runtime dependencies #3925, and fix(openclaw): prefer OpenShell loopback proxy #4005 touching Dockerfile; PRs feat(hermes): request network access through policy local #3750, chore: upgrade Hermes to v2026.5.16 #3831, and fix: remove proxy hooks from sandbox rc files #3842 overlap test/sandbox-provisioning.test.ts.
• New build timing behavior lacks direct regression tests (src/lib/sandbox/create-stream.ts:52): The PR adds classic Docker step timing, total build timing, completed/stopped output, and interactions with failure and ready-detach paths, but the changed test file focuses on Dockerfile permission behavior. No direct test evidence covers duplicate suppression, deterministic durations, successful completion, failure close, or readyCheck forced detach.
  • Recommendation: Add unit tests around streamSandboxCreate with a mocked child process and deterministic clock for classic Step N/M lines, Successfully built/Built image completion, nonzero close stopped output, and readyCheck forced-ready detachment.
  • Evidence: Diff adds CLASSIC_DOCKER_STEP_RE, buildStartedAtMs, activeBuildStep, finishBuildTiming, maybeStartClassicBuildStep, and finish-time behavior in src/lib/sandbox/create-stream.ts; no create-stream tests were added in test/sandbox-provisioning.test.ts.
• Fast permission path relies on inherited nested ownership without live-image proof (Dockerfile:548): The prior broad recursive repair guaranteed the whole /sandbox/.openclaw tree was sandbox-owned with group-writable/setgid directories. The new current-layout fast path updates only selected top-level paths. If the base image or plugin install leaves nested plugin-runtime-deps/state entries with root ownership or restrictive modes, non-root OpenClaw/gateway runtime behavior can fail or drift from intended security posture.
  • Recommendation: Back the optimization with real-image/container assertions for nested ownership, mode bits, setgid inheritance, and sandbox-user write probes under plugin-runtime-deps and mutable state directories; retain targeted recursive repair where contents are generated during image build if E2E exposes drift.
  • Evidence: Dockerfile fast path runs non-recursive chown on /sandbox/.openclaw, /sandbox/.openclaw/openclaw.json, and /sandbox/.openclaw/plugin-runtime-deps, plus chmod 2770 on only two directories and chmod 660 on openclaw.json. Required runtime/security E2E is missing for this head SHA.
• Permission regression test mocks ownership-changing commands (test/sandbox-provisioning.test.ts:113): The new test is stronger than a pure source-shape assertion because it executes extracted Dockerfile RUN blocks, but it mocks chown and wraps install/find/chmod. It proves branch selection and filesystem shape, not actual owner/group results inside a Docker image or nested plugin-runtime-deps modes after OpenClaw plugin installation.
  • Recommendation: Keep the snippet regression test, but supplement it with real-image or containerized assertions that verify owner, group, mode bits, setgid inheritance, legacy marker removal, and sandbox-user write access for modern-layout and legacy-migration scenarios.
  • Evidence: runOpenclawRepairLayoutCase defines chown() as a logger and install() as a mkdir wrapper, then asserts logged calls such as chown -R and chmod rather than real image ownership.

🔵 Suggestions

• None.

Acceptance coverage

• met — Gate legacy .openclaw-data symlink verification so it only runs when legacy migration occurs.: Dockerfile introduces legacy_layout=0, sets it to 1 only when /sandbox/.openclaw-data exists, and wraps post-cleanup legacy symlink verification in if [ "$legacy_layout" = "1" ]; then ... fi. The added test exercises modern and legacy cases.
• partial — Replace unconditional recursive .openclaw permission repair with a legacy-only broad repair and a targeted fast path for current unified layouts. The fast path relies on the current unified .openclaw layout being provisioned earlier in the image: Dockerfile.base creates the known state directories as sandbox:sandbox with group-write/setgid permissions, and openclaw plugins install runs as USER sandbox, so plugin-runtime-deps contents are already owned by sandbox:sandbox before the final repair step.: Dockerfile implements the legacy marker path with recursive chown/chmod/find and a non-recursive current-layout fast path. Coverage remains partial because trusted evidence does not show required live sandbox/OpenClaw E2E passing for this SHA, and nested plugin-runtime-deps ownership is not proven by real image execution.
• partial — Add behavior-based regression coverage for the .openclaw repair path: current layouts use targeted permission repair, while legacy .openclaw-data migrations still use broad recursive repair.: test/sandbox-provisioning.test.ts adds uses targeted permission repair unless legacy migration ran and executes extracted Dockerfile RUN blocks against fixture trees. It verifies logged calls and filesystem shape, but ownership-changing commands are mocked and no real image is executed.
• met — Add an explicit .openclaw layout contract check so future directory/file layout changes fail tests until the targeted permission repair assumptions are reviewed.: The new test asserts exact dirsAfterCleanup and filesAfterCleanup lists for the modern layout, including expected state directories and exec-approvals.json / update-check.json.
• partial — Add classic Docker build step timing to sandbox create progress output.: src/lib/sandbox/create-stream.ts adds CLASSIC_DOCKER_STEP_RE, active step tracking, duration formatting, and completed/stopped build timing lines. No direct changed test evidence covers this output, duplicate suppression, failure handling, or ready-detach interactions.
• unknown — Verified in a freshly built sandbox that /sandbox/.openclaw/plugin-runtime-deps and sampled contents are owned by sandbox:sandbox; no non-sandbox:sandbox entries were found, and a sandbox-user write probe in plugin-runtime-deps succeeded.: This validation appears only in the PR body, which is untrusted evidence. Trusted status/E2E evidence does not show the required live sandbox/OpenClaw jobs passing for head 65e281a.
• unknown — npx prek run --all-files passes: This is a PR body checkbox claim and is treated as untrusted evidence. Trusted CI does show required contexts green, but no direct trusted log for this exact local command was reviewed.
• met — npm test passes: Trusted GraphQL statusCheckRollup shows unit-vitest-linux completed with SUCCESS for the current head SHA, and the required checks context completed with SUCCESS.
• partial — Tests added or updated for new or changed behavior: test/sandbox-provisioning.test.ts adds regression coverage for .openclaw repair behavior and layout contract. No direct test was added for src/lib/sandbox/create-stream.ts build timing behavior.
• met — No secrets, API keys, or credentials committed: Visible diff adds no hardcoded tokens, PEM/key material, credential JSON, or secret literals; Dockerfile token-clearing step remains present.
• missing — Docs updated for user-facing behavior changes: PR body leaves this unchecked and changedFiles contains no docs. The change adds progress-output behavior but no user-facing docs or release note file in the diff.
• met — No linked issues were found for this pull request.: Trusted GitHub metadata reports linkedIssues: []. CodeRabbit pre-merge checks also state the linked issue check was skipped because no linked issues were found.

Security review

• pass — 1. Secrets and Credentials: No hardcoded secrets, API keys, passwords, PEM/key files, credential JSON, or token literals were introduced in the visible diff. The existing Dockerfile step that clears generated OpenClaw gateway auth token remains intact.
• pass — 2. Input Validation and Data Sanitization: No new external input parser, URL fetcher, deserialization path, or shell interpolation of user-controlled input was added. Dockerfile paths are fixed internal paths, and create-stream timing parses Docker output with a bounded regular expression for display.
• pass — 3. Authentication and Authorization: No authentication/authorization endpoints, token validation logic, scopes, privilege checks, or access-control decisions were added or modified. Gateway token generation/clearing boundaries are not visibly weakened.
• pass — 4. Dependencies and Third-Party Libraries: No new dependencies, package registries, package-manager trust changes, or floating production dependency ranges were added. The Dockerfile continues the offline npm posture for relevant local plugin install/repair layers.
• warning — 5. Error Handling and Logging: Build timing repeats Docker step instruction text into progress output and appends synthetic completed/stopped lines. This does not create a new secret source beyond existing Docker output, but direct tests are needed to ensure log consumers, duplicate suppression, ready detection, and failure handling are not confused.
• pass — 6. Cryptography and Data Protection: Not applicable — no cryptographic operations, algorithms, signatures, keys, hashes used for security decisions, or data-at-rest/in-transit protection mechanisms were changed.
• warning — 7. Configuration and Security Headers: The Dockerfile changes security-sensitive container filesystem permissions. The current-layout fast path removes previous recursive repair and only updates selected top-level paths, so live-image evidence is required to confirm least-privilege, mutability, group-write, setgid, and non-root runtime expectations are preserved.
• warning — 8. Security Testing: A behavior-style Dockerfile snippet test was added, but required security-relevant E2E jobs for OpenClaw onboard security posture and plugin-runtime-deps have not passed for the current head SHA in trusted evidence. Ownership-changing commands are mocked in the new unit test.
• warning — 9. Holistic Security Posture: The PR targets sandbox image permissions and sandbox lifecycle output, both high-risk NemoClaw areas. The legacy fallback is retained and the performance goal is reasonable, but merge should wait for mergeability, required E2E, and create-stream tests to avoid permission drift, sandbox startup failures, or false confidence from mocked assertions.

Test / E2E status

• Test depth: e2e_required — Runtime/sandbox/infrastructure paths need real execution coverage: Dockerfile permission/layout changes and src/lib/sandbox/create-stream.ts progress/timing behavior cannot be fully proven by mocked unit/snippet tests. Required CI contexts are green, but E2E Advisor required jobs are missing for this head SHA.
• E2E Advisor: missing
• Required E2E jobs: openclaw-onboard-security-posture-e2e, openclaw-plugin-runtime-exdev-e2e
• Missing for analyzed SHA: openclaw-onboard-security-posture-e2e, openclaw-plugin-runtime-exdev-e2e

✅ What looks good

• The changed files still exist on the active codebase; no rename drift was reported for Dockerfile, src/lib/sandbox/create-stream.ts, or test/sandbox-provisioning.test.ts.
• Required status contexts are currently successful for head 65e281a.
• The Dockerfile retains a conservative recursive repair path for legacy .openclaw-data migration instead of deleting that safety path outright.
• The cleanup block refuses symlinked legacy data entries, verifies legacy symlink removal only when migration ran, and removes the marker after broad repair.
• The new sandbox-provisioning test executes extracted Dockerfile RUN snippets for modern and legacy layouts, which is stronger than a pure string-only assertion.
• No new third-party dependencies or obvious committed secrets were introduced.
• The E2E Advisor correctly identified sandbox/OpenClaw security-posture and plugin-runtime-deps coverage needed for this change.

Review completeness

• Review used trusted metadata and the provided diff only; no PR scripts, package-manager commands, Docker builds, or tests were executed by this advisor.
• The diff was provided as truncated-if-large context; conclusions focus on visible changed hunks and trusted metadata.
• No full workflow logs were reviewed, so successful CI context internals were not independently inspected.
• No passed required E2E runs for head 65e281a were available in trusted context.
• PR body validation claims, build timing measurements, and freshly built sandbox validation claims were treated as untrusted evidence only.
• Review thread state was not fully available beyond the provided trusted metadata.
• Human maintainer review required: yes