fix(onboard): stage repository root when --from targets the managed agent Dockerfile

[nvshaxie]

Summary

nemohermes onboard --from agents/hermes/Dockerfile fails at the first COPY because --from stages the Dockerfile's parent directory as the Docker build context, while the managed Hermes Dockerfile copies repository-root paths (src/, scripts/, nemoclaw-blueprint/). Onboard now detects when the resolved --from path is the selected agent's own managed Dockerfile and routes staging through the existing managed agent path, so the repository root becomes the build context and ARG BASE_IMAGE is pinned exactly as the managed build does. Standalone custom Dockerfiles keep the documented parent-directory contract.

Related Issue

Fixes #7205

Changes

• src/lib/onboard/build-context-stage.ts: when --from resolves (through symlinks) to agent.dockerfilePath, delegate to createAgentSandbox instead of staging the parent directory. origin stays custom, so the build still goes through the gateway builder (prebuildSandboxImageIfEligible keeps skipping the local BuildKit prebuild for user-supplied --from). The same staging function serves onboard and both rebuild preflights, so rebuilds of such sandboxes are covered too.
• src/lib/onboard/build-context-stage.test.ts: cover managed-Dockerfile delegation, symlinked-path delegation, and the standalone-Dockerfile path staying on the parent-directory contract.
• docs/reference/commands.mdx, docs/manage-sandboxes/install-plugins-hermes.mdx: document the managed-Dockerfile exception to the parent-directory contract.

Type of Change

• Code change with doc updates

Quality Gates

• Tests added or updated for changed behavior
• Docs updated for user-facing behavior changes
• 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: requesting maintainer review on this PR

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 — npx vitest run src/lib/onboard/build-context-stage.test.ts --project cli (10 passed) and npm run test:changed (36 files, 291 tests passed)
• 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)

---

Signed-off-by: Shawn Xie shaxie@nvidia.com

Summary by CodeRabbit

• New Features
  • Improved onboard --from for managed agent Dockerfiles to stage the repository-root build context, including when the Dockerfile is provided via symlink.
  • Added support to customize the build-context root used during agent sandbox image preparation.
• Documentation
  • Clarified which .dockerignore is used for managed vs non-managed --from Dockerfile paths.
• Tests
  • Expanded coverage for managed Dockerfile staging, symlink handling, credential filtering in staged contexts, and standalone Dockerfile behavior.

[github-actions]

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

[github-actions]

PR Review Advisor — Informational

Advisor assessment: Informational / high confidence
Next action: No advisor follow-up needed.
Findings: 0 blockers · 0 warnings · 0 suggestions
Status: No actionable findings remain in the canonical review ledger.

Model lanes

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

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

Since last review: 0 prior items resolved · 0 still apply · 0 new items found

E2E guidance

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

Recommended E2E: full-e2e, hermes-e2e, onboard-repair, onboard-resume, cloud-onboard

1 optional E2E recommendation

• rebuild-hermes

Workflow run details

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

