feat(cli): add Deep Agents aliases (#5881)

<!-- markdownlint-disable MD041 -->
## Summary
Adds a `nemo-deepagents` host CLI alias for the LangChain Deep Agents
Code runtime and teaches onboarding to accept common user-facing agent
aliases. This lets users run `nemo-deepagents onboard` or shorter forms
such as `nemoclaw onboard --agent dcode`, `--agent deepagents`, and
`--agent langchain` instead of remembering `langchain-deepagents-code`.

## Changes
- Registered `nemo-deepagents` as an npm bin that reuses the existing
`bin/nemoclaw.js` launcher and selects Deep Agents Code when invoked
through that symlink.
- Added canonical agent alias resolution for `--agent` and
`NEMOCLAW_AGENT`, including `nemohermes`, `dcode`, `deepagents`,
`deepagents-code`, `langchain`, and related variants.
- Updated CLI branding, installer/update branding, onboard `--agent`
help, and unknown-agent diagnostics for the alias set.
- Updated Deep Agents quickstart, command reference, and platform
support docs; adjusted platform-doc validation to allow documented
aliases.
- Added/updated tests for CLI alias behavior, onboarding arg
parsing/help, agent definition alias resolution, update copy, oclif
help, and platform-doc validation.

## Type of Change

- [ ] Code change (feature, bug fix, or refactor)
- [x] Code change with doc updates
- [ ] Doc only (prose changes, no code sample modifications)
- [ ] Doc only (includes code sample changes)

## Quality Gates
<!-- Check all that apply. For any "covered by existing tests", "not
applicable", or waiver entry, add a brief justification on the same line
or in the Changes section. -->
- [x] Tests added or updated for changed behavior
- [ ] Existing tests cover changed behavior — justification:
- [ ] Tests not applicable — justification:
- [x] Docs updated for user-facing behavior changes
- [ ] Docs not applicable — justification:
- [x] Sensitive paths changed (security, policy, credentials, preflight,
onboarding, inference, runner, sandbox, or messaging)
- [x] Sensitive-path review completed or maintainer-approved waiver
recorded — reviewer/approval link/justification: self-review; changes
are limited to agent selector canonicalization, launcher branding,
installer alias selection, docs, and tests, with no credential handling
or network-policy enforcement changes.
- [ ] Non-success, skipped, or missing CI check accepted by maintainer —
check name, approval link, and follow-up issue:

## Verification
<!-- Check each item you ran and confirmed. Leave unchecked items you
skipped. Doc-only changes do not require npm test unless you ran it. -->
- [x] PR description includes the DCO sign-off declaration and every
commit appears as `Verified` in GitHub
- [x] Git hooks passed during commit and push, or `npx prek run
--from-ref main --to-ref HEAD` passes
- [x] Targeted tests pass for changed behavior
- [ ] Full `npm test` passes (broad runtime changes only)
- [x] Quality Gates section completed with required justifications or
waivers
- [x] No secrets, API keys, or credentials committed
- [ ] `npm run docs` builds without warnings (doc changes only)
- [x] Doc pages follow the [style
guide](https://github.com/NVIDIA/NemoClaw/blob/main/docs/CONTRIBUTING.md)
(doc changes only)
- [ ] New doc pages include SPDX header and frontmatter (new pages only)

Verification commands run:
- `npm run build:cli`
- `npx vitest run test/nemohermes-alias.test.ts
test/nemo-deepagents-alias.test.ts test/update.test.ts
test/cli-oclif-compatibility.test.ts src/lib/cli/branding.test.ts
src/lib/actions/update.test.ts src/lib/agent/defs.test.ts
src/lib/onboard/legacy-command.test.ts
src/lib/onboard/agent-flag-help.test.ts
src/lib/onboard/command-support.test.ts test/cli/dispatch-basics.test.ts
test/generate-platform-docs.test.ts --reporter=dot`
- `NEMOCLAW_RUN_INSTALLER_TESTS=1 npx vitest run --project
installer-integration test/install-preflight.test.ts --reporter=dot`
- `npm run typecheck:cli`
- `npm run validate:configs`
- `python3 scripts/generate-platform-docs.py --check`
- `npm run docs` (passed; Fern reported two hidden warnings)
- Commit hooks passed; latest push hooks passed.

---
<!-- DCO sign-off is required in this PR description, and every commit
must appear as Verified in GitHub. Run: git config user.name && git
config user.email -->
Signed-off-by: Carlos Villela <cvillela@nvidia.com>


<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

* **New Features**
* Added a `nemo-deepagents` CLI alias for Deep Agents with matching
branding, help, onboarding, uninstall, and update flows.
* **Documentation**
* Updated quickstart and command/reference docs to use the Deep Agents
CLI wrapper and clarified `--agent` alias vs canonical name behavior.
* Refreshed platform support/onboarding matrix entries for the new
alias.
* **Bug Fixes**
* Improved agent selector alias resolution and enhanced “unknown agent”
guidance with supported alias mappings.
  * Sanitized Deep Agents update environment variables during installs.
* **Tests**
* Added/expanded coverage for Deep Agents alias behavior and alias
canonicalization.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

Author: cv

bin/nemoclaw.js

@@ -3,4 +3,10 @@
 // SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
 // SPDX-License-Identifier: Apache-2.0
 
+const invokedAs = require("node:path").basename(process.argv[1] || "");
+if (invokedAs === "nemo-deepagents") {
+  process.env.NEMOCLAW_AGENT = "langchain-deepagents-code";
+  process.env.NEMOCLAW_INVOKED_AS = "nemo-deepagents";
+}
+
 require("../dist/nemoclaw");

ci/platform-matrix.json

@@ -162,7 +162,7 @@
       "name": "LangChain Deep Agents Code",
       "status": "experimental",
       "default": false,
-      "notes": "Terminal-oriented coding harness (no in-sandbox gateway, no dashboard) built on the Deep Agents SDK; manifest at `agents/langchain-deepagents-code/manifest.yaml` with binary `dcode`. Onboard with `$$nemoclaw onboard --agent langchain-deepagents-code` and follow [the quickstart](../get-started/quickstart-langchain-deepagents-code). NemoClaw runs it as a managed harness: unmanaged sandbox/MCP/shell overrides are rejected and credential-bearing proxy URLs are dropped from persisted shell env. Inference routes through OpenShell's `inference.local` endpoint via Deep Agents Code's OpenAI-compatible provider. Live runtime acceptance, broader launch material, and terminal-agent diagnostics are tracked at open issue #4861."
+      "notes": "Terminal-oriented coding harness (no in-sandbox gateway, no dashboard) built on the Deep Agents SDK; manifest at `agents/langchain-deepagents-code/manifest.yaml` with binary `dcode`. Onboard with `$$nemo-deepagents onboard` or `$$nemoclaw onboard --agent langchain-deepagents-code`, and follow [the quickstart](../get-started/quickstart-langchain-deepagents-code). NemoClaw runs it as a managed harness: unmanaged sandbox/MCP/shell overrides are rejected and credential-bearing proxy URLs are dropped from persisted shell env. Inference routes through OpenShell's `inference.local` endpoint via Deep Agents Code's OpenAI-compatible provider. Live runtime acceptance, broader launch material, and terminal-agent diagnostics are tracked at open issue #4861."
     }
   ],
 

