Skip to content

docs: recommend nemoclaw exec for one-off commands#4117

Merged
cv merged 3 commits into
NVIDIA:mainfrom
glenn-agent:docs/nemoclaw-exec-cli-guide
Jun 3, 2026
Merged

docs: recommend nemoclaw exec for one-off commands#4117
cv merged 3 commits into
NVIDIA:mainfrom
glenn-agent:docs/nemoclaw-exec-cli-guide

Conversation

@glenn-agent

@glenn-agent glenn-agent commented May 23, 2026

Copy link
Copy Markdown
Contributor

Summary

  • recommend nemoclaw <name> exec for one-off in-sandbox commands in the CLI selection guide
  • clarify that openshell sandbox exec is the lower-level bypass path
  • document that NemoClaw exec preserves the sandbox user, HOME=/sandbox, and NemoClaw-provisioned config/routing/policy state

Fixes #4087

Tests

  • npm run docs
  • python3 scripts/docs-to-skills.py docs/ .agents/skills/ --prefix nemoclaw-user --doc-platform fern-mdx --dry-run
  • git diff --check

Signed-off-by: Glenn-Agent glenn_agent@163.com

Summary by CodeRabbit

  • Documentation
    • Clarified CLI selection guidance for when to use openshell vs. nemoclaw for sandbox operations.
    • Improved one-off command examples, showing how to run and verify execution context in both managed and raw sandboxes.
    • Made explicit that openshell exec is for bypassing wrapper/registry behavior while nemoclaw exec is the recommended non-interactive path for managed sandboxes.

Signed-off-by: Glenn-Agent <glenn_agent@163.com>
@copy-pr-bot

copy-pr-bot Bot commented May 23, 2026

Copy link
Copy Markdown

This pull request requires additional validation before any workflows can run on NVIDIA's runners.

Pull request vetters can view their responsibilities here.

Contributors can view more details about this message here.

@coderabbitai

coderabbitai Bot commented May 23, 2026

Copy link
Copy Markdown
Contributor

Review Change Stack

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: 2ea9250f-57b6-4106-9247-ebc14d3b6d96

📥 Commits

Reviewing files that changed from the base of the PR and between d2e1460 and 1e32b95.

📒 Files selected for processing (1)
  • docs/reference/cli-selection-guide.mdx
💤 Files with no reviewable changes (1)
  • docs/reference/cli-selection-guide.mdx

📝 Walkthrough

Walkthrough

Updated CLI selection docs: OpenShell bypass examples now show upload/download + raw exec with HOME verification; Connect section now recommends nemoclaw <name> exec for one-off NemoClaw-managed commands and documents its execution context.

Changes

CLI Selection Guide

Layer / File(s) Summary
One-off command and bypass guidance
docs/reference/cli-selection-guide.mdx
OpenShell bypass examples replaced with openshell sandbox upload/download plus a raw openshell sandbox exec that verifies HOME. The "Connect to the Sandbox" section now recommends nemoclaw <name> exec for one-off commands in NemoClaw-managed sandboxes and documents that it runs as the sandbox user with NemoClaw-provisioned environment; openshell sandbox exec is reserved for intentional bypasses.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Suggested reviewers

  • miyoungc

Poem

🐰 I hopped through docs with a brightened pen,
I nudged execs where they rightly went.
Now nemoclaw leads the one-off way,
openshell stays the raw bypass play.
Hooray for clarity—bash and hop away!

🚥 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 accurately summarizes the main change: recommending nemoclaw exec for one-off commands instead of openshell sandbox exec, which is the primary documentation update in this PR.
Linked Issues check ✅ Passed The PR fully addresses all objectives from issue #4087: recommends nemoclaw exec as primary one-off command, documents its behavior with HOME=/sandbox and NemoClaw-provisioned config, and clarifies openshell sandbox exec as a bypass-only path.
Out of Scope Changes check ✅ Passed The PR contains only documentation changes to cli-selection-guide.mdx that directly address the linked issue #4087 with no extraneous modifications.
Docstring Coverage ✅ Passed No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

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

✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests

Comment @coderabbitai help to get the list of available commands and usage tips.

@wscurran

Copy link
Copy Markdown
Contributor

