feat(cli): add nemoclaw use to set default sandbox

[laitingsheng]

Summary

Adds a first-class nemoclaw use <name> command that promotes a registered sandbox to the default. Closes the discoverability gap where the only post-onboard mechanism to change the default was hand-editing ~/.nemoclaw/sandboxes.json.

Related Issue

Fixes #5923

Changes

• New oclif command src/commands/use.ts wires through to the existing atomic, lock-guarded registry.setDefault already used by onboard finalisation, recovery, and default-preservation paths.
• New src/lib/use-command-deps.ts exposes a pure runUseCommand that classifies the outcome (set, already-default, not-found) with the previous default and the known-sandbox list, plus a deps builder for the oclif shim.
• Sandbox Management help entry placed at order 2.5 so nemoclaw use lands between list and <name> connect in nemoclaw --help.
• docs/reference/commands.mdx gains a ### nemoclaw use <name> section; the Hermes variant commands-nemohermes.mdx synced through npm run docs:sync-agent-variants.
• 5 behaviour-oriented tests cover unknown sandbox, already-default short-circuit, set with previous default, first default from null, and the concurrent-removal race where setDefault returns false.

Type of Change

• Code change with doc updates
• Code change (feature, bug fix, or refactor)
• 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:
• Non-success, skipped, or missing CI check accepted by maintainer — check name, approval link, and follow-up issue:

Verification

• PR description includes the DCO sign-off declaration and every commit appears as Verified in GitHub
• Git hooks passed during commit and push, or npx prek run --from-ref main --to-ref HEAD passes
• Targeted tests pass for changed behavior — npx vitest run --project=cli src/commands src/lib/use-command-deps.test.ts (93 + 5 passed)
• Full npm test passes (broad runtime changes only)
• 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) — npm run docs:sync-agent-variants clean
• Doc pages follow the style guide (doc changes only)
• New doc pages include SPDX header and frontmatter (new pages only)

CLI parity check passes locally: bash test/e2e/e2e-cloud-experimental/check-docs.sh --only-cli lists nemoclaw use <name> from both nemoclaw --help and docs/reference/commands.mdx. Static checks pass: npx tsx scripts/checks/run.ts.

---

Signed-off-by: Tinson Lai tinsonl@nvidia.com

Summary by CodeRabbit

• New Features
  • Added use <name> command to promote a registered sandbox as the default (including $$nemoclaw use <name>), with plain and --json output showing updated/already-default/unknown states.
  • Updated the public command display to include use under Sandbox Management.
• Documentation
  • Added CLI command reference entries and quickstart guidance for choosing the default sandbox.
• Tests
  • Added unit and alias/integration tests covering successful promotion, already-default behavior, unknown names, and concurrent-removal edge cases.