docs/get-started/quickstart-langchain-deepagents-code.mdx

@@ -19,10 +19,16 @@ Use this guide to build an OpenShell sandbox with the `dcode` terminal coding ag
 
 ## Onboard
 
-Run onboarding with the canonical agent ID.
+Run onboarding with the Deep Agents alias, or use `nemoclaw --agent` with either the canonical agent ID or a short alias.
 
 ```bash
+nemo-deepagents onboard
+# Equivalent:
 nemoclaw onboard --agent langchain-deepagents-code
+# Also accepted:
+nemoclaw onboard --agent dcode
+nemoclaw onboard --agent deepagents
+nemoclaw onboard --agent langchain
 ```
 
 The image installs a hash-locked, pinned Deep Agents Code release with NVIDIA provider support.
@@ -71,9 +77,9 @@ To enable Tavily, apply the maintained `tavily` policy preset so the sandbox may
 
 ```bash
 # Preview the endpoints the preset opens:
-nemoclaw <sandbox-name> policy-add tavily --dry-run
+nemo-deepagents <sandbox-name> policy-add tavily --dry-run
 # Apply it:
-nemoclaw <sandbox-name> policy-add tavily --yes
+nemo-deepagents <sandbox-name> policy-add tavily --yes
 ```
 
 The `tavily` preset only opens egress to `api.tavily.com:443`.