✨ Thanks for submitting this detailed PR about recommending nemoclaw exec for one-off in-sandbox commands. This proposes a fix to update the CLI selection guide and clarify the usage of openshell sandbox exec as a lower-level bypass path, which improves the documentation and user experience for executing commands in sandboxes.


Related open issues:

@wscurran wscurran added area: cli Command line interface, flags, terminal UX, or output bug-fix PR fixes a bug or regression v0.0.58 Release target area: docs Documentation, examples, guides, or docs build and removed NemoClaw CLI labels Jun 3, 2026
@prekshivyas prekshivyas self-assigned this Jun 3, 2026

@prekshivyas prekshivyas left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks — the content and direction are right (correctly implements #4087: recommend nemoclaw <name> exec, reframe openshell sandbox exec as the lower-level path). Holding approval on two things:

1. Merge conflict — needs a rebase + reformat (blocking). The branch is CONFLICTING. Since this PR was opened, docs/reference/cli-selection-guide.mdx was reformatted on main:

  • code fences changed from ```console (with $ prompts) to ```bash (no $ prompt)
  • prose was rewrapped to one sentence per line (semantic line breaks)

Please rebase on main and re-apply the change in the current house style:

  • use a ```bash fence with no $ prompt for the nemoclaw my-assistant exec -- cat /tmp/gateway.log example
  • split the added explanatory sentences one-per-line to match the surrounding text

2. Wording (non-blocking). I traced nemoclaw <name> exec through the code — it's a thin passthrough: src/commands/sandbox/exec.tsexecSandbox() (src/lib/actions/sandbox/exec.ts) just runs openshell sandbox exec --name <name> ... -- <cmd>, forwarding only --workdir/--tty/--timeout. No env injection or provisioning in the wrapper. So both nemoclaw <name> exec and openshell sandbox exec hit the same OpenShell exec endpoint in the same provisioned sandbox → identical sandbox user, HOME=/sandbox, agent config, inference routing, and policy state (baked in at provision time, not applied per-exec). The real differentiators are NemoClaw registry name resolution and CLI ergonomics, not the execution environment. The current phrasing slightly implies openshell sandbox exec would miss the provisioned config, which isn't the case. Optional tightening:

…use nemoclaw <name> exec. It resolves the sandbox by its NemoClaw registry name and runs through the standard NemoClaw CLI surface. The command executes as the sandbox user with HOME=/sandbox inside the provisioned sandbox (agent config, inference routing, and policy state are already in place). Use openshell sandbox exec for the raw OpenShell path — e.g. addressing a sandbox by its gateway name or bypassing the NemoClaw CLI.

Note this framing traces to #4087's Expected Result, so if there's a governing spec the same tweak may belong upstream. Happy to re-approve once the rebase lands.

Resolve cli-selection-guide.mdx conflict: re-apply the nemoclaw exec
recommendation in the current bash-fence house style (no $ prompt,
sentence-per-line) and tighten the wording so the nemoclaw exec vs
openshell sandbox exec distinction reflects registry/UX, not a
different execution environment.

Signed-off-by: Prekshi Vyas <prekshiv@nvidia.com>

@prekshivyas prekshivyas left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Approving. Pushed a merge of main into this branch (forward-only, no force-push) that resolves the cli-selection-guide.mdx conflict and re-applies the change in the current house style — ```bash fences, no $ prompt, sentence-per-line — matching the rest of the file after the recent reformat.

While resolving I also tightened the wording so the nemoclaw <name> exec vs openshell sandbox exec distinction is accurate: it's about NemoClaw registry name-resolution and the CLI surface, not a different execution environment. (Both paths run through the same OpenShell exec endpoint in the same provisioned sandbox — nemoclaw <name> exec is a thin passthrough in src/lib/actions/sandbox/exec.ts, so the sandbox user, HOME=/sandbox, agent config, inference routing, and policy state are identical either way.)

Net diff is docs-only, MDX parses (docs-to-skills.py --dry-run), git diff --check clean. Branch is now MERGEABLE. Good for v0.0.58 once checks go green.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

area: cli Command line interface, flags, terminal UX, or output area: docs Documentation, examples, guides, or docs build bug-fix PR fixes a bug or regression v0.0.58 Release target

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[NemoClaw][All Platforms][Docs] CLI Selection Guide still recommends openshell sandbox exec instead of nemoclaw exec for one-off sandbox commands

4 participants