[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

Adds a new use command that promotes a registered sandbox to the default, updates CLI discovery and alias help, and adds reference and quickstart documentation for the new default-selection flow.

Changes

use command: logic, CLI, tests, and docs

Layer / File(s)	Summary
UseCommandDeps and runUseCommand src/lib/use-command-deps.ts, src/lib/use-command-deps.test.ts	Defines the dependency interface, result union, registry wiring, and command execution flow for selecting, reusing, or rejecting a default sandbox. Tests cover unknown names, already-default selection, promotion, no-default initialization, and failed registry updates with refreshed sandbox lists.
UseCommand and command discovery src/commands/use.ts, src/lib/cli/public-display-defaults.ts, test/package-contract/cli/command-registry.test.ts	Implements the Oclif UseCommand with JSON output handling and outcome-specific messaging, adds the use entry to public command display metadata, and updates the command registry test to include the new global token.
Command reference and quickstart docs docs/reference/commands.mdx, docs/reference/commands-nemohermes.mdx, docs/get-started/quickstart-langchain-deepagents-code.mdx	Adds use <name> documentation to the command reference pages and the Deep Agents quickstart, including the default-sandbox promotion behavior, registry update semantics, no-sandbox-mutation wording, JSON result modes, and usage examples.
Deep Agents alias help and integration test test/nemo-deepagents-alias.test.ts	Updates the nemo-deepagents help expectations to surface use <name>, and adds an integration test that runs use dcode-beta against a temporary registry and checks the updated default sandbox value and output.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Suggested labels

area: onboarding, area: docs

Suggested reviewers

• cv
• jyaunches
• prekshivyas

🚥 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 clearly names the new CLI command and its purpose of setting the default sandbox.
Linked Issues check	✅ Passed	The PR adds a first-class nemoclaw use <name> command, help visibility, atomic default updates, and validation for issue #5923.
Out of Scope Changes check	✅ Passed	The docs, alias surfaces, and tests all support the new default-sandbox command rather than introducing unrelated changes.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/use-default-sandbox

---

_{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 the feat/use-default-san... branch is 96%. Coverage data for the main branch is not yet available.

Show a code coverage summary of the most covered files.

File	main	feat/use-default-san... fcf9269	+/-
nemoclaw/src/se...cret-scanner.ts	—	100%	—
nemoclaw/src/commands/slash.ts	—	100%	—
nemoclaw/src/li...bprocess-env.ts	—	100%	—
nemoclaw/src/bl...eprint/state.ts	—	98%	—
nemoclaw/src/onboard/config.ts	—	98%	—
nemoclaw/src/bl...int/snapshot.ts	—	97%	—
nemoclaw/src/bl...print/runner.ts	—	95%	—
nemoclaw/src/co...ration-state.ts	—	94%	—
nemoclaw/src/bl...ate-networks.ts	—	94%	—
nemoclaw/src/index.ts	—	94%	—

TypeScript / code-coverage/cli

The overall coverage in the feat/use-default-san... branch is 68%. Coverage data for the main branch is not yet available.

Show a code coverage summary of the most covered files.

File	main	feat/use-default-san... fcf9269	+/-
src/lib/actions...all/run-plan.ts	—	80%	—
src/lib/state/o...oard-session.ts	—	79%	—
src/lib/actions...dbox/rebuild.ts	—	74%	—
src/lib/state/sandbox.ts	—	72%	—
src/lib/shields/index.ts	—	70%	—
src/lib/onboard/preflight.ts	—	69%	—
src/lib/actions...licy-channel.ts	—	59%	—
src/lib/onboard...er-gpu-patch.ts	—	59%	—
src/lib/policy/index.ts	—	52%	—
src/lib/onboard.ts	—	20%	—

---

_{Updated June 28, 2026 22:52 UTC
Code Coverage is in Public Preview. Learn more and provide us with your feedback.}

[github-actions]

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

[github-actions]

PR Review Advisor — No blocking findings

Merge posture: No blocking advisor findings
Primary next action: No advisor follow-up required beyond maintainer review.
Open items: 0 required · 0 warnings · 0 suggestions · 0 test follow-ups
Since last review: 1 prior item resolved · 0 still apply · 0 new items found

Workflow run details

This is an automated, non-binding review; it still expects maintainers and agents to respond to each required or warning item. Treat suggestions as current-PR improvements when they touch changed code; defer only with maintainer rationale or a linked follow-up. A human maintainer must make the final merge decision.

[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 `@src/lib/use-command-deps.ts`:
- Around line 46-48: The `setDefault()` failure path in `use-command-deps` is
using a stale `known` snapshot when returning `not-found`, which can produce
contradictory sandbox lists. In the `setDefault(sandboxName)` branch, refresh
the registry state before constructing the `{ outcome: "not-found", sandboxName,
knownSandboxes: ... }` result so `knownSandboxes` reflects the latest sandbox
set after a concurrent removal. Use the `deps.setDefault` and `knownSandboxes`
return path in `use-command-deps.ts` to locate the fix.

🪄 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: c0979ef6-90f3-466c-9983-577dc1b877da

📥 Commits

Reviewing files that changed from the base of the PR and between 4db5d5d and 656ce71.

📒 Files selected for processing (6)

• docs/reference/commands-nemohermes.mdx
• docs/reference/commands.mdx
• src/commands/use.ts
• src/lib/cli/public-display-defaults.ts
• src/lib/use-command-deps.test.ts
• src/lib/use-command-deps.ts

[github-actions]

E2E Advisor Recommendation

Required E2E: sandbox-operations-e2e
Optional E2E: launchable-smoke-e2e, ubuntu-repo-cloud-langchain-deepagents-code

Dispatch hint: sandbox-operations-e2e

Workflow run

Full advisor summary

E2E Recommendation Advisor

Base: origin/main
Head: HEAD
Confidence: high

Required E2E

• sandbox-operations-e2e: This is a sandbox-management registry change. The sandbox operations lane creates and manages real registered sandboxes on a fresh install, exercising the live registry/list/status/operation paths most likely to be affected by adding a default-sandbox selector.

Optional E2E

• launchable-smoke-e2e: Useful extra confidence that the newly registered public command and help/display metadata do not break the installed launchable CLI path, basic help, onboarding, list, status, and live inference smoke flow.
• ubuntu-repo-cloud-langchain-deepagents-code: Optional Deep Agents confidence because the PR updates the nemo-deepagents use user-facing path. The existing Deep Agents live scenario validates the real Deep Agents sandbox runtime, though it does not directly exercise the new selector command.

New E2E recommendations

• default sandbox selector (high): No existing live E2E appears to directly run nemoclaw use <name> against multiple real registered sandboxes and then verify subsequent default-resolving commands target the promoted sandbox.
  • Suggested test: Add a focused live E2E step, likely in sandbox-operations, that onboards/registers two sandboxes, runs nemoclaw use <second>, checks text and --json outcomes, verifies defaultSandbox changed, and proves a default-resolving command uses the selected sandbox.
• Deep Agents alias selector (medium): Existing unit/package tests cover nemo-deepagents use, but there is no live E2E proving the installed alias can promote a real registered Deep Agents Code sandbox without mutating the sandbox runtime.
  • Suggested test: Extend the Deep Agents live scenario or add a small alias smoke to run nemo-deepagents use <deepagents-sandbox> and verify registry default selection plus no change to /sandbox/.deepagents/config.toml.

Dispatch hint

• Workflow: nightly-e2e.yaml
• jobs input: sandbox-operations-e2e

[github-actions]

Vitest E2E Scenario Recommendation

Required Vitest E2E scenarios: ubuntu-repo-cloud-langchain-deepagents-code
Optional Vitest E2E scenarios: ubuntu-repo-cloud-openclaw

Dispatch required Vitest E2E scenarios:

• gh workflow run e2e-vitest-scenarios.yaml --ref <pr-head-ref> --field scenarios=ubuntu-repo-cloud-langchain-deepagents-code

Workflow run

Full Vitest E2E advisor summary

Vitest E2E Scenario Advisor

Base: origin/main
Head: HEAD
Confidence: medium

Required Vitest E2E scenarios

• ubuntu-repo-cloud-langchain-deepagents-code: The PR adds a default-sandbox selector command and documents/tests the nemo-deepagents alias path. This is the smallest live-supported typed scenario covering a real Deep Agents Code repo CLI onboarding with host registry/default-sandbox state.
  • Dispatch: gh workflow run e2e-vitest-scenarios.yaml --ref <pr-head-ref> --field scenarios=ubuntu-repo-cloud-langchain-deepagents-code

Optional Vitest E2E scenarios

• ubuntu-repo-cloud-openclaw: Optional adjacent coverage for the generic nemoclaw default-sandbox command surface on the primary OpenClaw onboarding path, separate from the Deep Agents alias path.
  • Dispatch: gh workflow run e2e-vitest-scenarios.yaml --ref <pr-head-ref> --field scenarios=ubuntu-repo-cloud-openclaw

Relevant changed files

• src/commands/use.ts
• src/lib/cli/public-display-defaults.ts
• src/lib/use-command-deps.ts

[github-actions]

Selective E2E Results — ✅ All requested jobs passed

Run: 28322935846
Target ref: 656ce7141e05c3041e0b9b26dcd4187ff72b8958
Workflow ref: main
Requested jobs: docs-validation-e2e
Summary: 1 passed, 0 failed, 0 cancelled, 0 skipped

Job	Result
docs-validation-e2e	✅ success

[github-actions]

PR Review Advisor (Nemotron Ultra) — No blocking findings

Merge posture: No blocking advisor findings
Primary next action: Add or justify PRA-T1 and any related test follow-ups.
Open items: 0 required · 0 warnings · 3 suggestions · 2 test follow-ups
Since last review: 3 prior items resolved · 0 still apply · 0 new items found

Action checklist

• PRA-T1 Add or justify test follow-up: Integration tests for alias command error cases now present
• PRA-T2 Add or justify test follow-up: Test follow-up for alias command error cases addressed
• PRA-1 In-scope improvement: Integration tests for alias command error cases now present in test/nemo-deepagents-alias.test.ts:68
• PRA-2 In-scope improvement: TOCTOU avoidance comment added for race-condition handling in src/lib/use-command-deps.ts:38
• PRA-3 In-scope improvement: Test follow-up for alias command error cases addressed in test/nemo-deepagents-alias.test.ts:68

Findings index

ID	Severity	Category	Location	Required action
PRA-1	Improvement	tests	test/nemo-deepagents-alias.test.ts:68	No action needed — resolved in this PR.
PRA-2	Improvement	security	src/lib/use-command-deps.ts:38	No action needed — resolved in this PR.
PRA-3	Improvement	tests	test/nemo-deepagents-alias.test.ts:68	No action needed — resolved in this PR.

Review findings by urgency: 0 required fixes, 0 items to resolve/justify, 3 in-scope improvements

⚠️ Resolve or justify before merge

Investigate these in the current review; either fix them, explain why they are not applicable, or document the accepted risk.

• None.

💡 In-scope improvements

These are lower-risk, not throwaway. Prefer fixing them in this PR when they are local to changed code; defer only with rationale or a linked follow-up.

PRA-1 Improvement — Integration tests for alias command error cases now present

• Location: test/nemo-deepagents-alias.test.ts:68
• Category: tests
• Problem: Three integration tests cover: happy path promotion, already-default case, and not-found with --json output. Resolves prior review item PRA-1.
• Impact: Lower confidence in CLI wiring for error paths through nemo-deepagents alias; unit tests already validated core logic. Now fully covered.
• Suggested action: No action needed — resolved in this PR.
• Expected follow-up: Prefer a current-PR fix when local to changed code; defer only with rationale or linked follow-up.
• Verification: Run vitest on test/nemo-deepagents-alias.test.ts and verify three 'use' tests pass: 'promotes a registered Deep Agents sandbox through the alias command', 'reports an already-default Deep Agents sandbox through the alias command', 'returns structured not-found output through the alias command'.
• Missing regression test: Integration tests for: nemo-deepagents use unknown-sandbox (exit 1, known list), nemo-deepagents use already-default (exit 0, 'already the default'), nemo-deepagents use name --json (structured output). Now present in test/nemo-deepagents-alias.test.ts lines 68-150.
• Done when: The local improvement is applied, or the PR notes why it should be deferred.
• Evidence: test/nemo-deepagents-alias.test.ts lines 68-150 has three 'use' tests. src/lib/use-command-deps.test.ts lines 24-106 has 6 unit tests covering all branches.

PRA-2 Improvement — TOCTOU avoidance comment added for race-condition handling

• Location: src/lib/use-command-deps.ts:38
• Category: security
• Problem: Comment explains: 'setDefault rechecks existence under the registry lock. Refresh after a concurrent removal so the not-found diagnostic reflects post-lock state.' Resolves prior review item PRA-2.
• Impact: Maintainer may not recognize the deliberate race-condition handling without reading registry.setDefault implementation. Now documented inline.
• Suggested action: No action needed — resolved in this PR.
• Expected follow-up: Prefer a current-PR fix when local to changed code; defer only with rationale or linked follow-up.
• Verification: Read src/lib/use-command-deps.ts lines 37-50 and src/lib/state/registry.ts lines 529-537 to confirm atomic check-and-set under lock.
• Missing regression test: Existing test at src/lib/use-command-deps.test.ts lines 81-106 covers the race: setDefault returns false, then listSandboxes is called again and the refreshed list excludes the concurrently removed sandbox.
• Done when: The local improvement is applied, or the PR notes why it should be deferred.
• Evidence: src/lib/use-command-deps.ts lines 37-50 show the pattern: setDefault called, if false then listSandboxes refreshes. src/lib/state/registry.ts lines 529-537 show setDefault uses withLock for atomic check-and-set.

PRA-3 Improvement — Test follow-up for alias command error cases addressed

• Location: test/nemo-deepagents-alias.test.ts:68
• Category: tests
• Problem: Test follow-up from previous review (PRA-T1) requesting integration tests for alias command error cases. Addressed by the three new integration tests. Resolves prior review item PRA-3.
• Impact: Same as first finding — CLI wiring confidence now verified end-to-end.
• Suggested action: No action needed — resolved in this PR.
• Expected follow-up: Prefer a current-PR fix when local to changed code; defer only with rationale or linked follow-up.
• Verification: Run vitest on test/nemo-deepagents-alias.test.ts and verify three 'use' tests pass.
• Missing regression test: Same as first finding — now covered.
• Done when: The local improvement is applied, or the PR notes why it should be deferred.
• Evidence: test/nemo-deepagents-alias.test.ts lines 68-150 now has three integration tests for 'use' command error cases.

Test follow-ups to resolve or justify

If these cover changed behavior, prefer adding them in this PR; otherwise state why existing coverage is enough or link the follow-up.

• PRA-T1 Integration tests for alias command error cases now present — No action needed — resolved in this PR.
• PRA-T2 Test follow-up for alias command error cases addressed — No action needed — resolved in this PR.

Since last review details

Current findings, using the urgency labels above:

PRA-1 Improvement — Integration tests for alias command error cases now present

• Location: test/nemo-deepagents-alias.test.ts:68
• Category: tests
• Problem: Three integration tests cover: happy path promotion, already-default case, and not-found with --json output. Resolves prior review item PRA-1.
• Impact: Lower confidence in CLI wiring for error paths through nemo-deepagents alias; unit tests already validated core logic. Now fully covered.
• Suggested action: No action needed — resolved in this PR.
• Expected follow-up: Prefer a current-PR fix when local to changed code; defer only with rationale or linked follow-up.
• Verification: Run vitest on test/nemo-deepagents-alias.test.ts and verify three 'use' tests pass: 'promotes a registered Deep Agents sandbox through the alias command', 'reports an already-default Deep Agents sandbox through the alias command', 'returns structured not-found output through the alias command'.
• Missing regression test: Integration tests for: nemo-deepagents use unknown-sandbox (exit 1, known list), nemo-deepagents use already-default (exit 0, 'already the default'), nemo-deepagents use name --json (structured output). Now present in test/nemo-deepagents-alias.test.ts lines 68-150.
• Done when: The local improvement is applied, or the PR notes why it should be deferred.
• Evidence: test/nemo-deepagents-alias.test.ts lines 68-150 has three 'use' tests. src/lib/use-command-deps.test.ts lines 24-106 has 6 unit tests covering all branches.

PRA-2 Improvement — TOCTOU avoidance comment added for race-condition handling

• Location: src/lib/use-command-deps.ts:38
• Category: security
• Problem: Comment explains: 'setDefault rechecks existence under the registry lock. Refresh after a concurrent removal so the not-found diagnostic reflects post-lock state.' Resolves prior review item PRA-2.
• Impact: Maintainer may not recognize the deliberate race-condition handling without reading registry.setDefault implementation. Now documented inline.
• Suggested action: No action needed — resolved in this PR.
• Expected follow-up: Prefer a current-PR fix when local to changed code; defer only with rationale or linked follow-up.
• Verification: Read src/lib/use-command-deps.ts lines 37-50 and src/lib/state/registry.ts lines 529-537 to confirm atomic check-and-set under lock.
• Missing regression test: Existing test at src/lib/use-command-deps.test.ts lines 81-106 covers the race: setDefault returns false, then listSandboxes is called again and the refreshed list excludes the concurrently removed sandbox.
• Done when: The local improvement is applied, or the PR notes why it should be deferred.
• Evidence: src/lib/use-command-deps.ts lines 37-50 show the pattern: setDefault called, if false then listSandboxes refreshes. src/lib/state/registry.ts lines 529-537 show setDefault uses withLock for atomic check-and-set.

PRA-3 Improvement — Test follow-up for alias command error cases addressed

• Location: test/nemo-deepagents-alias.test.ts:68
• Category: tests
• Problem: Test follow-up from previous review (PRA-T1) requesting integration tests for alias command error cases. Addressed by the three new integration tests. Resolves prior review item PRA-3.
• Impact: Same as first finding — CLI wiring confidence now verified end-to-end.
• Suggested action: No action needed — resolved in this PR.
• Expected follow-up: Prefer a current-PR fix when local to changed code; defer only with rationale or linked follow-up.
• Verification: Run vitest on test/nemo-deepagents-alias.test.ts and verify three 'use' tests pass.
• Missing regression test: Same as first finding — now covered.
• Done when: The local improvement is applied, or the PR notes why it should be deferred.
• Evidence: test/nemo-deepagents-alias.test.ts lines 68-150 now has three integration tests for 'use' command error cases.

Workflow run details

This is an automated, non-binding review; it still expects maintainers and agents to respond to each required or warning item. Treat suggestions as current-PR improvements when they touch changed code; defer only with maintainer rationale or a linked follow-up. A human maintainer must make the final merge decision.