@@ -83,7 +89,7 @@ Because OpenShell attributes the harness's calls to the sandbox `python3` interp
 Remove the access again when it is no longer needed.
 
 ```bash
-nemoclaw <sandbox-name> policy-remove tavily --yes
+nemo-deepagents <sandbox-name> policy-remove tavily --yes
 ```
 
 ### Optional Tracing (LangSmith)
@@ -95,13 +101,13 @@ Treat it as unsupported until NemoClaw ships a maintained `langsmith` preset.
 
 ## Troubleshooting
 
-Use normal sandbox lifecycle commands.
+Use normal sandbox lifecycle commands through either `nemo-deepagents` or `nemoclaw`:
 
 ```bash
-nemoclaw <sandbox-name> status
-nemoclaw <sandbox-name> logs --follow
-nemoclaw <sandbox-name> rebuild
-nemoclaw <sandbox-name> snapshot create --name before-change
+nemo-deepagents <sandbox-name> status
+nemo-deepagents <sandbox-name> logs --follow
+nemo-deepagents <sandbox-name> rebuild
+nemo-deepagents <sandbox-name> snapshot create --name before-change
 ```
 
 `status` reports the selected harness as a terminal runtime and prints the interactive/headless command shape.

docs/reference/commands-nemohermes.mdx