[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

NemoClaw now detects when --from targets the selected agent’s managed Dockerfile, stages the repository root through the managed agent sandbox, preserves standalone Dockerfile behavior, and documents the exception.

Changes

Managed Dockerfile build context

Layer / File(s)	Summary
Managed agent context creation src/lib/agent/base-image.ts	createAgentSandbox accepts an optional context root and applies the custom build-context filter while excluding .claude.
Managed Dockerfile staging and documentation src/lib/onboard/build-context-stage.ts, docs/manage-sandboxes/install-plugins-hermes.mdx, docs/reference/commands.mdx	Managed Dockerfiles are identified through realpath comparison and staged with the repository-root context; documentation describes the repository-root .dockerignore behavior.
Managed and standalone Dockerfile tests src/lib/onboard/build-context-stage.test.ts	Tests cover direct and symlinked managed Dockerfiles, credential filtering, logging, and standalone Dockerfiles retaining custom staging behavior.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Possibly related PRs

• NVIDIA/NemoClaw#7461: Updates the managed Hermes Dockerfile and directly relates to repository-root build-context staging.

Suggested labels: area: security, area: docs

Suggested reviewers: cv, ericksoa

Sequence Diagram(s)

sequenceDiagram
  participant NemoClawOnboard
  participant stageCreateSandboxBuildContext
  participant createAgentSandbox
  participant createCustomBuildContextFilter
  NemoClawOnboard->>stageCreateSandboxBuildContext: provide managed Dockerfile
  stageCreateSandboxBuildContext->>stageCreateSandboxBuildContext: compare resolved Dockerfile paths
  stageCreateSandboxBuildContext->>createAgentSandbox: stage repository-root context
  createAgentSandbox->>createCustomBuildContextFilter: filter repository files
  createCustomBuildContextFilter-->>createAgentSandbox: filtered build context
  createAgentSandbox-->>stageCreateSandboxBuildContext: return build context
  stageCreateSandboxBuildContext-->>NemoClawOnboard: return custom origin and cleanup

Loading

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the main fix: staging the repository root for the managed Hermes Dockerfile.
Linked Issues check	✅ Passed	The code and docs now route --from agents/hermes/Dockerfile through managed staging, making the repo root the build context while preserving standalone behavior.
Out of Scope Changes check	✅ Passed	The added tests, docs, and rootDir plumbing directly support the build-context fix and related credential filtering, with no unrelated changes apparent.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/7205-from-managed-agent-dockerfile-context

---

_{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 be87544 in the fix/7205-from-manage... branch remains at 96%, unchanged from commit 1f40cd3 in the main branch.

TypeScript / code-coverage/cli

The overall coverage in commit be87544 in the fix/7205-from-manage... branch remains at 80%, unchanged from commit 1f40cd3 in the main branch.

Show a code coverage summary of the most impacted files.

File	main 1f40cd3	fix/7205-from-manage... be87544	+/-
src/lib/platform.ts	89%	84%	-5%
src/lib/onboard...ontext-stage.ts	98%	94%	-4%
src/lib/inferen...del-registry.ts	100%	97%	-3%
src/lib/agent/base-image.ts	89%	87%	-2%
src/lib/adapter.../auth-config.ts	96%	96%	0%
src/lib/inferen...lama-version.ts	100%	100%	0%
src/lib/messagi...nnels/policy.ts	100%	100%	0%
src/lib/state/m...-acquisition.ts	87%	89%	+2%
src/lib/inferen...time-context.ts	87%	93%	+6%
src/lib/onboard...uild-context.ts	88%	95%	+7%

---

_{Updated July 25, 2026 06:59 UTC}

[coderabbitai]

Actionable comments posted: 1

🤖 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 `@docs/manage-sandboxes/install-plugins-hermes.mdx`:
- Line 51: Replace the em dash in the sentence near “edit the managed Dockerfile
in place” with a comma or parenthetical punctuation, preserving the sentence’s
meaning and wording.

🪄 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: 8969da7b-d508-44ee-94a9-b74552f55cc1

📥 Commits

Reviewing files that changed from the base of the PR and between 3c4ea5a and ec6c425.

📒 Files selected for processing (4)

• docs/manage-sandboxes/install-plugins-hermes.mdx
• docs/reference/commands.mdx
• src/lib/onboard/build-context-stage.test.ts
• src/lib/onboard/build-context-stage.ts

[apurvvkumaria]

Published security remediation in verified commit 22ad159.

• Managed repository-root Docker build contexts now compose the repository .dockerignore with the existing non-negatable credential denylist.
• The standalone Dockerfile-parent staging path remains unchanged.
• A real staged-byte regression test proves the required Hermes COPY sources remain present while .env, .ssh, .aws, .npmrc, secret, PEM, and key canaries stay out even when .dockerignore tries to re-include them.
• The command and Hermes plugin docs now distinguish the managed-root and standalone .dockerignore roots and document that credential exclusions override negation.

Validation:

• managed build-context staging: 11/11
• custom credential filter contracts: 4/4
• Biome and git diff checks: clean
• independent security review: PASS
• documentation review: PASS

The commit is GitHub Verified, DCO signed, and credits the original author, Shawn Xie, as co-author. Exact-head CI and automated review have restarted.

[apurvvkumaria]

Security review PASS for exact head 6663209a775b0c765d3de5c5ba1f39f66ee9c597.

Reviewed all five changed files and the managed/custom staging call sites against the nine-category NemoClaw security checklist. No findings: no secrets or dependencies were added; canonical file comparison handles symlinked managed Dockerfiles; managed repository-root staging uses the existing .dockerignore plus deny-first credential filter; credential-like paths remain excluded even when negated; custom origin and gateway-builder routing are preserved; cleanup and negative-path coverage remain intact. Authentication, cryptography, headers, and endpoint authorization are not applicable to this change.

Exact-head evidence is green: all eight CLI shards, CodeQL/security scans, self-hosted sandbox tests, macOS E2E, E2E gate/coordination, docs build/receipt, DCO, commit lint, and verified commit signatures. Sensitive-path review completed; safe to merge.

[apurvvkumaria]

Fix-forward sync completed: signed merge commit 85957ab03 brings this PR onto current main while preserving all four original contributor commits. The merge was mechanical with no conflicts, and the normal pre-push CLI TypeScript check plus package-version synchronization passed. This new head triggers fresh current-main CI and a new PR Review Advisor event, replacing the stale-base provenance that was the sole deterministic merge-gate blocker.

[apurvvkumaria]

Documentation follow-up completed in signed commit 8cdda3cbf: changed the managed-Dockerfile exception sentence so the colon no longer violates the repository rule that colons introduce lists. Validation: npm run docs passed, including generated-page synchronization, 62 guarded published routes, and Fern validation with 0 errors. The documentation-writer review is being refreshed against this exact head.

[apurvvkumaria]

Final docs grammar follow-up is now on exact head be87544dd in a separate signed commit. The command reference now uses a complete introductory clause without a colon or comma splice. npm run docs passed again: generated variants synchronized, all 62 guarded routes passed, and Fern reported 0 errors. A final exact-head documentation-writer review is in progress.

[apurvvkumaria]

Documentation writer review receipt

• Documentation writer subagent reviewed the completed changes
• Result: docs-updated
• Evidence: docs/reference/commands.mdx; docs/manage-sandboxes/install-plugins-hermes.mdx
• Agent: Codex Desktop

Final exact-head review found no remaining documentation defects.

[apurvvkumaria]

Fix-forward CI triage for exact head be87544dd: the failed installer and CLI shard jobs each hit the global 5-second timeout in unrelated tests (install-station-host-preparation and gateway-recovery). Both pass locally on this exact head without modification: installer 51/51 in 4.36s and gateway recovery 14/14 in 5.15s. I reran only the failed jobs in workflow run 30147859731 (attempt 2) rather than adding unrelated timeout churn to this approved PR.