@@ -103,6 +103,9 @@ nemohermes onboard [options]
 nemoclaw onboard --agent hermes [options]
 ```
 
+`--agent` accepts the canonical manifest names from `nemohermes agents list` plus common aliases.
+For example, `nemohermes` resolves to `hermes`, while `dcode`, `deepagents`, `deepagents-code`, and `langchain` resolve to `langchain-deepagents-code`.
+
 #### `--resume` and `--fresh`
 
 NemoClaw records onboarding progress so interrupted runs can continue.

docs/reference/commands.mdx

@@ -144,6 +144,9 @@ nemoclaw onboard --agent hermes [options]
 
 </AgentOnly>
 
+`--agent` accepts the canonical manifest names from `$$nemoclaw agents list` plus common aliases.
+For example, `nemohermes` resolves to `hermes`, while `dcode`, `deepagents`, `deepagents-code`, and `langchain` resolve to `langchain-deepagents-code`.
+
 #### `--resume` and `--fresh`
 
 NemoClaw records onboarding progress so interrupted runs can continue.

docs/reference/platform-support.mdx

@@ -65,7 +65,7 @@ Pick the matching onboarding entry point for each agent.
 |-------|--------|---------|-------|
 | OpenClaw | Tested | Yes | Default agent runtime. Onboard with `$$nemoclaw onboard` (no `--agent` flag required). |
 | Hermes | Tested with limitations | No | First-class agent with dedicated CLI (`$$nemohermes`), Dockerfile, manifest, docs, and nightly E2E job coverage (`hermes-e2e` job in `.github/workflows/nightly-e2e.yaml` plus the `hermes-*-vitest` jobs in `e2e-vitest-scenarios.yaml`). Onboard with `$$nemohermes onboard` or pass `--agent hermes` to `$$nemoclaw onboard`. Unlocks the Hermes Provider inference route. Known structural gaps: model-provider compatibility registry is empty (backfilled after failures, see `nemoclaw-blueprint/model-specific-setup/hermes/README.md`); no Hermes-specific unit tests in `nemoclaw/src/`; macOS and WSL CI suites do not differentiate agents. Suitable for evaluation and the documented onboarding paths; production parity with OpenClaw is not yet asserted. |
-| LangChain Deep Agents Code | Experimental | No | Terminal-oriented coding harness (no in-sandbox gateway, no dashboard) built on the Deep Agents SDK; manifest at `agents/langchain-deepagents-code/manifest.yaml` with binary `dcode`. Onboard with `$$nemoclaw onboard --agent langchain-deepagents-code` and follow [the quickstart](../get-started/quickstart-langchain-deepagents-code). NemoClaw runs it as a managed harness: unmanaged sandbox/MCP/shell overrides are rejected and credential-bearing proxy URLs are dropped from persisted shell env. Inference routes through OpenShell's `inference.local` endpoint via Deep Agents Code's OpenAI-compatible provider. Live runtime acceptance, broader launch material, and terminal-agent diagnostics are tracked at open issue #4861. |
+| LangChain Deep Agents Code | Experimental | No | Terminal-oriented coding harness (no in-sandbox gateway, no dashboard) built on the Deep Agents SDK; manifest at `agents/langchain-deepagents-code/manifest.yaml` with binary `dcode`. Onboard with `$$nemo-deepagents onboard` or `$$nemoclaw onboard --agent langchain-deepagents-code`, and follow [the quickstart](../get-started/quickstart-langchain-deepagents-code). NemoClaw runs it as a managed harness: unmanaged sandbox/MCP/shell overrides are rejected and credential-bearing proxy URLs are dropped from persisted shell env. Inference routes through OpenShell's `inference.local` endpoint via Deep Agents Code's OpenAI-compatible provider. Live runtime acceptance, broader launch material, and terminal-agent diagnostics are tracked at open issue #4861. |
 {/* agent-status:end */}
 
 ## Platforms

package-lock.json

@@ -6,7 +6,8 @@
   "license": "Apache-2.0",
   "bin": {
     "nemoclaw": "./bin/nemoclaw.js",
-    "nemohermes": "./bin/nemohermes.js"
+    "nemohermes": "./bin/nemohermes.js",
+    "nemo-deepagents": "./bin/nemoclaw.js"
   },
   "oclif": {
     "bin": "nemoclaw",

package.json

@@ -107,6 +107,7 @@ installer_version_for_display() {
 agent_display_name() {
   case "${1:-}" in
     hermes) printf "Hermes" ;;
+    langchain-deepagents-code) printf "LangChain Deep Agents Code" ;;
     openclaw | "") printf "OpenClaw" ;;
     *)
       local first rest
@@ -117,6 +118,25 @@ agent_display_name() {
   esac
 }
 
+canonical_agent_name() {
+  local raw="${1:-}" normalized
+  normalized="$(printf "%s" "$raw" | tr '[:upper:]_ ' '[:lower:]--' | sed -E 's/-+/-/g; s/^-//; s/-$//')"
+  case "$normalized" in
+    nemoclaw | nemo-claw | openclaw)
+      printf "openclaw"
+      ;;
+    nemohermes | nemo-hermes | hermes)
+      printf "hermes"
+      ;;
+    nemo-deepagents | nemo-deepagent | nemodeepagents | nemodeepagent | dcode | deepagent | deepagents | deep-agent | deep-agents | deepagentcode | deepagentscode | deepagent-code | deepagents-code | deep-agent-code | deep-agents-code | langchain | langchain-code | langchaindeepagent | langchaindeepagents | langchain-deepagent | langchain-deepagents | langchaindeepagentcode | langchaindeepagentscode | langchain-deepagent-code | langchain-deepagents-code | langchain-deep-agent | langchain-deep-agents | langchain-deep-agent-code | langchain-deep-agents-code)
+      printf "langchain-deepagents-code"
+      ;;
+    *)
+      printf "%s" "$raw"
+      ;;
+  esac
+}
+
 # Resolve which Git ref to install from.
 # Priority: NEMOCLAW_INSTALL_TAG env var > lkg tag.
 resolve_release_tag() {
@@ -269,9 +289,14 @@ resolve_default_sandbox_name() {
   fi
 
   local fallback="my-assistant"
-  if [[ "${NEMOCLAW_AGENT:-}" == "hermes" ]]; then
-    fallback="hermes"
-  fi
+  case "${NEMOCLAW_AGENT:-}" in
+    hermes)
+      fallback="hermes"
+      ;;
+    langchain-deepagents-code)
+      fallback="deepagents-code"
+      ;;
+  esac
   printf "%s" "${sandbox_name:-$fallback}"
 }
 
@@ -846,12 +871,21 @@ MIN_NODE_VERSION="22.16.0"
 MIN_NPM_MAJOR=10
 
 # ── Agent branding — adapt user-visible names to the active agent ──
+if [[ -n "${NEMOCLAW_AGENT:-}" ]]; then
+  NEMOCLAW_AGENT="$(canonical_agent_name "$NEMOCLAW_AGENT")"
+  export NEMOCLAW_AGENT
+fi
 case "${NEMOCLAW_AGENT:-openclaw}" in
   hermes)
     _CLI_DISPLAY="NemoHermes"
     _AGENT_PRODUCT="Hermes"
     _CLI_BIN="nemohermes"
     ;;
+  langchain-deepagents-code)
+    _CLI_DISPLAY="NemoDeepAgents"
+    _AGENT_PRODUCT="LangChain Deep Agents Code"
+    _CLI_BIN="nemo-deepagents"
+    ;;
   *)
     _CLI_DISPLAY="NemoClaw"
     _AGENT_PRODUCT="OpenClaw"
@@ -1536,8 +1570,8 @@ is_real_nemoclaw_cli() {
   local expected_name="${2:-$_CLI_BIN}"
   local version_output
   version_output="$("$bin_path" --version 2>/dev/null)" || return 1
-  # Real CLI outputs: "nemoclaw v0.1.0" or "nemohermes v0.1.0"
-  # (or any semver, with optional pre-release/build metadata).
+  # Real CLI outputs: "nemoclaw v0.1.0", "nemohermes v0.1.0", or
+  # "nemo-deepagents v0.1.0" (or any semver, with optional pre-release/build metadata).
   [[ "$version_output" =~ ^${expected_name}[[:space:]]+v[0-9]+\.[0-9]+\.[0-9]+(-[0-9A-Za-z.-]+)?([+][0-9A-Za-z.-]+)?$ ]]
 }
 

scripts/install.sh

@@ -66,6 +66,32 @@ describe("runUpdateAction", () => {
     );
   });
 
+  it("--check renders NemoDeepAgents branding and installer guidance when the Deep Agents alias is active", async () => {
+    const log = vi.fn();
+
+    const result = await runUpdateAction(
+      { check: true },
+      {
+        currentVersion: () => "0.1.0",
+        env: { ...process.env, NEMOCLAW_AGENT: "dcode" },
+        getLatestVersion: () => "0.2.0",
+        isSourceCheckout: () => false,
+        log,
+        spawnSyncImpl: vi.fn(),
+      },
+    );
+
+    expect(result.status).toBe(0);
+    expect(log).toHaveBeenCalledWith(
+      expect.stringContaining("Current NemoDeepAgents version: 0.1.0"),
+    );
+    expect(log).toHaveBeenCalledWith(
+      expect.stringContaining(
+        "curl -fsSL https://www.nvidia.com/nemoclaw.sh | NEMOCLAW_AGENT=langchain-deepagents-code bash",
+      ),
+    );
+  });
+
   it("does not run the installer for developer source checkouts", async () => {
     const error = vi.fn();
     const spawnSyncImpl = vi.fn();
@@ -226,6 +252,46 @@ describe("runUpdateAction", () => {
     expect(options?.env?.NEMOCLAW_INSTALL_TAG).toBeUndefined();
   });
 
+  it("preserves the canonical Deep Agents agent selection while sanitizing installer env", async () => {
+    const spawnSyncImpl = vi.fn(
+      () => ({ status: 0, stdout: "", stderr: "", signal: null }) as never,
+    );
+    const log = vi.fn();
+
+    await runUpdateAction(
+      { yes: true },
+      {
+        currentVersion: () => "0.1.0",
+        env: {
+          ...process.env,
+          BASH_ENV: "/tmp/review-bash-env",
+          NEMOCLAW_AGENT: "langchain-deepagents-code",
+          NEMOCLAW_INSTALL_REF: "refs/heads/not-maintained",
+        },
+        getLatestVersion: () => "0.2.0",
+        isSourceCheckout: () => false,
+        log,
+        spawnSyncImpl,
+      },
+    );
+
+    const calls = spawnSyncImpl.mock.calls as unknown as Array<
+      [string, readonly string[], { env?: NodeJS.ProcessEnv }]
+    >;
+    const options = calls[0]?.[2];
+    expect(options?.env?.NEMOCLAW_AGENT).toBe("langchain-deepagents-code");
+    expect(options?.env?.BASH_ENV).toBeUndefined();
+    expect(options?.env?.NEMOCLAW_INSTALL_REF).toBeUndefined();
+    expect(log).toHaveBeenCalledWith(
+      expect.stringContaining("Running maintained NemoDeepAgents installer"),
+    );
+    expect(log).toHaveBeenCalledWith(
+      expect.stringContaining(
+        "Installer completed. Run `nemo-deepagents upgrade-sandboxes --check`",
+      ),
+    );
+  });
+
   it("preserves the Hermes agent selection while sanitizing installer env", async () => {
     const spawnSyncImpl = vi.fn(
       () => ({ status: 0, stdout: "", stderr: "", signal: null }) as never,