diff --git a/.agents/skills/nemoclaw-user-guide/SKILL.md b/.agents/skills/nemoclaw-user-guide/SKILL.md index 2615963051..7ae9f8763f 100644 --- a/.agents/skills/nemoclaw-user-guide/SKILL.md +++ b/.agents/skills/nemoclaw-user-guide/SKILL.md @@ -16,7 +16,7 @@ Do not answer from stale copied docs or generated skill references when the live 3. If MCP is not available, fetch the AI documentation index first: `https://docs.nvidia.com/nemoclaw/llms.txt`. 4. Fetch the specific `.md` page listed in the index or returned by docs search for the user's task. 5. If you only find an HTML documentation URL, replace the `.html` suffix with `.md`, or append `.md` to the route when the URL has no suffix. -6. Prefer the user's selected agent variant, either OpenClaw or Hermes, and do not mix variant-specific instructions unless you explain why. +6. Prefer the user's selected agent variant, OpenClaw, Hermes, or Deep Agents, and do not mix variant-specific instructions unless you explain why. ## Configure the MCP Server @@ -39,10 +39,13 @@ Use these pages first for common onboarding flows: - Hermes home: `https://docs.nvidia.com/nemoclaw/latest/user-guide/hermes/home.md`. - Hermes prerequisites: `https://docs.nvidia.com/nemoclaw/latest/user-guide/hermes/get-started/prerequisites.md`. - Hermes quickstart: `https://docs.nvidia.com/nemoclaw/latest/user-guide/hermes/get-started/quickstart.md`. +- Deep Agents home: `https://docs.nvidia.com/nemoclaw/latest/user-guide/deepagents/home.md`. +- Deep Agents prerequisites: `https://docs.nvidia.com/nemoclaw/latest/user-guide/deepagents/get-started/prerequisites.md`. +- Deep Agents quickstart: `https://docs.nvidia.com/nemoclaw/latest/user-guide/deepagents/get-started/quickstart.md`. ## How to Help the User -- Ask which agent variant they want to use before giving setup instructions: OpenClaw or Hermes. +- Ask which agent variant they want to use before giving setup instructions: OpenClaw, Hermes, or Deep Agents. - Ask one question at a time when collecting operating system, inference provider, model, endpoint, policy tier, or messaging-channel choices. - Run commands for non-technical users when your environment allows it, after explaining what the command does and getting permission. - Summarize important command output instead of asking the user to paste terminal output into chat. diff --git a/README.md b/README.md index bea4ee2919..11cee57eb5 100644 --- a/README.md +++ b/README.md @@ -39,7 +39,7 @@ For Hermes, set `NEMOCLAW_AGENT=hermes` before running the installer, or use the |-------|-------| | OpenClaw (default) | [Quickstart with OpenClaw](https://docs.nvidia.com/nemoclaw/latest/get-started/quickstart.html) | | Hermes | [Quickstart with Hermes](https://docs.nvidia.com/nemoclaw/latest/get-started/quickstart-hermes.html) | -| LangChain Deep Agents Code | [Quickstart with LangChain Deep Agents Code](https://docs.nvidia.com/nemoclaw/latest/get-started/quickstart-langchain-deepagents-code.html) | +| LangChain Deep Agents Code | [Quickstart with LangChain Deep Agents Code](https://docs.nvidia.com/nemoclaw/latest/user-guide/deepagents/get-started/quickstart.html) | ## Documentation diff --git a/ci/platform-matrix.json b/ci/platform-matrix.json index 23d892d495..02b8dce498 100644 --- a/ci/platform-matrix.json +++ b/ci/platform-matrix.json @@ -150,19 +150,19 @@ "name": "OpenClaw", "status": "tested", "default": true, - "notes": "Default agent runtime. Onboard with `$$nemoclaw onboard` (no `--agent` flag required)." + "notes": "Default agent runtime. Onboard with `nemoclaw onboard` (no `--agent` flag required)." }, { "name": "Hermes", - "status": "caveated", + "status": "tested", "default": false, - "notes": "First-class agent with dedicated CLI (`$$nemohermes`), Dockerfile, manifest, docs, and Hermes E2E coverage in `.github/workflows/e2e.yaml` (`hermes-e2e`, `hermes-*`, and Hermes rebuild/switch jobs). 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." + "notes": "First-class agent with dedicated CLI (`nemohermes`), Dockerfile, manifest, docs, and Hermes E2E coverage in `.github/workflows/e2e.yaml` (`hermes-e2e`, `hermes-*`, and Hermes rebuild/switch jobs). Onboard with `nemohermes onboard` or `nemoclaw onboard --agent hermes`. 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." }, { "name": "LangChain Deep Agents Code", - "status": "experimental", + "status": "tested", "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 `$$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." + "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](/user-guide/deepagents/get-started/quickstart). 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." } ], diff --git a/docs/AGENTS.md b/docs/AGENTS.md index a3112bf0de..80f59bea67 100644 --- a/docs/AGENTS.md +++ b/docs/AGENTS.md @@ -8,7 +8,7 @@ Treat `docs/` as the source of truth for published content and AI-agent Markdown ## Role -- Write clear, accurate, task-oriented documentation for developers who run NemoClaw with OpenClaw, Hermes, and OpenShell sandboxes. +- Write clear, accurate, task-oriented documentation for developers who run NemoClaw with OpenClaw, Hermes, LangChain Deep Agents Code, and OpenShell sandboxes. - Preserve the reader's workflow: explain what to do, when to do it, and how to verify it. - Prefer small, focused edits that match the structure of the current page. - Verify behavior against source code, tests, scripts, or existing docs before documenting it. @@ -33,7 +33,7 @@ Treat `docs/` as the source of truth for published content and AI-agent Markdown ## NemoClaw Doc Patterns -- Use `$$nemoclaw` for host CLI command examples on shared OpenClaw and Hermes pages. +- Use `$$nemoclaw` for host CLI command examples on shared OpenClaw, Hermes, and Deep Agents pages. - Use literal command names on pages that have only one agent variant. - Use `` blocks only when content differs by behavior, setup flow, state layout, or agent-specific wording. - Use route-style links without `.mdx` extensions for links between docs pages. diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index 2b60c404af..67827b2290 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -80,13 +80,27 @@ The watcher rejects blank or malformed overrides before it starts Fern. Fern `.mdx` pages are the canonical docs source. Fern publishes Markdown routes for AI agents from the same source pages. +## Publishing Docs + +GitHub Actions publishes Fern docs from the same source files that `npm run docs` validates locally. + +Docs PRs get Fern previews when they change `docs/`, `fern/`, or docs build inputs. +The preview workflow publishes to the staging Fern instance with a `pr-` preview ID and posts the preview URL on the PR when `FERN_TOKEN` is available. + +After a docs PR merges, pushes to `main` publish the affected docs to the staging Fern instance. +The staging publish job regenerates agent variants, validates Fern docs, publishes staging, and deletes the merged PR preview when it can map the merge commit back to a PR. + +Public docs publish automatically when a `v*.*.*` release tag is pushed. +The public publish job runs in the `docs-public` environment, verifies that the tag commit is reachable from `origin/main`, regenerates agent variants, validates Fern docs, and publishes to the public Fern instance. +If the tag does not point to a commit on `main`, the job stops before installing dependencies or running Fern. + ## Agent Variant Generation -Some Fern pages appear in both the OpenClaw and Hermes guide variants. -The `scripts/sync-agent-variant-docs.ts` script reads `docs/index.yml` and renders variant-specific copies for every page that appears in both guide variants before Fern validates or publishes the site. +Some Fern pages appear in the OpenClaw, Hermes, and Deep Agents guide variants. +The `scripts/sync-agent-variant-docs.ts` script reads `docs/index.yml` and renders variant-specific copies for every page that appears in multiple guide variants before Fern validates or publishes the site. The source pages stay in their normal `docs/` locations, and generated pages are written under `docs/_build/agent-variants/`, which is ignored by Git. Navigation in `docs/index.yml` points Fern at generated pages for shared entries so Fern still renders normal fenced code blocks with copy buttons and syntax highlighting. -OpenClaw-only or Hermes-only pages stay as source pages in navigation. +OpenClaw-only, Hermes-only, or Deep Agents-only pages stay as source pages in navigation. When shared page content is the same except for the host CLI binary, write one source page and use `$$nemoclaw` as a build-time placeholder. Do not duplicate fenced code blocks or inline command examples only to switch between `nemoclaw` and `nemohermes`. @@ -203,7 +217,7 @@ Remove them during review. ``` - Use `$$nemoclaw` as a build-time placeholder for NemoClaw host CLI command examples in shared variant pages. - The docs build resolves it to `nemoclaw` for OpenClaw pages and `nemohermes` for Hermes pages before Fern renders code blocks. + The docs build resolves it to `nemoclaw` for OpenClaw pages, `nemohermes` for Hermes pages, and `nemo-deepagents` for Deep Agents pages before Fern renders code blocks. This preserves Fern's native fenced-code UI while keeping one source sample. - Do not write duplicate `` fenced code blocks when the only difference is `nemoclaw` versus `nemohermes`. Use `` blocks only when the surrounding content differs between the OpenClaw and Hermes variants. diff --git a/docs/_components/AgentGuide.tsx b/docs/_components/AgentGuide.tsx index 4043e77fd6..5e84c13092 100644 --- a/docs/_components/AgentGuide.tsx +++ b/docs/_components/AgentGuide.tsx @@ -4,14 +4,14 @@ */ /** - * Resolves OpenClaw vs Hermes user-guide variant from injected route data. + * Resolves OpenClaw, Hermes, or Deep Agents user-guide variant from injected route data. * Prefer passing `variant` or `pathname` from the page or route that renders the * component so SSR output does not depend on browser-only globals. The window * fallback preserves the current client-side behavior for unwrapped pages. */ declare const React: unknown; -export type GuideVariant = "openclaw" | "hermes"; +export type GuideVariant = "openclaw" | "hermes" | "deepagents"; export type GuideVariantSource = | GuideVariant | string @@ -30,6 +30,7 @@ type GuideContextProps = { }; const GUIDE_PATH = "/user-guide/"; +const DEEPAGENTS_PATH = `${GUIDE_PATH}deepagents`; const HERMES_PATH = `${GUIDE_PATH}hermes`; const OPENCLAW_PATH = `${GUIDE_PATH}openclaw`; @@ -51,11 +52,17 @@ export function guidePath(suffix: string, source?: GuideVariantSource): string { } export function AgentCli(props: GuideContextProps = {}) { - return {getGuideVariant(props) === "hermes" ? "nemohermes" : "nemoclaw"}; + const variant = getGuideVariant(props); + if (variant === "hermes") return nemohermes; + if (variant === "deepagents") return nemo-deepagents; + return nemoclaw; } export function AgentProductName(props: GuideContextProps = {}) { - return <>{getGuideVariant(props) === "hermes" ? "NemoHermes" : "NemoClaw"}; + const variant = getGuideVariant(props); + if (variant === "hermes") return <>NemoHermes; + if (variant === "deepagents") return <>NemoDeepAgents; + return <>NemoClaw; } export function AgentOnly({ @@ -64,12 +71,14 @@ export function AgentOnly({ pathname, children, }: { - variant: GuideVariant; + variant: GuideVariant | string; activeVariant?: GuideVariant | null; pathname?: string | null; children: unknown; }) { - if (getGuideVariant({ activeVariant, pathname }) !== variant) { + const active = getGuideVariant({ activeVariant, pathname }); + const variants = variant.split(",").map((item) => item.trim()); + if (!variants.includes(active)) { return null; } return <>{children}; @@ -97,7 +106,7 @@ export function GuideLink({ function resolveGuideVariant(source?: GuideVariantSource): GuideVariant | null { if (!source) return null; - if (source === "openclaw" || source === "hermes") return source; + if (source === "openclaw" || source === "hermes" || source === "deepagents") return source; if (typeof source === "string") return resolveGuideVariantFromPathname(source); return ( source.activeVariant ?? @@ -107,13 +116,16 @@ function resolveGuideVariant(source?: GuideVariantSource): GuideVariant | null { } function resolveGuidePathname(source?: GuideVariantSource): string | null { - if (!source || source === "openclaw" || source === "hermes") return null; + if (!source || source === "openclaw" || source === "hermes" || source === "deepagents") { + return null; + } if (typeof source === "string") return source; return source.pathname ?? null; } function resolveGuideVariantFromPathname(pathname: string | null): GuideVariant | null { if (!pathname) return null; + if (pathname.includes(DEEPAGENTS_PATH)) return "deepagents"; if (pathname.includes(HERMES_PATH)) return "hermes"; if (pathname.includes(OPENCLAW_PATH)) return "openclaw"; return null; diff --git a/docs/_components/StarterPrompt.tsx b/docs/_components/StarterPrompt.tsx index 83e6cba358..2285ee4d26 100644 --- a/docs/_components/StarterPrompt.tsx +++ b/docs/_components/StarterPrompt.tsx @@ -54,10 +54,11 @@ Before giving install instructions, ask me which supported agent I want to use: - OpenClaw, the default NemoClaw agent. - Hermes. +- LangChain Deep Agents Code. Ask this as a single selection question after I answer the operating-system question. -After I choose, use the matching documentation variant. Do not mix OpenClaw-specific and Hermes-specific instructions unless you explain why. +After I choose, use the matching documentation variant. Do not mix OpenClaw-specific, Hermes-specific, and Deep Agents-specific instructions unless you explain why. Use these Markdown documentation pages as the first sources: @@ -68,6 +69,9 @@ Use these Markdown documentation pages as the first sources: - Hermes home: https://docs.nvidia.com/nemoclaw/latest/user-guide/hermes/home.md - Hermes prerequisites: https://docs.nvidia.com/nemoclaw/latest/user-guide/hermes/get-started/prerequisites.md - Hermes quickstart: https://docs.nvidia.com/nemoclaw/latest/user-guide/hermes/get-started/quickstart.md +- Deep Agents home: https://docs.nvidia.com/nemoclaw/latest/user-guide/deepagents/home.md +- Deep Agents prerequisites: https://docs.nvidia.com/nemoclaw/latest/user-guide/deepagents/get-started/prerequisites.md +- Deep Agents quickstart: https://docs.nvidia.com/nemoclaw/latest/user-guide/deepagents/get-started/quickstart.md ## Avoid Getting Stuck on Interactive NemoClaw Prompts @@ -75,11 +79,13 @@ Do not start the interactive installer first and then try to answer terminal men Instead, collect the required choices from me first, one clickable selection at a time, then run NemoClaw in non-interactive mode whenever possible. -- After I choose OpenClaw or Hermes, ask me which inference provider I want as one selection question. -- If I choose a provider that requires a model, endpoint URL, credential, model download, sandbox name, web search, messaging channel, or policy tier choice, ask those follow-up questions one at a time before running the installer. +- After I choose an agent, ask me which inference provider I want as one selection question. +- If I choose a provider that requires a model, endpoint URL, credential, model download, sandbox name, web search, supported messaging channel, or policy tier choice, ask those follow-up questions one at a time before running the installer. - For Local Ollama, ask for the model before running the installer. Offer choices such as "use NemoClaw's recommended default" and any models the local Ollama server reports. If I approve downloading a model, set \`NEMOCLAW_YES=1\`. - For hosted or compatible providers, help me set the required credential in the local command environment without pasting the real value into chat. - Never echo a command that contains a real secret. Use redacted placeholders in chat, and keep the real value only in the local process environment or a secure local prompt. +- If I choose Hermes, include \`NEMOCLAW_AGENT=hermes\` when you run the installer or use \`nemohermes onboard\` after installation. +- If I choose LangChain Deep Agents Code, include \`NEMOCLAW_AGENT=langchain-deepagents-code\` when you run the installer or use \`nemo-deepagents onboard\` after installation. ## Handle Tokens Securely and Visually @@ -108,6 +114,7 @@ Use this provider mapping for non-interactive setup: | Model Router | \`routed\` | \`NVIDIA_INFERENCE_API_KEY\` | When you have the approved values, run the installer with the environment variables on the \`bash\` side of the pipe, not before \`curl\`. +Do not offer the Hermes Provider option for OpenClaw or Deep Agents. For example, for an approved Local Ollama setup: @@ -125,8 +132,9 @@ If non-interactive mode cannot cover a later prompt, stop before running the int ## Configure Messaging Channels after Non-Interactive Onboarding -Non-interactive onboarding can skip the interactive messaging-channel picker. After the sandbox is created, ask whether I want to set up messaging as a separate one-question selection. +Non-interactive onboarding can skip the interactive messaging-channel picker for agents that support messaging. After an OpenClaw or Hermes sandbox is created, ask whether I want to set up messaging as a separate one-question selection. +- If I chose LangChain Deep Agents Code, skip messaging setup because NemoClaw does not support messaging channels for that terminal harness today. - First ask: "Do you want to set up a messaging channel now?" with choices: No, Telegram, Discord, Slack, WhatsApp, WeChat (experimental). - Configure one channel at a time. If I want another channel, ask again after the current channel finishes. - Run channel commands from the host with \`nemoclaw channels add \`, not from inside the sandbox. diff --git a/docs/about/ecosystem-deepagents.mdx b/docs/about/ecosystem-deepagents.mdx new file mode 100644 index 0000000000..2c74d95a86 --- /dev/null +++ b/docs/about/ecosystem-deepagents.mdx @@ -0,0 +1,103 @@ +--- +# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# SPDX-License-Identifier: Apache-2.0 +title: "Ecosystem" +sidebar-title: "Ecosystem" +description: "How LangChain Deep Agents Code, OpenShell, and NemoClaw form one managed terminal-agent stack." +description-agent: "Explains how LangChain Deep Agents Code, OpenShell, and NemoClaw fit together, what NemoClaw adds for the managed dcode path, and when to use NemoClaw versus custom OpenShell integration. Use when users ask how Deep Agents relates to NemoClaw and OpenShell." +keywords: ["nemoclaw deep agents ecosystem", "dcode openshell sandbox", "nemo-deepagents", "langchain deep agents code"] +content: + type: "concept" +--- +NemoClaw provides onboarding, lifecycle management, policy, and inference routing for LangChain Deep Agents Code in OpenShell containers. +Use the `nemo-deepagents` CLI alias when you work from the Deep Agents guide; it is equivalent to `nemoclaw` with `langchain-deepagents-code` pre-selected. + +This page explains how Deep Agents, OpenShell, and NemoClaw fit together, and when to choose NemoClaw or a custom OpenShell integration. + +## How the Stack Fits Together + +A NemoClaw deployment for Deep Agents combines three pieces with distinct scopes: LangChain Deep Agents Code, OpenShell, and NemoClaw. +The following diagram shows how they fit together. + +```mermaid +flowchart TB + NC["NVIDIA NemoClaw
CLI, blueprint, managed runtime"] + OS["NVIDIA OpenShell
Gateway, policy, inference routing"] + DA["LangChain Deep Agents Code
dcode terminal agent in sandbox"] + + NC -->|orchestrates| OS + OS -->|isolates and runs| DA + + classDef nv fill:#76b900,stroke:#333,color:#fff + classDef nvDark fill:#333,stroke:#76b900,color:#fff + + class NC nv + class OS nv + class DA nvDark + + linkStyle 0 stroke:#76b900,stroke-width:2px + linkStyle 1 stroke:#76b900,stroke-width:2px +``` + +NemoClaw sits above OpenShell in the operator workflow. +It calls OpenShell APIs and CLI commands to create and configure the sandbox that runs `dcode`. +Models and endpoints sit behind OpenShell's inference routing. +NemoClaw onboarding connects your provider choice to that route and writes the managed Deep Agents configuration under `/sandbox/.deepagents`. + +The following table shows the scope of each component in the stack. + +| Project | Scope | +|---------|--------| +| LangChain Deep Agents Code | The terminal coding agent runtime, interactive TUI, headless `dcode -n` mode, skills, memory, and tool approval UI inside the container. | +| OpenShell | The execution environment: sandbox lifecycle, network, filesystem, process policy, inference routing, and the operator-facing `openshell` CLI for those primitives. | +| NemoClaw | The NVIDIA reference stack on the host: `nemo-deepagents` / `nemoclaw` CLI, versioned blueprint, managed Deep Agents runtime patches, credential-safe inference routing, policy presets, and state migration helpers. | + +## NemoClaw Path versus OpenShell Path + +Both paths assume OpenShell can sandbox a workload. +The difference is who owns the integration work. + +| Path | What it means | +|------|---------------| +| **NemoClaw path** | You adopt the reference stack. NemoClaw's Deep Agents blueprint encodes the image, managed `dcode` launchers, default policies, inference configuration, and state handling so `nemo-deepagents onboard` creates a tested Deep Agents-on-OpenShell setup with less custom integration work. | +| **OpenShell path** | You use OpenShell as the platform and supply your own container, Deep Agents install steps, policy YAML, provider setup, and runtime wrappers. OpenShell stays the sandbox and policy engine; nothing requires NemoClaw's blueprint or CLI. | + +## What NemoClaw Adds Beyond Custom OpenShell + +You can run Deep Agents inside OpenShell without NemoClaw by building your own image, writing policy YAML, registering providers, and wiring inference routes yourself. +That path is valid when you need full control over the container layout. + +NemoClaw builds on OpenShell with additional security hardening, automation, and lifecycle tooling for Deep Agents. +The following table compares custom OpenShell integration with `nemo-deepagents onboard`. + +| Capability | Custom OpenShell + Deep Agents | `nemo-deepagents onboard` | +|---|---|---| +| Sandbox isolation | You define and apply OpenShell seccomp, Landlock, network namespace isolation, and no-new-privileges policy. | NemoClaw applies the managed Deep Agents policy through the blueprint and requires the runtime checks that the managed harness depends on. | +| Credential handling | You create OpenShell providers manually and decide how `dcode` receives endpoint credentials. | NemoClaw creates OpenShell providers during onboarding, points Deep Agents at `https://inference.local/v1`, and keeps provider credentials on the host. | +| Image hardening | Depends on your base image and install steps. | NemoClaw installs the pinned Deep Agents Code package in `/opt/venv`, uses managed launchers, and disables unsupported runtime escape paths such as unmanaged MCP autoloading, tracing exports, nested sandbox providers, and alternate model routes. | +| Filesystem policy | You define read-only and read-write paths in policy YAML. | NemoClaw defines a targeted layout: system paths are read-only, `/sandbox` and `/tmp` are writable, and Deep Agents state lives under `/sandbox/.deepagents`. | +| Inference setup | You configure OpenShell inference routing and Deep Agents provider settings manually. | NemoClaw validates the selected provider from the host, configures the OpenShell route, and writes `/sandbox/.deepagents/config.toml` for the managed OpenAI-compatible path. | +| Optional integrations | You decide how web search, MCP, tracing, and other integrations enter the sandbox. | NemoClaw supports a maintained MCP projection and opt-in Tavily policy path, while keeping LangSmith and OpenTelemetry tracing disabled for the managed harness. | +| Blueprint versioning | No NemoClaw blueprint; your image tag is whatever you built locally. | NemoClaw downloads the blueprint artifact, checks version compatibility, and verifies its digest before applying. | +| State migration | Not included unless you build it. | NemoClaw preserves manifest-declared Deep Agents state and omits credential-bearing user files from snapshots and rebuilds. | + +## When to Use Which + +Use the following table to choose NemoClaw or custom OpenShell integration. + +| Situation | Prefer | +|-----------|--------| +| You want Deep Agents with NVIDIA defaults, managed inference routing, and the documented install and onboard flow. | NemoClaw (`nemo-deepagents`) | +| You need maximum flexibility for custom images, a layout that does not match the NemoClaw Deep Agents blueprint, or an unsupported Deep Agents extension path. | OpenShell with your own integration | +| You are standardizing on a managed terminal coding agent with sandbox policy and host-owned credentials. | NemoClaw (`nemo-deepagents`) | +| You are building internal platform abstractions where the NemoClaw CLI or blueprint is not the right fit. | OpenShell and your orchestration | + +## Related Topics + +- [Overview](overview) defines NemoClaw's capabilities, benefits, and use cases. +- [Architecture Overview](how-it-works) describes how NemoClaw runs, the blueprint, sandbox creation, routing, and protection layers for Deep Agents. +- [Architecture Details](../reference/architecture) describes the Deep Agents blueprint, file layout, policy paths, and managed runtime internals. +- [Quickstart with Deep Agents](../get-started/quickstart) installs NemoClaw and launches your first Deep Agents sandbox. +- [Inference Options](../inference/inference-options) explains provider choices and the `inference.local` route. +- [Deep Agents Code overview](https://docs.langchain.com/oss/python/deepagents/code/overview) explains upstream `dcode` capabilities and commands. +- [NemoClaw Community](https://github.com/NVIDIA/nemoclaw-community) collects community-driven blueprint examples, showcases, and integrations that demonstrate complete blueprint patterns. diff --git a/docs/about/how-it-works.mdx b/docs/about/how-it-works.mdx index 1adb837cf5..4ea62be77e 100644 --- a/docs/about/how-it-works.mdx +++ b/docs/about/how-it-works.mdx @@ -21,6 +21,9 @@ OpenClaw sandboxes also load the NemoClaw plugin for managed inference metadata Hermes sandboxes receive agent configuration under `/sandbox/.hermes` during onboarding instead of the OpenClaw plugin path. + +Deep Agents sandboxes receive managed `dcode` configuration under `/sandbox/.deepagents` during onboarding instead of the OpenClaw plugin path. + You can use that setup directly or adapt it for your own OpenShell integration. ## High-Level Flow @@ -29,7 +32,59 @@ NemoClaw keeps the user workflow on the host while OpenShell enforces the sandbo The gateway sits between NemoClaw control, the sandbox, inference providers, and external integrations. That placement lets NemoClaw configure the environment without giving the agent direct access to host credentials or uncontrolled network egress. -![NemoClaw High-Level Component Diagram](images/nemoclaw-highlevel-component-diagram.png) +```mermaid +flowchart TB + subgraph TOP_ROW[" "] + direction LR + TOP_USERS["Users + Operators
Developer, admin
end-user channels"]:::hidden + TOP_CONTROL["NemoClaw Control
CLI, installer, dashboard
onboard + configure"]:::hidden + INFERENCE["Inference
NVIDIA Endpoints, NIM
or compatible APIs"]:::inference + TOP_SANDBOX["NemoClaw Sandbox
Selected agent runtime
integration, blueprints, tools"]:::hidden + TOP_STATE["State + Artifacts
Config, credentials, logs
workspace, policy, transcripts"]:::hidden + + TOP_USERS ~~~ TOP_CONTROL ~~~ INFERENCE ~~~ TOP_SANDBOX ~~~ TOP_STATE + end + + subgraph MAIN_ROW[" "] + direction LR + USERS["Users + Operators
Developer, admin
end-user channels"]:::users + CONTROL["NemoClaw Control
CLI, installer, dashboard
onboard + configure"]:::control + GATEWAY["OpenShell Gateway
Sandbox lifecycle
networking + policy"]:::gateway + SANDBOX["NemoClaw Sandbox
Selected agent runtime
integration, blueprints, tools"]:::sandbox + STATE["State + Artifacts
Config, credentials, logs
workspace, policy, transcripts"]:::state + + USERS --> CONTROL + CONTROL --> GATEWAY + GATEWAY -->|"egress via gateway"| SANDBOX + SANDBOX -.-> STATE + end + + subgraph BOTTOM_ROW[" "] + direction LR + BOTTOM_USERS["Users + Operators
Developer, admin
end-user channels"]:::hidden + BOTTOM_CONTROL["NemoClaw Control
CLI, installer, dashboard
onboard + configure"]:::hidden + INTEGRATIONS["Integrations
Messaging, MCP
GitHub, npm, PyPI, HF"]:::integrations + BOTTOM_SANDBOX["NemoClaw Sandbox
Selected agent runtime
integration, blueprints, tools"]:::hidden + BOTTOM_STATE["State + Artifacts
Config, credentials, logs
workspace, policy, transcripts"]:::hidden + + BOTTOM_USERS ~~~ BOTTOM_CONTROL ~~~ INTEGRATIONS ~~~ BOTTOM_SANDBOX ~~~ BOTTOM_STATE + end + + GATEWAY -->|"inference via gateway"| INFERENCE + GATEWAY -->|"integrations via gateway"| INTEGRATIONS + + style TOP_ROW fill:transparent,stroke:transparent + style MAIN_ROW fill:transparent,stroke:transparent + style BOTTOM_ROW fill:transparent,stroke:transparent + classDef hidden fill:transparent,stroke:transparent,color:transparent,stroke-width:0px + classDef users fill:#d9ecf7,stroke:#6aa6c8,color:#1a1a1a,stroke-width:2px + classDef control fill:#d7f0dc,stroke:#5a9f70,color:#1a1a1a,stroke-width:2px + classDef gateway fill:#fff1be,stroke:#c4992f,color:#1a1a1a,stroke-width:2px + classDef sandbox fill:#e7ddff,stroke:#8c6ccf,color:#1a1a1a,stroke-width:2px + classDef state fill:#f7dfe4,stroke:#c86d7d,color:#1a1a1a,stroke-width:2px + classDef inference fill:#d5f1f1,stroke:#4fa7a7,color:#1a1a1a,stroke-width:2px + classDef integrations fill:#fce6d7,stroke:#c77e55,color:#1a1a1a,stroke-width:2px +``` The diagram has the following components: @@ -81,6 +136,11 @@ NemoClaw separates host orchestration from sandbox image contents. - NemoClaw writes Hermes runtime configuration into `/sandbox/.hermes` during onboarding, including `config.yaml`, environment files, and platform adapter settings for supported messaging channels. + + + +- NemoClaw writes Deep Agents runtime configuration into `/sandbox/.deepagents` during onboarding, including `config.toml`, managed MCP projection state, and the inference route used by `dcode`. + - The _blueprint_ is a versioned YAML package with the sandbox image, policy, inference profile, and supporting assets. The runner resolves and verifies the blueprint before applying it through OpenShell. @@ -108,6 +168,9 @@ When you select the Model Router provider, `inference.local` routes to a host-si For Hermes, `inference set` updates `/sandbox/.hermes/config.yaml` at runtime without rebuilding the sandbox. + +For Deep Agents, the managed `dcode` runtime reads the OpenAI-compatible route that NemoClaw writes into `/sandbox/.deepagents/config.toml`. + ## Protection Layers @@ -145,3 +208,12 @@ NemoClaw's runtime context tells supported agents to try allowed network and fil - For details on the baseline rules, refer to [Network Policies](../reference/network-policies). + + +- Read [Ecosystem](ecosystem) for stack-level relationships and NemoClaw versus OpenShell-only paths. +- Follow [Quickstart with Deep Agents](../get-started/quickstart) to launch your first sandbox. +- Read [Architecture](../reference/architecture) for the full technical structure, including file layouts and the blueprint lifecycle. +- Read [Inference Options](../inference/inference-options) for detailed provider configuration. +- For details on the baseline rules, refer to [Network Policies](../reference/network-policies). + + diff --git a/docs/about/overview.mdx b/docs/about/overview.mdx index 6bc9e73907..097dbb292e 100644 --- a/docs/about/overview.mdx +++ b/docs/about/overview.mdx @@ -5,7 +5,7 @@ title: "Overview of NVIDIA NemoClaw" sidebar-title: "Overview" description: "NemoClaw is an open-source reference stack for running sandboxed AI agents more safely inside OpenShell." description-agent: "Explains what NemoClaw covers: onboarding, lifecycle management, and agent operations within OpenShell containers, plus capabilities and why it exists. Use when users ask what NemoClaw is or what the project provides. For ecosystem placement or OpenShell-only paths, use the Ecosystem page; for internal mechanics, use How It Works." -keywords: ["nemoclaw overview", "openclaw always-on assistants", "hermes agent", "nvidia openshell", "nvidia nemotron"] +keywords: ["nemoclaw overview", "openclaw always-on assistants", "hermes agent", "langchain deep agents code", "dcode sandbox", "nvidia openshell", "nvidia nemotron"] content: type: "concept" skill: @@ -39,7 +39,7 @@ NemoClaw provides these product capabilities. | AI-agent docs | Publishes Markdown docs and a small routing skill so AI coding assistants can guide setup, inference configuration, policy management, monitoring, deployment, security review, and troubleshooting. | | Hardened blueprint | A Dockerfile with capability drops, least-privilege network rules, and declarative policy. | | State management | Safe migration of agent state across machines with credential stripping and integrity verification. | -| Messaging channels | OpenShell-managed processes connect Telegram, Discord, Slack, and similar platforms to the sandboxed agent. NemoClaw configures channels during onboarding; OpenShell supplies the native constructs, credential flow, and runtime supervision. | +| Messaging channels | OpenShell-managed processes connect Telegram, Discord, Slack, and similar platforms to supported messaging agents. NemoClaw configures channels during onboarding where the selected agent supports them; OpenShell supplies the native constructs, credential flow, and runtime supervision. | | Routed inference | Provider-routed model calls through the OpenShell gateway, transparent to the agent. Supports NVIDIA Endpoints, OpenAI, Anthropic, Google Gemini, compatible endpoints, local Ollama, local vLLM, and the Model Router. | | Layered protection | Network, filesystem, process, and inference controls that can be hot-reloaded or locked at creation. | @@ -65,6 +65,7 @@ Use NemoClaw for these use cases. | Use Case | Description | |---------------------------|----------------------------------------------------------------------------------------------| | Always-on assistant | Run a sandboxed agent with controlled network access and operator-approved egress. | +| Terminal coding harness | Run `dcode` inside an OpenShell sandbox with host-owned inference credentials and a managed terminal workflow. | | Sandboxed testing | Test agent behavior in a locked-down environment before granting broader permissions. | | Remote GPU deployment | Deploy a sandboxed agent to a remote GPU instance for persistent operation. | @@ -92,3 +93,13 @@ Use these topics to learn more about NemoClaw and how to install and use it. - Read [Inference Options](../inference/inference-options) to check the inference providers that NemoClaw supports and how inference routing works. + + +- Read [Architecture Overview](how-it-works) to understand how NemoClaw works. +- Read [Ecosystem](ecosystem) to understand how Deep Agents, OpenShell, and NemoClaw relate in the wider stack, and when to use NemoClaw versus OpenShell. +- Follow [Quickstart with Deep Agents](../get-started/quickstart) to install NemoClaw and run your first Deep Agents sandbox with `$$nemoclaw`. +- Read [AI Agent Docs](../resources/agent-skills) to let your AI coding assistant fetch NemoClaw Markdown docs. +- Explore [NemoClaw Community](https://github.com/NVIDIA/nemoclaw-community) for community-driven blueprint examples, showcases, and integrations. +- Read [Inference Options](../inference/inference-options) to check the inference providers that NemoClaw supports and how inference routing works. + + diff --git a/docs/about/release-notes.mdx b/docs/about/release-notes.mdx index b250ad9a80..f94179b145 100644 --- a/docs/about/release-notes.mdx +++ b/docs/about/release-notes.mdx @@ -43,11 +43,11 @@ NemoClaw v0.0.74 upgrades the OpenShell policy boundary, adds managed MCP and pr For more information, refer to [OpenShell 0.0.72 Compatibility Review](../security/openshell-0.0.72-compatibility-review) and [Customize the Network Policy](../network-policy/customize-network-policy). - Managed MCP commands use `add`, `list`, `status`, `restart`, and `remove` to manage authenticated HTTPS Streamable HTTP servers for OpenClaw, Hermes, and experimental LangChain Deep Agents Code through native OpenShell policy enforcement and provider-backed credential replacement. The LangChain Deep Agents Code rebuild path validates the recorded gateway, route, image, staged build context, and prepared replacement inputs before deleting the previous sandbox, then restores managed MCP state after the recreated runtime is ready. - For more information, refer to [Set Up MCP Servers](../manage-sandboxes/set-up-mcp-servers), [Quickstart with LangChain Deep Agents Code](../../openclaw/get-started/quickstart-langchain-deepagents-code), and the [accepted architecture decision](https://github.com/NVIDIA/NemoClaw/issues/566#issuecomment-4847534784). + For more information, refer to [Set Up MCP Servers](../manage-sandboxes/set-up-mcp-servers), [Quickstart with LangChain Deep Agents Code](/user-guide/deepagents/get-started/quickstart), and the [accepted architecture decision](https://github.com/NVIDIA/NemoClaw/issues/566#issuecomment-4847534784). - New sandboxes default to progressive tool disclosure across OpenClaw, Hermes, and LangChain Deep Agents Code, while `--tool-disclosure direct` restores the full visible catalog. The selected mode persists through resume and transactional rebuilds, and model-specific compatibility safeguards can keep an incompatible model on direct disclosure. Sandbox-first `inference get` and `inference set` commands now provide the same route controls as their global forms. - For more information, refer to [Tool Calling Reliability](../inference/tool-calling-reliability), [Model Capability Audit](../inference/model-capability-audit), and [NemoClaw CLI Commands Reference](../reference/commands). + For more information, refer to [Tool Calling Reliability](/user-guide/openclaw/inference/tool-calling-reliability), [Model Capability Audit](../inference/model-capability-audit), and [NemoClaw CLI Commands Reference](../reference/commands). - Shared OpenShell gateways now enforce a single compatible inference route across every registered sandbox, including stopped sandboxes. Onboarding, connect-time repair, and `inference set` reject provider/model conflicts; custom routes must also match the normalized endpoint and API family. As a migration requirement, custom switches must provide `--endpoint-url` and an unambiguous API family, and incomplete legacy custom-route metadata fails closed until the sandbox is removed and re-onboarded with complete metadata. @@ -67,11 +67,11 @@ NemoClaw v0.0.74 upgrades the OpenShell policy boundary, adds managed MCP and pr For more information, refer to [Switch Inference Providers](../inference/switch-inference-providers), [NemoClaw CLI Commands Reference](../reference/commands), and [Troubleshooting](../reference/troubleshooting). - LangChain Deep Agents Code now provides managed `status`, `whoami`, and `identity` commands without launching the interactive UI, validates the installed agent version during onboarding, and keeps credential-shaped or tracing configuration out of persisted runtime metadata. Its rebuild path validates recreation before destructive handoff and preserves the managed proxy, tool-disclosure, and MCP boundaries. - For more information, refer to [Quickstart with LangChain Deep Agents Code](../../openclaw/get-started/quickstart-langchain-deepagents-code), [NemoClaw CLI Commands Reference](../reference/commands), and [Security Best Practices](../security/best-practices). + For more information, refer to [Quickstart with LangChain Deep Agents Code](/user-guide/deepagents/get-started/quickstart), [NemoClaw CLI Commands Reference](../reference/commands), and [Security Best Practices](../security/best-practices). - Onboarding uses BuildKit prebuilds with bounded progress heartbeats, reuses validated release and source-commit sandbox images, and rejects stale or incompatible image contracts before sandbox creation. Readiness handling tolerates a bounded run of transient OpenShell `Error` phases, while preflight output distinguishes an unreachable container DNS resolver from one that answers but rejects the query. On Windows on Arm N1X systems, automatic Local Ollama setup treats the integrated GPU as compute-constrained and selects `qwen3.5:9b` instead of the 30B and 35B starter models. - For more information, refer to [NemoClaw CLI Commands Reference](../reference/commands), [Install OpenClaw Plugins](../deployment/install-openclaw-plugins), [Use a Local Inference Server](../inference/use-local-inference), [Prepare Windows for NemoClaw](../get-started/windows-preparation), and [Troubleshooting](../reference/troubleshooting). + For more information, refer to [NemoClaw CLI Commands Reference](../reference/commands), [Install OpenClaw Plugins](/user-guide/openclaw/manage-sandboxes/install-openclaw-plugins), [Use a Local Inference Server](../inference/use-local-inference), [Prepare Windows for NemoClaw](../get-started/prerequisites/windows-preparation), and [Troubleshooting](../reference/troubleshooting). - Messaging configuration now keeps channel policy ownership with the enabled channel, persists selected policy presets through onboarding and rebuilds, reports Telegram mention mode in channel status, and detects credential conflicts before a destructive rebuild starts. For more information, refer to [Messaging Channels](../manage-sandboxes/messaging-channels), [Customize the Network Policy](../network-policy/customize-network-policy), and [NemoClaw CLI Commands Reference](../reference/commands). - Day-two commands provide safer recovery and clearer automation behavior. @@ -102,7 +102,7 @@ NemoClaw v0.0.73 improves custom endpoint safety, Linux GPU onboarding, agent-aw - LangChain Deep Agents Code now reaches `inference.local` through the managed OpenShell proxy across interactive, login-shell, direct-exec, and connect-probe paths. The runtime normalizes proxy environment state, clears inherited bypass settings, and keeps credential-shaped values out of persisted proxy configuration. Rebuild existing LangChain Deep Agents Code sandboxes after upgrading so they receive the corrected image scripts. - For more information, refer to [Quickstart with LangChain Deep Agents Code](../../openclaw/get-started/quickstart-langchain-deepagents-code) and [Troubleshooting](../reference/troubleshooting). + For more information, refer to [Quickstart with LangChain Deep Agents Code](/user-guide/deepagents/get-started/quickstart) and [Troubleshooting](../reference/troubleshooting). - Setup and recovery guidance now covers the Docker CLI requirement for Homebrew Colima, Cursor terminal restrictions on Windows, stale Kubernetes namespace cleanup, OpenShell and OpenClaw gateway startup order, and stopped-container recovery. The new Host Files and State reference explains files under `~/.nemoclaw/` and which registry and backup state uninstall preserves. For more information, refer to [Prerequisites](../get-started/prerequisites), [Prepare Windows for NemoClaw](../get-started/prerequisites/windows-preparation), [Host Files and State](../reference/host-files-and-state), and [Troubleshooting](../reference/troubleshooting). @@ -178,7 +178,7 @@ NemoClaw v0.0.69 improves sandbox recovery, Deep Agents Code workflows, Hermes m For more information, refer to [Manage Sandbox Lifecycle](../manage-sandboxes/lifecycle), [Backup and Restore](../manage-sandboxes/backup-restore), and [Troubleshooting](../reference/troubleshooting). - Deep Agents Code workflows now have clearer terminal and CLI behavior. Session export reports actionable guidance for dash-prefixed arguments, warm-up sessions stay out of normal history, `nemo-deepagents` aliases share a consistent command surface, terminal runtime dispatch and version probes are more accurate, and status reports out-of-memory degradation with useful context. - For more information, refer to [Quickstart with LangChain Deep Agents Code](../../openclaw/get-started/quickstart-langchain-deepagents-code) and [NemoClaw CLI Commands Reference](../reference/commands). + For more information, refer to [Quickstart with LangChain Deep Agents Code](/user-guide/deepagents/get-started/quickstart) and [NemoClaw CLI Commands Reference](../reference/commands). - Deep Agents Code rebuild and snapshot operations now protect more user state. Skills created with `skill-creator` persist across rebuilds, the managed Python environment stays on `PATH`, rebuild warns before dropping user-managed files, and snapshot creation refuses to capture an active Deep Agents Code session. For more information, refer to [Workspace Files](../manage-sandboxes/workspace-files), [Backup and Restore](../manage-sandboxes/backup-restore), and [Security Best Practices](../security/best-practices). @@ -210,7 +210,7 @@ NemoClaw v0.0.68 improves onboarding recovery, messaging setup, agent-specific C `sessions export` routes by sandbox agent kind, Hermes `gateway-token` points users to `dashboard-url`, bare OpenClaw `agent` invocations print wrapper help locally, and omitted extra-agent `workspace` and `agentDir` fields use canonical OpenClaw paths. For more information, refer to [NemoClaw CLI Commands Reference](../reference/commands). - LangChain Deep Agents Code sandboxes now stay alive with a stable entrypoint, use their own product branding, reject unsupported messaging mutations, and preserve the hosted-compatible default model ID without doubling the provider namespace. - For more information, refer to [Quickstart with LangChain Deep Agents Code](../../openclaw/get-started/quickstart-langchain-deepagents-code), [NemoClaw Inference Options](../inference/inference-options), and [Platform Support and Launch Claims](../reference/platform-support). + For more information, refer to [Quickstart with LangChain Deep Agents Code](/user-guide/deepagents/get-started/quickstart), [NemoClaw Inference Options](../inference/inference-options), and [Platform Support and Launch Claims](../reference/platform-support). - DGX Spark express install now selects managed local vLLM by default, while hosted NVIDIA inference setup preserves the provider, namespace, and model ID shape used by the compatible endpoint path. For more information, refer to [NemoClaw Quickstart with OpenClaw](../get-started/quickstart), [NemoClaw Inference Options](../inference/inference-options), and [Platform Support and Launch Claims](../reference/platform-support). - Platform-support docs now rely on the canonical support matrix, so users and agents see one source of truth for supported platforms, inference providers, agents, messaging integrations, deployment paths, capabilities, and out-of-scope items. @@ -239,7 +239,7 @@ NemoClaw v0.0.66 improves gateway serving, OpenClaw agent workflows, messaging d For more information, refer to [Troubleshooting](../reference/troubleshooting), [Manage Sandbox Lifecycle](../manage-sandboxes/lifecycle), [Credential Storage](../security/credential-storage), and [Security Best Practices](../security/best-practices). - OpenClaw sandboxes gained new agent workflows. The release adds the LangChain Deep Agents Code harness, `agents.yaml` declarative multi-agent manifests, live `agents apply` reconciliation, and the non-interactive `$$nemoclaw agent` passthrough command for automation that needs direct OpenClaw agent access. - For more information, refer to [Quickstart with LangChain Deep Agents Code](../../openclaw/get-started/quickstart-langchain-deepagents-code), [Declarative Multi-Agent Manifest](../../openclaw/inference/declarative-agents-manifest), and [NemoClaw CLI Commands Reference](../reference/commands). + For more information, refer to [Quickstart with LangChain Deep Agents Code](/user-guide/deepagents/get-started/quickstart), [Declarative Multi-Agent Manifest](../../openclaw/inference/declarative-agents-manifest), and [NemoClaw CLI Commands Reference](../reference/commands). - Messaging setup has clearer OpenClaw Telegram group defaults. NemoClaw records explicit channel defaults during onboarding, defaults OpenClaw Telegram group access to `TELEGRAM_GROUP_POLICY=open`, and lets operators choose `allowlist` or `disabled` when they need stricter group behavior. For more information, refer to [Messaging Channels](../manage-sandboxes/messaging-channels). diff --git a/docs/deployment/set-up-mcp-bridge.mdx b/docs/deployment/set-up-mcp-bridge.mdx index e3dfb732d1..2238928f42 100644 --- a/docs/deployment/set-up-mcp-bridge.mdx +++ b/docs/deployment/set-up-mcp-bridge.mdx @@ -11,6 +11,7 @@ content: skill: priority: 30 --- +import { AgentOnly } from "../_components/AgentGuide"; NemoClaw lets a sandboxed agent use MCP Streamable HTTP servers without copying external service credentials into the sandbox. @@ -139,8 +140,13 @@ This does not expose the raw credential to the sandbox before the request is aut ## Agent Adapters + + OpenClaw uses `mcporter config add` in the sandbox. + + + Hermes writes this managed HTTP entry under `/sandbox/.hermes/config.yaml`: ```yaml @@ -170,10 +176,14 @@ Success still requires a replacement gateway identity, healthy loopback endpoint There is no host listener, persistent control socket, MCP relay, or service for this operation. The command carries no MCP traffic or raw service credential, and its payload contains only the endpoint definition and OpenShell placeholder. + + + The managed image pins Deep Agents Code `0.1.30` and keeps NemoClaw definitions in `/sandbox/.deepagents/.nemoclaw-mcp.json`. The launcher validates canonical HTTPS endpoints and exact OpenShell credential placeholders, then supplies Deep Agents Code with a process-local, integrity-bound snapshot for server starts and restarts. It prefers a sealed in-memory file when available; the OpenShell-compatible anonymous read-only descriptor fallback verifies the inode, size, and SHA-256 digest and fails closed on drift. NemoClaw never auto-loads the user-owned `/sandbox/.deepagents/.mcp.json` or project MCP files into the managed configuration. +For upstream Deep Agents Code MCP discovery and trust behavior outside NemoClaw's managed path, refer to [MCP tools](https://docs.langchain.com/oss/python/deepagents/code/mcp-tools). ```json { @@ -191,6 +201,8 @@ NemoClaw never auto-loads the user-owned `/sandbox/.deepagents/.mcp.json` or pro External service credential values such as the value of `GITHUB_MCP_TOKEN` remain in OpenShell provider state, not in sandbox files or NemoClaw's sandbox registry. + + ## Operate MCP Servers ```bash @@ -301,9 +313,13 @@ NemoClaw checks inspectable installed OpenShell artifacts for the `protocol: mcp For image-backed or compressed supervisors without an inspectable host runtime artifact, that onboarding check is provisional. Before any credential or provider side effect, the MCP command loads the exact generated policy with `policy set --wait` and exact-matches the effective state; a runtime that rejects `protocol: mcp` therefore fails closed. + + If a Hermes sandbox is alive but its gateway is not running after a supervisor or container restart, run `$$nemoclaw recover` before retrying the MCP command. Recovery re-establishes the managed Hermes service lifecycle, API forwarding, and the exit-75 reload loop used for transactional MCP configuration changes. + + If a mutating MCP command times out waiting for the per-sandbox lifecycle lock, first confirm that no `mcp add`, `mcp restart`, `mcp remove`, `rebuild`, or `destroy` command for that sandbox is still running, then retry the original command. Every mutating command automatically recovers a lock whose local process is provably dead or whose PID now has a different process-start identity, including locks left while stale-lock cleanup was in progress. NemoClaw deliberately does not expose a force-unlock flag: a live owner, a different host or PID namespace, or an incomplete legacy owner record fails closed because removing it could overlap a provider, policy, or adapter mutation. diff --git a/docs/get-started/prerequisites.mdx b/docs/get-started/prerequisites.mdx index a6b7408d38..c0044cd6c1 100644 --- a/docs/get-started/prerequisites.mdx +++ b/docs/get-started/prerequisites.mdx @@ -9,6 +9,8 @@ keywords: ["nemoclaw prerequisites", "nemoclaw supported platforms", "nemoclaw h content: type: "reference" --- +import { AgentOnly } from "../_components/AgentGuide"; + Before you start, verify that your machine has the software and hardware needed to run NemoClaw. ## Hardware @@ -75,7 +77,9 @@ On Linux hosts running Docker 26 or later with the [containerd image store](http The containerd image store is the install-time default for fresh `docker-ce` installations on Ubuntu 24.04 and similar distros. The `fuse-overlayfs`-enabled image bypasses a kernel-level nested-overlay limitation in k3s. You do not need manual setup. + Refer to the [troubleshooting guide](../reference/troubleshooting) for the override knobs and a manual `daemon.json` alternative. + ## Platforms diff --git a/docs/get-started/quickstart-langchain-deepagents-code.mdx b/docs/get-started/quickstart-langchain-deepagents-code.mdx index 7d4607269e..42e89f6510 100644 --- a/docs/get-started/quickstart-langchain-deepagents-code.mdx +++ b/docs/get-started/quickstart-langchain-deepagents-code.mdx @@ -2,7 +2,7 @@ # SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. # SPDX-License-Identifier: Apache-2.0 title: "Quickstart with LangChain Deep Agents Code" -sidebar-title: "LangChain Deep Agents Code" +sidebar-title: "Quickstart with Deep Agents" description: "Create a NemoClaw sandbox that runs LangChain Deep Agents Code as a terminal harness." description-agent: "Creates a NemoClaw sandbox that runs LangChain Deep Agents Code as a terminal harness. Use when testing dcode with NemoClaw-managed inference." keywords: ["langchain deep agents code nemoclaw", "dcode openshell sandbox", "langchain coding agent"] @@ -14,8 +14,40 @@ status: published content: type: "get_started" --- +import { StarterPromptFallback } from "../_components/StarterPrompt"; +import { StarterPromptButton } from "../_components/StarterPromptButton"; -Use this guide to build an OpenShell sandbox with the `dcode` terminal coding agent installed and configured for NemoClaw-managed inference. +Use NemoClaw for Deep Agents to create an OpenShell sandbox that runs LangChain Deep Agents Code. +The `nemo-deepagents` command is an alias for `nemoclaw` with the `langchain-deepagents-code` agent pre-selected. + +Review the [Prerequisites](prerequisites) before starting. +Install Docker, start it, and verify that the current shell can reach it before Deep Agents onboarding builds the sandbox image. +On Linux, the installer can install Docker, start the service, and add your user to the `docker` group. +If it changes group membership, run the printed `newgrp docker` recovery command before rerunning the installer. +On macOS, start Docker Desktop or Colima before you run the installer. + +## Start from Your Coding Agent + +Copy the starter prompt into Cursor, Claude Code, Codex, Copilot, or another local coding agent when you want the assistant to install NemoClaw with you. +The prompt points your agent to [AI Agent Docs](../resources/agent-skills), this quickstart, the Markdown docs, and the optional `nemoclaw-user-guide` skill. +It also asks your agent to confirm LangChain Deep Agents Code as the selected agent before it builds the install or onboard command. + + + + + +## Install and Onboard + +Start the installer with `NEMOCLAW_AGENT=langchain-deepagents-code` set in your shell. +The installer installs the CLI, selects the `nemo-deepagents` alias, and runs the guided onboarding flow. + +```bash +export NEMOCLAW_AGENT=langchain-deepagents-code +curl -fsSL https://www.nvidia.com/nemoclaw.sh | bash +``` + +The hosted installer follows the last-known-good (`lkg`) release tag by default, so this command installs the maintained Deep Agents-capable build without a version override. +If NemoClaw is already installed, start Deep Agents onboarding directly. ## Onboard @@ -31,6 +63,12 @@ nemoclaw onboard --agent deepagents nemoclaw onboard --agent langchain ``` +The onboard wizard asks for an inference provider, model, any required credential, sandbox name, and policy tier before it prints the review summary. +At any prompt, press Enter to accept the default shown in `[brackets]`, type `back` to return to the previous prompt, or type `exit` to quit. +The default Deep Agents sandbox name is `deepagents-code`. +Use a distinct sandbox name, such as `my-deepagents`, so you can run Deep Agents, Hermes, and OpenClaw sandboxes side by side. +For provider-specific prompts, refer to [Inference Options](../inference/inference-options). + The image installs hash-locked Deep Agents Code `0.1.30` with NVIDIA provider support. After the terminal smoke checks, onboarding runs `dcode --version` and compares the result with the version required by the agent manifest. Fresh and resumed onboarding exit nonzero instead of reporting the runtime ready when the installed version is too old, uses an incompatible version scheme, or cannot be verified. @@ -124,15 +162,16 @@ The managed `.deepagents/.nemoclaw-mcp.json` projection is also excluded because Service credentials remain in OpenShell provider state. It also does not preserve `hooks.json`; executable Deep Agents Code hooks are disabled in the managed harness. If `.deepagents/.state/auth.json` contains upstream credentials, or `.deepagents/.state/chatgpt-auth.json` exists, the managed Deep Agents Code launch paths refuse to start until that credential state is removed. -Before a managed Deep Agents Code rebuild changes the sandbox, NemoClaw selects its recorded OpenShell gateway, tests the recorded inference route through `https://inference.local`, and prepares the replacement from the recorded provider, model, reasoning, and web search settings with a pinned base and fingerprinted context. +Before a managed Deep Agents Code rebuild changes the sandbox, NemoClaw selects its recorded OpenShell gateway, tests the recorded inference route through `https://inference.local`, and prepares the replacement from the recorded provider, model, policy, and build inputs with a pinned base and fingerprinted context. Initial failures stop before backup. After backup, NemoClaw rechecks the target, route, and retained build inputs before changing MCP state, then checks again after MCP preparation and before stopping inference or deleting the old sandbox. If the final check fails, NemoClaw restores the previous MCP state and keeps the existing sandbox intact. Rebuild also preserves the standalone Deep Agents Code `tavily` preset and replays recorded custom policies from their exact stored content. -## Optional Web Search +## Optional Tavily Egress -Deep Agents Code can reach Tavily web search once you register a Tavily credential with the OpenShell gateway on the host. +Deep Agents Code does not currently have a NemoClaw-managed web-search feature. +If your project code or a manually configured tool needs Tavily, opt the sandbox Python egress path into Tavily explicitly. Register the raw key only with the OpenShell gateway on the host, not inside the sandbox, in `.env`, or in Deep Agents config files. The gateway injects it at egress instead. The managed Deep Agents Code entry points reject credential-shaped process environment values, disable project `.env` and global `/sandbox/.deepagents/.env` loading, and block upstream `/auth`, `/connect`, startup/onboarding credential prompts, model-selector credential prompts, notification-service key prompts, and ChatGPT OAuth. @@ -141,7 +180,7 @@ Use NemoClaw-managed credential paths when support is available instead of stori NemoClaw does not enable Tavily or LangSmith by default for this harness. The sandbox policy denies `api.tavily.com` and `api.smith.langchain.com` until you opt in. -To enable Tavily for the target sandbox, apply the maintained `tavily` policy preset, register the credential with the OpenShell gateway, then rebuild the sandbox so the new provider attaches. +To allow Tavily egress for the target sandbox, apply the maintained `tavily` policy preset, register the credential with the OpenShell gateway, then rebuild the sandbox so the new provider attaches. The policy preset is a per-sandbox managed-Python opt-in, but provider registration is gateway-wide: `tavily-search` attaches to every sandbox that you build or rebuild afterward. ```bash @@ -207,6 +246,7 @@ There is no dashboard port or long-running gateway process for this harness. ## Next Steps - [Inference Options](../inference/inference-options) explains how to choose a provider and model. +- [Workspace Files](../manage-sandboxes/workspace-files) explains `/sandbox/.deepagents`, memory, skills, and what NemoClaw preserves. - [Backup and Restore](../manage-sandboxes/backup-restore) explains snapshot and rebuild preservation. -- [Runtime Controls](../manage-sandboxes/runtime-controls) explains sandbox mutability and host-side control boundaries. -- [Troubleshooting](../reference/troubleshooting) covers common setup and runtime issues. +- [Set Up MCP Servers](../manage-sandboxes/set-up-mcp-servers) explains managed MCP configuration for Deep Agents sandboxes. +- [Deep Agents Code overview](https://docs.langchain.com/oss/python/deepagents/code/overview) explains upstream `dcode` capabilities and commands. diff --git a/docs/get-started/windows-preparation.mdx b/docs/get-started/windows-preparation.mdx index 3f0b8d9890..77171c3112 100644 --- a/docs/get-started/windows-preparation.mdx +++ b/docs/get-started/windows-preparation.mdx @@ -168,7 +168,12 @@ Do not run both the Windows and WSL Ollama instances on port `11434` at the same Use one instance, or move one of them to a different port before running `$$nemoclaw onboard`. On Windows on Arm N1X systems with a Snapdragon X processor, let NemoClaw choose the Ollama starter model automatically. It selects the compute-constrained `qwen3.5:9b` path instead of recommending the 30B and 35B starter models. -For the selection boundary and remaining N1X limitations, refer to [Use a Local Inference Server](../inference/use-local-inference). + +For the selection boundary and remaining N1X limitations, refer to [Use a Local Inference Server](/user-guide/openclaw/inference/use-local-inference). + + +For the selection boundary and remaining N1X limitations, refer to [Use a Local Inference Server](/user-guide/hermes/inference/use-local-inference). + ## Next Step diff --git a/docs/index.mdx b/docs/index.mdx index 6856a2ad62..4c74dcfdfd 100644 --- a/docs/index.mdx +++ b/docs/index.mdx @@ -4,7 +4,7 @@ title: "NVIDIA NemoClaw" sidebar-title: "Home" description: "NemoClaw is an open-source reference stack for running sandboxed AI agents more safely, with a single command and Markdown docs for AI assistants." -keywords: "NemoClaw, OpenClaw, Hermes, OpenShell, AI agents, Markdown docs, sandboxing, inference routing" +keywords: "NemoClaw, OpenClaw, Hermes, LangChain Deep Agents Code, dcode, OpenShell, AI agents, Markdown docs, sandboxing, inference routing" layout: overview position: 1 --- @@ -45,7 +45,7 @@ Install NemoClaw and run the onboard wizard to get started. ### From Your Coding Agent Copy the starter prompt and paste it into your local coding agent, such as Cursor, Claude Code, Codex, Copilot, or another assistant that can run local commands with your approval. -The prompt tells your agent to use NemoClaw skills when available, bootstrap the docs-routing skill when it is missing, fetch the Markdown docs, collect choices one question at a time, and avoid asking you to paste secrets into chat. +The prompt tells your agent to use NemoClaw skills when available, bootstrap the docs-routing skill when it is missing, fetch the Markdown docs, ask whether you want OpenClaw, Hermes, or Deep Agents, collect choices one question at a time, and avoid asking you to paste secrets into chat. @@ -78,6 +78,7 @@ By default, NemoClaw installs the OpenClaw agent. Use one of the following quick |-------|-------| | OpenClaw (default) | [Quickstart with OpenClaw](../openclaw/get-started/quickstart) | | Hermes | [Quickstart with Hermes](../hermes/get-started/quickstart) | +| LangChain Deep Agents Code | [Quickstart with Deep Agents](../deepagents/get-started/quickstart) |
@@ -138,6 +139,13 @@ Read the Hermes-focused overview before launching a Hermes sandboxed agent. Overview + + +Read the Deep Agents-focused overview before launching a `dcode` sandboxed terminal agent. + +Overview + + --- diff --git a/docs/index.yml b/docs/index.yml index 8eea7f133f..12f93add6a 100644 --- a/docs/index.yml +++ b/docs/index.yml @@ -47,9 +47,6 @@ navigation: - page: "Quickstart with OpenClaw" path: get-started/quickstart.mdx slug: quickstart - - page: "Quickstart with LangChain Deep Agents Code" - path: get-started/quickstart-langchain-deepagents-code.mdx - slug: quickstart-langchain-deepagents-code - section: "Inference" slug: inference collapsed: open-by-default @@ -199,6 +196,123 @@ navigation: - page: "License" path: _build/agent-variants/resources/license.openclaw.generated.mdx slug: license + - title: NemoClaw for Deep Agents + subtitle: Guide for LangChain Deep Agents Code + slug: deepagents + layout: + - page: "Home" + path: index.mdx + slug: home + - section: "About NemoClaw" + slug: about + collapsed: open-by-default + contents: + - page: "Overview" + path: _build/agent-variants/about/overview.deepagents.generated.mdx + slug: overview + - page: "Architecture Overview" + path: _build/agent-variants/about/how-it-works.deepagents.generated.mdx + slug: how-it-works + - page: "Ecosystem" + path: about/ecosystem-deepagents.mdx + slug: ecosystem + - page: "Release Notes" + path: _build/agent-variants/about/release-notes.deepagents.generated.mdx + slug: release-notes + - section: "Get Started" + slug: get-started + collapsed: open-by-default + contents: + - section: "Prerequisites" + path: _build/agent-variants/get-started/prerequisites.deepagents.generated.mdx + slug: prerequisites + contents: + - page: "(Windows Only) Windows Prerequisites" + path: _build/agent-variants/get-started/windows-preparation.deepagents.generated.mdx + slug: windows-preparation + - page: "Quickstart with Deep Agents" + path: get-started/quickstart-langchain-deepagents-code.mdx + slug: quickstart + - section: "Inference" + slug: inference + collapsed: open-by-default + contents: + - page: "Inference Options" + path: _build/agent-variants/inference/inference-options.deepagents.generated.mdx + slug: inference-options + - page: "Model Capability Audit" + path: _build/agent-variants/inference/model-capability-audit.deepagents.generated.mdx + slug: model-capability-audit + - page: "Switch Inference Providers" + path: _build/agent-variants/inference/switch-inference-providers.deepagents.generated.mdx + slug: switch-inference-providers + - section: "Manage Sandboxes" + slug: manage-sandboxes + collapsed: open-by-default + contents: + - page: "Manage Sandbox Lifecycle" + path: _build/agent-variants/manage-sandboxes/lifecycle.deepagents.generated.mdx + slug: lifecycle + - page: "Set Up MCP Servers" + path: _build/agent-variants/deployment/set-up-mcp-bridge.deepagents.generated.mdx + slug: set-up-mcp-servers + - page: "Workspace Files" + path: _build/agent-variants/manage-sandboxes/workspace-files.deepagents.generated.mdx + slug: workspace-files + - page: "Backup and Restore" + path: _build/agent-variants/manage-sandboxes/backup-restore.deepagents.generated.mdx + slug: backup-restore + - section: "Security" + slug: security + collapsed: open-by-default + contents: + - page: "Security Best Practices" + path: _build/agent-variants/security/best-practices.deepagents.generated.mdx + slug: best-practices + - page: "Credential Storage" + path: _build/agent-variants/security/credential-storage.deepagents.generated.mdx + slug: credential-storage + - section: "Reference" + slug: reference + collapsed: open-by-default + contents: + - page: "Platform Support" + path: reference/platform-support.mdx + slug: platform-support + - page: "Architecture Details" + path: _build/agent-variants/reference/architecture.deepagents.generated.mdx + slug: architecture + - page: "CLI Commands Reference" + path: _build/agent-variants/reference/commands.deepagents.generated.mdx + slug: commands + - page: "CLI Selection Guide" + path: _build/agent-variants/reference/cli-selection-guide.deepagents.generated.mdx + slug: cli-selection-guide + - page: "Host Files and State" + path: _build/agent-variants/reference/host-files-and-state.deepagents.generated.mdx + slug: host-files-and-state + - page: "Network Policies" + path: _build/agent-variants/reference/network-policies.deepagents.generated.mdx + slug: network-policies + - page: "Troubleshooting" + path: _build/agent-variants/reference/troubleshooting.deepagents.generated.mdx + slug: troubleshooting + - section: "Resources" + slug: resources + collapsed: open-by-default + contents: + - page: "AI Agent Docs" + path: _build/agent-variants/resources/agent-skills.deepagents.generated.mdx + slug: agent-skills + - link: "Community Examples" + href: https://github.com/NVIDIA/nemoclaw-community + - link: "Report Vulnerabilities" + href: https://github.com/NVIDIA/NemoClaw/blob/main/SECURITY.md + - page: "License" + path: _build/agent-variants/resources/license.deepagents.generated.mdx + slug: license + - link: "Discord" + href: https://discord.gg/XFpfPv9Uvx - title: NemoClaw for Hermes subtitle: Guide for Hermes agents slug: hermes @@ -330,7 +444,7 @@ navigation: path: _build/agent-variants/reference/architecture.hermes.generated.mdx slug: architecture - page: "CLI Commands Reference" - path: reference/commands-nemohermes.mdx + path: _build/agent-variants/reference/commands.hermes.generated.mdx slug: commands - page: "CLI Selection Guide" path: _build/agent-variants/reference/cli-selection-guide.hermes.generated.mdx diff --git a/docs/inference/inference-options.mdx b/docs/inference/inference-options.mdx index 23828b53ff..cc7de696e0 100644 --- a/docs/inference/inference-options.mdx +++ b/docs/inference/inference-options.mdx @@ -24,6 +24,10 @@ The provider flow is the same, with the NVIDIA Endpoints route available for Ope For Hermes onboarding, use `$$nemoclaw onboard`. The provider flow is the same, with the Hermes Provider route available for Hermes Agent. + +For Deep Agents onboarding, use `$$nemoclaw onboard`. +The provider flow is the same, and the managed `dcode` configuration uses the OpenAI-compatible `https://inference.local/v1` route inside the sandbox. + ## How Inference Routing Works @@ -35,6 +39,10 @@ Provider credentials stay on the host. The sandbox does not receive your API key. Local Ollama and local vLLM do not require your host `OPENAI_API_KEY`. NemoClaw uses provider-specific local tokens for those routes, and rebuilds of legacy local-inference sandboxes migrate away from stale OpenAI credential requirements. + +For Deep Agents, NemoClaw writes `/sandbox/.deepagents/config.toml` with the managed OpenAI-compatible `https://inference.local/v1` route, a scoped placeholder API key, and `use_responses_api = false`. +The managed `dcode` runtime uses Chat Completions through OpenShell even when a compatible endpoint also supports the Responses API. + ## Provider Status @@ -80,7 +88,7 @@ NemoClaw neither displays nor accepts an unsafe `NEMOCLAW_MODEL` value as the ma | Other Anthropic-compatible endpoint | Routes agents that support Anthropic Messages, including OpenClaw, to `/v1/messages`. For Hermes and agents that only support OpenAI-compatible inference, NemoClaw instead requires `/v1/chat/completions`, which is the surface it validates and uses at runtime. The adapter is validated against AWS Bedrock (refer to the status table above); behavior on other Anthropic-compatible proxies and gateways may vary. The wizard prompts for a base URL and model name. Set `COMPATIBLE_ANTHROPIC_API_KEY`. | You provide the model name. | | Google Gemini | Routes to Google's OpenAI-compatible chat-completions endpoint. NemoClaw skips the Responses-API probe because Gemini does not support `/v1/responses`. Set `GEMINI_API_KEY`. | `gemini-3.1-pro-preview`, `gemini-3.1-flash-lite-preview`, `gemini-3-flash-preview`, `gemini-2.5-pro`, `gemini-2.5-flash`, `gemini-2.5-flash-lite` | | Hermes Provider | Routes Hermes Agent through the host OpenShell provider registered by NemoClaw when onboarding Hermes Agent. | Curated Hermes Provider models such as `moonshotai/kimi-k2.6`, `openai/gpt-5.4-mini`, and `z-ai/glm-5.1`. | -| Local Ollama | Routes to a local Ollama instance on `localhost:11434`. NemoClaw detects installed models, offers starter models if none are present, pulls and warms the selected model, and validates it. | Selected during onboarding. For more information, refer to [Use a Local Inference Server](use-local-inference). | +| Local Ollama | Routes to a local Ollama instance on `localhost:11434`. NemoClaw detects installed models, offers starter models if none are present, pulls and warms the selected model, and validates it. | Selected during onboarding. | | Model Router | Starts a host-side router on port `4000`, registers it as an OpenAI-compatible provider, and keeps the sandbox pointed at `inference.local`. Set `NEMOCLAW_PROVIDER=routed` for non-interactive setup. | The router pool defines the model names. | ### Custom Endpoint URL Validation @@ -229,7 +237,9 @@ An already-running vLLM server appears directly in the onboarding selection list | Local NVIDIA NIM | NIM-capable GPU detected | Pulls and manages a NIM container. | | Local vLLM | vLLM running on `localhost:8000`, or a supported DGX Spark, DGX Station, or Linux NVIDIA GPU profile | Auto-detects the loaded model when vLLM is already running. Can install or start a managed vLLM container by default on DGX Spark/Station and after opt-in on generic Linux NVIDIA GPU hosts. | + For setup instructions, refer to [Use a Local Inference Server](use-local-inference). + ## Validation @@ -250,6 +260,11 @@ Other provider credentials, such as `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `GEMI | Compatible endpoints | Sends a real inference request because many proxies do not expose a `/models` endpoint. For OpenAI-compatible endpoints, the probe tries `/v1/responses` first then falls back to `/v1/chat/completions`; the selected runtime API defaults to `/v1/chat/completions`. Set `NEMOCLAW_PREFERRED_API=openai-responses` to allow `/v1/responses` at runtime when validation succeeds. | | Local NVIDIA NIM | Validates through `/v1/chat/completions` only; NemoClaw skips the `/v1/responses` probe (same as NVIDIA Endpoints). | + +Deep Agents runtime validation also checks that generated `config.toml` points at `https://inference.local/v1` and that the sandbox can use the managed OpenShell L7 proxy path. +If you change providers or models for an existing Deep Agents sandbox, run `nemo-deepagents onboard --fresh --name --recreate-sandbox` so NemoClaw rewrites the config and route together. + + ## Setup Details for Local and Compatible Providers The sections below collect the detailed setup prompts and environment variables for local and compatible inference providers. @@ -334,6 +349,10 @@ NEMOCLAW_PREFERRED_API=openai-responses $$nemoclaw onboard The wizard then probes `/v1/responses` and only selects it when streaming support is complete. If the probe fails, the wizard falls back to `/v1/chat/completions` automatically. You can use this variable in both interactive and non-interactive mode. + +This environment variable does not change the managed Deep Agents `dcode` runtime. +Deep Agents sandboxes keep `use_responses_api = false` in `/sandbox/.deepagents/config.toml` so the terminal harness uses Chat Completions through the OpenShell route. + | Variable | Values | Default | |---|---|---| @@ -548,11 +567,15 @@ export NEMOCLAW_SANDBOX_READY_TIMEOUT=600 $$nemoclaw onboard ``` + If onboard ends with `Sandbox '' was created but did not become ready within 180s`, refer to [Troubleshooting](../reference/troubleshooting#sandbox-onboard-times-out-with-did-not-become-ready-within-ns). + ## Next Steps + - [Use a Local Inference Server](use-local-inference) for Ollama, vLLM, NIM, and compatible-endpoint setup details. + - [Tool-Calling Reliability](tool-calling-reliability) for deciding when Ollama is enough and when vLLM with a parser is safer. diff --git a/docs/inference/model-capability-audit.mdx b/docs/inference/model-capability-audit.mdx index 227a9117a2..70e3347db8 100644 --- a/docs/inference/model-capability-audit.mdx +++ b/docs/inference/model-capability-audit.mdx @@ -43,9 +43,9 @@ If a field is not applicable, write `n/a` and explain why in the evidence notes. |---|---| | Model ID | Exact model identifier used by onboarding or runtime config. | | Provider path | Provider class and route, such as NVIDIA Endpoints, OpenAI, Anthropic, Gemini, Local Ollama, Local vLLM, or another compatible endpoint. | -| Agent surface | Exact agent path, such as OpenClaw primary agent, OpenClaw CLI prompt path, OpenClaw browser or gateway path, OpenClaw sub-agent delegation, Hermes sandbox API, or auxiliary model path. | +| Agent surface | Exact agent path, such as OpenClaw primary agent, OpenClaw CLI prompt path, OpenClaw browser or gateway path, OpenClaw sub-agent delegation, Hermes sandbox API, Deep Agents interactive `dcode`, Deep Agents headless `dcode -n`, or auxiliary model path. | | NemoClaw commit SHA | Full commit SHA for the repo state used during validation. | -| Runtime versions | OpenShell, OpenClaw, Hermes, provider server, and local serving versions when available. | +| Runtime versions | OpenShell, OpenClaw, Hermes, Deep Agents Code, provider server, and local serving versions when available. | | Endpoint/API path selected | Concrete API path, base URL class, and provider key selected by NemoClaw. | | Workflow used | Exact command sequence or CI workflow used to run the scenario. | | State | One result state from this page. | @@ -69,6 +69,7 @@ Rows can remain `degraded`, `blocked`, or `not-yet-run` when a scenario cannot b | Multi-turn continuation | Turn 2 uses a tool result from turn 1 and does not ask the user to continue after a complete tool result. | | Sub-agent delegation | The primary agent emits a structured `sessions_spawn` request, the sub-agent receives the intended task and workspace, and the primary agent consumes the result. | | Hermes path | Hermes starts with the selected provider/model, returns the expected OpenAI-compatible response shape, keeps core tools direct, and uses its native structured `tool_search` -> `tool_describe` -> `tool_call` path for a deferred tool. Keep Hermes `tools.tool_search.enabled: on` evidence separate from OpenClaw `tools.toolSearch.mode: tools` evidence. | +| Deep Agents path | `dcode status` reports the managed route, interactive `dcode` can complete a terminal task with approval prompts intact, and headless `dcode -n` can complete a bounded non-shell task while preserving the managed Chat Completions route. Keep interactive approval evidence separate from headless auto-approval evidence. | | Performance and operability | The row records validation duration, first event timing when available, retry behavior, timeout budget, streaming requirement, request mutation requirement, API path forcing, and cold-start differences. | ## Audit Matrix @@ -90,6 +91,8 @@ When importing a completed row from an issue comment, preserve the exact commit | OpenClaw primary agent | Other OpenAI-compatible endpoint | User-selected `custom-model` or another configured model id. | Managed `inference.local` route to the compatible endpoint. | `not-yet-run` | Add endpoint class and trajectory evidence before changing state. | Record endpoint API path forcing and store/streaming assumptions. | Add one row per endpoint class that is validated. | `src/lib/inference/config.ts`. | | OpenClaw primary agent | Other Anthropic-compatible endpoint | User-selected `custom-anthropic-model` or another configured model id. | `anthropic` route when supported, otherwise managed compatible route. | `not-yet-run` | Add endpoint class and trajectory evidence before changing state. | Record native Anthropic Messages or compatible-route transport behavior. | Add one row per endpoint class that is validated. | `src/lib/inference/config.ts`. | | Hermes sandbox API | Hermes Provider | Default `moonshotai/kimi-k2.6` or any model from `HERMES_PROVIDER_MODEL_OPTIONS`. | Hermes Provider route through NemoClaw managed inference. | `not-yet-run` | Add Hermes session, request dump, logs, and local API evidence before changing state. | Generated config uses native `tools.tool_search.enabled: on` with snake-case 5/20 limits; core tools stay direct while deferred MCP and non-core plugin tools use structured search, describe, and call. | Verify a deferred-tool trajectory and keep it separate from OpenClaw `mode: tools` evidence. | `agents/hermes/config/hermes-config.ts`, `test/generate-hermes-config.test.ts`. | +| Deep Agents interactive `dcode` | NVIDIA Endpoints | `nvidia/nemotron-3-super-120b-a12b` | Managed `inference.local` OpenAI-compatible Chat Completions with `use_responses_api = false`. | `not-yet-run` | Add interactive terminal transcript, status output, and route evidence before changing state. | Managed `/sandbox/.deepagents/config.toml` forces the OpenAI-compatible route and disables Responses API for `dcode`. | Verify a terminal task with approval prompts intact and no provider credential in sandbox-visible files. | `agents/langchain-deepagents-code/generate-config.ts`, `docs/get-started/quickstart-langchain-deepagents-code`. | +| Deep Agents headless `dcode -n` | NVIDIA Endpoints | `nvidia/nemotron-3-super-120b-a12b` | Managed `inference.local` OpenAI-compatible Chat Completions with `use_responses_api = false`. | `not-yet-run` | Add headless command transcript and status output before changing state. | Headless mode has no approval UI and auto-approves non-shell tools while managed shell execution remains disabled. | Verify a bounded non-shell task and record the approval boundary separately from interactive evidence. | `agents/langchain-deepagents-code/dcode-wrapper.sh`, `docs/security/best-practices`. | ## Completed Row Template @@ -100,9 +103,9 @@ Do not leave placeholder text in a completed row. |---|---| | Model ID | ``. | | Provider path | ``. | -| Agent surface | ``. | +| Agent surface | ``. | | NemoClaw commit SHA | ``. | -| Runtime versions | ``. | +| Runtime versions | ``. | | Endpoint/API path selected | ``. | | Workflow used | ``. | | State | ``. | diff --git a/docs/inference/switch-inference-providers.mdx b/docs/inference/switch-inference-providers.mdx index 4fa8c8dffc..9410a71cbd 100644 --- a/docs/inference/switch-inference-providers.mdx +++ b/docs/inference/switch-inference-providers.mdx @@ -1,10 +1,10 @@ --- # SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. # SPDX-License-Identifier: Apache-2.0 -title: "Switch Inference Models at Runtime" +title: "Switch Inference Models" sidebar-title: "Switch Inference Providers" -description: "Change the active inference model for a running sandbox without restarting it." -description-agent: "Changes the active inference model for a running sandbox without restarting it. Use when switching inference providers, changing the model runtime, or reconfiguring inference routing." +description: "Change the active inference model for a NemoClaw-managed sandbox." +description-agent: "Changes the active inference model for a NemoClaw-managed sandbox. Use when switching inference providers, changing the model runtime, or reconfiguring inference routing." keywords: ["switch nemoclaw inference model", "change inference runtime"] content: type: "how_to" @@ -13,14 +13,28 @@ skill: --- import { AgentOnly } from "../_components/AgentGuide"; -Change the active inference model while the sandbox is running. -You do not need to restart the sandbox. +Change the active inference model for a NemoClaw-managed sandbox. +OpenClaw and Hermes can update the running sandbox route without a restart. +Deep Agents sandboxes should use the recreate path so the OpenShell route and `/sandbox/.deepagents/config.toml` stay aligned. -## Prerequisites +Choose one of these paths: -- A running NemoClaw sandbox created or resumed with `$$nemoclaw onboard`. -- A selected default sandbox, or pass `--sandbox ` to each `$$nemoclaw inference set` command when more than one sandbox is registered. -- The OpenShell CLI on your `PATH`, which NemoClaw uses internally. +- Runtime switch: use `$$nemoclaw inference set` for OpenClaw and Hermes when the target provider is already registered on the sandbox. + This updates the OpenShell route and synchronizes the running agent config without recreating the sandbox. +- Fresh recreation: use `$$nemoclaw onboard --fresh --name --recreate-sandbox` for a consistent all-agent path. + This is required for Deep Agents provider or model changes, and it also applies to any agent when you change build-time settings. +- Recorded rebuild: use `$$nemoclaw rebuild` when you want to recreate the sandbox from the provider and model already recorded in the registry. + That rebuild flow may use an internal resume handoff, but it does not choose a new provider or model. +- Interrupted recovery: use `--resume` only to recover an interrupted onboarding session. + +## Before You Start + +- Start from an existing NemoClaw sandbox created with `$$nemoclaw onboard`. +- Keep the OpenShell CLI on your `PATH`, which NemoClaw uses internally. +- For runtime switches, select a default sandbox or pass `--sandbox ` to each `$$nemoclaw inference set` command when more than one sandbox is registered. +- For fresh recreation, pass the existing sandbox name when you want to replace that sandbox. +- For side-by-side validation, pass a new sandbox name and switch the default after the new sandbox passes validation. +- Keep the required provider credential available in your host shell before rerunning onboarding. If you run `$$nemoclaw inference set` before NemoClaw has a selected sandbox, the CLI exits with `No sandbox selected`. @@ -38,6 +52,8 @@ When a route conflicts, onboarding, runtime switching, and connect-time repair e Align the routes, remove the conflicting sandbox, or onboard it with another `NEMOCLAW_GATEWAY_PORT`. + + ## Find the Provider Name The `--provider` value must match a provider already configured on the sandbox. @@ -61,6 +77,8 @@ $$nemoclaw inference set --provider compatible-anthropic-endpoint --model + ## Switch to a Different Model @@ -73,12 +91,25 @@ Use `$$nemoclaw inference set` with the provider and model that match the upstre The command updates the OpenShell inference route and synchronizes the running agent config. For Hermes, it updates `/sandbox/.hermes/config.yaml` (`model.default`, `model.base_url`, `model.provider: custom`, API-family mode when needed, and the OpenShell proxy API-key placeholder) without rebuilding or restarting Hermes. Pass `--sandbox ` when you do not want to use the default registered sandbox or when you have registered more than one Hermes sandbox. + + + +For Deep Agents, use a fresh named recreation when you need to switch providers or models. +The managed `dcode` runtime reads `/sandbox/.deepagents/config.toml`, which NemoClaw writes during onboarding and rebuilds. +The recreate path keeps that file, the OpenShell route, and the host registry in sync while runtime switching for Deep Agents is still being hardened. +The `--resume` flag is not a provider or model switch path for any variant. +After completed onboarding, sessions are no longer resumable. +During an interrupted resume, NemoClaw reuses the recorded provider and model. +Pass the existing sandbox name when you want to replace that sandbox. + Pass `--sandbox ` when you do not want to use the default registered sandbox. + + ### NVIDIA Endpoints ```bash @@ -121,6 +152,7 @@ If the durable metadata is incomplete, NemoClaw fails closed and tells you to re Any `--endpoint-url` you pass is always validated by the host-side SSRF guard, so a URL that resolves to a private or internal address is rejected even if it matches the recorded endpoint. To point the sandbox at a different endpoint, re-run `$$nemoclaw onboard` with the new endpoint because rebuild reuses the recorded endpoint and cannot change it. + ### Hermes Provider @@ -131,10 +163,31 @@ For a NemoClaw-managed Hermes sandbox, use the Hermes alias with the registered $$nemoclaw inference set --provider hermes-provider --model openai/gpt-5.4-mini ``` + + + +### Deep Agents Recreate Path + +Use the fresh recreate path for Deep Agents provider or model changes: + +```bash +nemo-deepagents onboard --fresh --name --recreate-sandbox +``` + +The wizard prompts for provider and model choices, backs up the existing sandbox state, recreates the named sandbox, and rewrites the managed `dcode` config for the new route. +If you want to keep the current sandbox until the new route passes validation, create a side-by-side sandbox first: + +```bash +nemo-deepagents onboard --fresh --name +nemo-deepagents use +``` + ### API Family Sync + + Before patching the in-sandbox config, NemoClaw resolves the target route's API family: OpenAI chat completions, Anthropic Messages, or OpenAI Responses. For OpenClaw, `inference set` syncs the provider API family and primary model reference into the running config. Switches within the current API family hot-reload without replacing the gateway process. @@ -145,6 +198,12 @@ That failure does not roll back the committed route or config; run `$$nemoclaw < For Hermes, `inference set` writes `model.api_mode: anthropic_messages` for Anthropic Messages routes, `model.api_mode: codex_responses` for OpenAI Responses routes, and removes `api_mode` for OpenAI-style chat-completions routes. Hermes also keeps `model.api_key` on the OpenShell proxy placeholder so dashboard and API sessions continue to authenticate through the gateway after a route change. + + +For Deep Agents, NemoClaw keeps the managed runtime on Chat Completions with `use_responses_api = false`. +`NEMOCLAW_PREFERRED_API=openai-responses` can affect compatible-endpoint onboarding probes for other variants, but it does not switch managed `dcode` to the Responses API. + + For `compatible-anthropic-endpoint`, NemoClaw selects the managed OpenAI Chat Completions frontend at `https://inference.local/v1` and verifies the endpoint's `/v1/chat/completions` surface before registering it with OpenShell as `type=openai` using `OPENAI_BASE_URL`. The route retains `COMPATIBLE_ANTHROPIC_API_KEY` as its credential binding. @@ -163,6 +222,8 @@ Resuming onboarding also detects and repairs a stale route. When supplying new custom metadata, Hermes may omit `--inference-api` for this provider because NemoClaw deterministically selects `openai-completions`; an explicit non-OpenAI value is rejected. + + #### Switching from Responses API to Chat Completions If onboarding selected `/v1/responses` but the agent fails at runtime, re-run onboarding so the wizard re-probes the endpoint and bakes the correct API path into the image. @@ -188,6 +249,8 @@ If you recreate the sandbox without the override environment variable, the image A fresh `$$nemoclaw onboard` is the reliable fix because it updates both the session and the baked image. + + ## Cross-Provider Switching @@ -212,7 +275,17 @@ $$nemoclaw inference set --provider anthropic-prod --model claude-sonnet-4-6 --n ``` + +Cross-provider changes for Deep Agents should use sandbox recreation instead of `$$nemoclaw inference set`. +The recreate flow validates the target provider, rewrites `/sandbox/.deepagents/config.toml`, preserves manifest-defined state, and rebuilds managed MCP projection state from the host registry. +```bash +nemo-deepagents onboard --fresh --name --recreate-sandbox +``` + + + + Before you switch provider families, the target provider must already be registered through onboarding. If OpenShell cannot find the requested provider, NemoClaw leaves the route and sandbox state unchanged. The error includes a redacted OpenShell detail, lists the registered providers when available, and tells you to run onboarding. @@ -220,6 +293,9 @@ Run `$$nemoclaw onboard` to register the provider, then retry `$$nemoclaw infere Use `--no-verify` only when OpenShell cannot verify the provider at switch time but you have already confirmed the provider and credential. `--no-verify` does not bypass the one-route-per-gateway compatibility check. + + + ## Tune Model Metadata @@ -252,6 +328,8 @@ export NEMOCLAW_AGENT_HEARTBEAT_EVERY=0m $$nemoclaw onboard ``` + + `NEMOCLAW_AGENT_TIMEOUT` controls the per-request inference timeout baked into `agents.defaults.timeoutSeconds`. @@ -280,23 +358,27 @@ Tune the cadence with a duration string like `5m` or `2h`, or set `0m` to disabl Disabling also drops `HEARTBEAT.md` from normal-run bootstrap context per upstream behavior, so the model no longer sees heartbeat-only instructions. NemoClaw writes this value into `openclaw.json` during onboarding. The in-sandbox `openclaw config set` command is not the supported path for NemoClaw-managed build-time defaults, and a rebuild overwrites direct file edits. -Rebuild the sandbox with `$$nemoclaw onboard --resume` to apply a new value. +Recreate the sandbox with `$$nemoclaw onboard --fresh --name --recreate-sandbox` to apply a new value. Hermes does not use OpenClaw's `HEARTBEAT.md` wake-up mechanism. -Rebuild the sandbox with `$$nemoclaw onboard --resume` to apply build-time inference metadata changes. +Recreate the sandbox with `$$nemoclaw onboard --fresh --name --recreate-sandbox` to apply build-time inference metadata changes. + + These variables are build-time settings. If you change them on an existing sandbox, recreate the sandbox so the new values bake into the image: ```bash -$$nemoclaw onboard --resume --recreate-sandbox +$$nemoclaw onboard --fresh --name --recreate-sandbox ``` + + ## Verify the Active Model Use `$$nemoclaw inference get` to print the provider and model the gateway is currently routing to. @@ -346,7 +428,7 @@ The status output includes the active provider, model, and endpoint with the res - The host keeps provider credentials. - The sandbox continues to use `inference.local`. - `$$nemoclaw inference set` patches the selected running OpenClaw sandbox config and recomputes its config hash. -- Use `$$nemoclaw onboard --resume --recreate-sandbox` for build-time settings such as context window, max tokens, reasoning mode, heartbeat cadence, or image contents. +- Use `$$nemoclaw onboard --fresh --name --recreate-sandbox` for build-time settings such as context window, max tokens, reasoning mode, heartbeat cadence, or image contents. - Local Ollama and local vLLM routes use local provider tokens rather than `OPENAI_API_KEY`. Rebuilds of older local-inference sandboxes clear the stale OpenAI credential requirement automatically. @@ -355,9 +437,18 @@ The status output includes the active provider, model, and endpoint with the res - The host keeps provider credentials. - The sandbox continues to use `inference.local`. - `$$nemoclaw inference set` patches the selected running Hermes sandbox config and recomputes its config hash. -- Use `$$nemoclaw onboard --resume --recreate-sandbox` for build-time settings such as context window, max tokens, reasoning mode, heartbeat cadence, or image contents. +- Use `$$nemoclaw onboard --fresh --name --recreate-sandbox` for build-time settings such as context window, max tokens, reasoning mode, heartbeat cadence, or image contents. - Local Ollama and local vLLM routes use local provider tokens rather than `OPENAI_API_KEY`. Rebuilds of older local-inference sandboxes clear the stale OpenAI credential requirement automatically. + + + +- The host keeps provider credentials. +- The sandbox continues to use `inference.local`. +- Use `nemo-deepagents onboard --fresh --name --recreate-sandbox` for provider, model, context window, max tokens, reasoning mode, timeout, or image-content changes. +- The managed `dcode` runtime uses Chat Completions through `/sandbox/.deepagents/config.toml` with `use_responses_api = false`. +- Local Ollama and local vLLM routes use local provider tokens rather than `OPENAI_API_KEY`. + ## Related Topics diff --git a/docs/inference/use-local-inference.mdx b/docs/inference/use-local-inference.mdx index bd80cb4e84..fbc77d72b8 100644 --- a/docs/inference/use-local-inference.mdx +++ b/docs/inference/use-local-inference.mdx @@ -86,11 +86,13 @@ NemoClaw lists installed models or offers starter models if you have not install On hosts where the larger starter models fit the currently available GPU memory, the starter list includes `qwen3.6:35b` and selects it by default. When another GPU workload is using most of the memory at onboard time, NemoClaw downgrades the menu to the largest model that still fits. It pulls the selected model, loads it into memory, and validates it before continuing. + When Ollama reports a loaded-model context length, NemoClaw uses that value for the `contextWindow` baked into `openclaw.json` unless you set `NEMOCLAW_CONTEXT_WINDOW` yourself. If the selected model declares that it does not support tool calling, onboarding stops with guidance to choose a model whose `ollama show ` capabilities include `tools`. The validation also requires structured chat-completions tool calls. If the model leaks tool-call JSON as plain message text, onboarding stops so you can choose a model that returns tool calls in the expected response field. If a host-side validation probe times out, NemoClaw retries the Ollama tool-call validation with a larger timeout before failing the setup. + On WSL, if you choose the Windows-host Ollama path, NemoClaw uses `host.docker.internal:11434` and pulls missing models through the Ollama HTTP API instead of requiring the `ollama` CLI inside WSL. ### WSL with Windows-Host Ollama @@ -194,8 +196,10 @@ After a selected model fails validation, NemoClaw excludes that tag from the nex On Windows on Arm N1X systems with a Snapdragon X processor, NemoClaw treats the integrated GPU as compute-constrained even when its shared-memory total appears large enough for a bigger model. Automatic Ollama bootstrap selection omits `qwen3.6:35b` and `nemotron-3-nano:30b` and selects `qwen3.5:9b` instead. This is a model-selection safeguard only. + It does not make 30B or 35B models usable on N1X, add a general refusal for an explicitly selected large model, or resolve the OpenClaw `1006` disconnect, embedded fallback, and model-timeout behavior tracked in [issue #3707](https://github.com/NVIDIA/NemoClaw/issues/3707). When Ollama reports a loaded-model context length below `16384` and `NEMOCLAW_CONTEXT_WINDOW` is unset, NemoClaw raises the baked `contextWindow` to `16384` so the agent prompt and tool definitions fit better than the stock daemon default. + If the initial Ollama validation probe times out during a cold load, NemoClaw retries once with a 300-second probe budget. This applies beyond DGX Spark, including tight-VRAM dGPU hosts where warm-up can spill from GPU to CPU. @@ -213,8 +217,11 @@ Run onboard without `--non-interactive` to get the interactive `[y/N]` prompt th ## Compatible Local Servers Use **Other OpenAI-compatible endpoint** for vLLM, TensorRT-LLM, llama.cpp, LocalAI, NIM, SGLang, or another server that implements `/v1/chat/completions`. -For compatible endpoints, NemoClaw uses `/v1/chat/completions` by default because some local backends accept `/v1/responses` but drop system prompts or tool definitions. +For compatible endpoints, NemoClaw uses `/v1/chat/completions` by default. + +This avoids local backends that accept `/v1/responses` but drop system prompts or tool definitions. Set `NEMOCLAW_PREFERRED_API=openai-responses` only after you have verified that the backend streams the events OpenClaw requires. + Use this path when you already have a local server for a raw model file, such as a GGUF model served by `llama-server`. The Ollama picker accepts Ollama model tags, not a filesystem path to a `.gguf` file. diff --git a/docs/manage-sandboxes/backup-restore.mdx b/docs/manage-sandboxes/backup-restore.mdx index 59b013adf7..71b3ccd346 100644 --- a/docs/manage-sandboxes/backup-restore.mdx +++ b/docs/manage-sandboxes/backup-restore.mdx @@ -33,6 +33,13 @@ This guide covers snapshot commands, all-sandbox backups, and manual backup with - Before major NemoClaw version upgrades. - Periodically, if you have invested time customizing your agent or paired messaging channels. + + + +- Before running `$$nemoclaw destroy`. +- Before major NemoClaw version upgrades. +- Periodically, if you have invested time customizing Deep Agents skills, memory, or managed MCP state. + ## Snapshot Commands @@ -40,9 +47,18 @@ This guide covers snapshot commands, all-sandbox backups, and manual backup with Use the built-in snapshot commands for the fastest backup and restore path. Snapshots capture all workspace state directories defined in the agent manifest and store them in `~/.nemoclaw/rebuild-backups//`. Agent manifests can also declare durable top-level state files. + For Hermes, snapshots include `SOUL.md` and the SQLite database behind `.hermes/state.db` using SQLite's online backup API, then restore that database through SQLite instead of copying a live raw database file. + + +For Deep Agents, snapshots include manifest-declared state under `/sandbox/.deepagents`, including skills and runtime state, while omitting credential-bearing user files. +NemoClaw refuses to create a snapshot when it detects an active `dcode` task or cannot verify that the Deep Agents state tree is idle. +Wait for active `dcode` work to finish before running `$$nemoclaw snapshot create`. + Treat snapshot directories as private local data. + The Hermes database can contain session metadata and message history needed for a faithful restore. + Snapshots also preserve sandbox registry metadata that affects rebuild behavior, including custom policy presets applied with `policy-add --from-file` or `policy-add --from-dir`. When you restore a snapshot, NemoClaw replays those recorded custom presets with their stored YAML content, so you do not need the original preset files on disk for the restored sandbox to keep the same policy state. @@ -103,7 +119,27 @@ NemoClaw-regenerated Hermes config files, including `config.yaml` and `.env`, ar NemoClaw recreates model/provider and messaging credentials from host-side onboarding and OpenShell provider state during rebuild. + + +The `$$nemoclaw rebuild` command uses the same snapshot mechanism automatically. +NemoClaw rejects unsafe symlinks and hard links inside sandbox state during backup creation before they can enter a snapshot. +Credential-bearing Deep Agents files such as `.deepagents/.env` and user-authored `.deepagents/.mcp.json` are intentionally excluded from snapshots. +Deep Agents auth state files such as `.deepagents/.state/auth.json` and `.deepagents/.state/chatgpt-auth.json` are also excluded because the managed launcher refuses to start when upstream credential state is present. +The managed `.deepagents/.nemoclaw-mcp.json` projection and `hooks.json` are also excluded because NemoClaw reconstructs managed MCP state and disables executable Deep Agents Code hooks in the managed harness. +NemoClaw recreates generated `config.toml`, managed MCP projection state, and provider credentials from host-side onboarding and OpenShell provider state during rebuild. +Before a Deep Agents rebuild changes the sandbox, NemoClaw verifies the recorded inference route, provider, model, reasoning settings, web search selection, base image, and policy inputs. +If a late check fails, NemoClaw restores the previous MCP state and keeps the existing sandbox intact. + + + +For full details, refer to the [Commands reference](../reference/commands). + + For full details, refer to the [Commands reference](../reference/commands). + + +For Deep Agents, the quickstart summarizes the managed state layout and the snapshot commands shown above cover normal backup and restore workflows. + ## Manual Backup @@ -137,6 +173,25 @@ openshell sandbox download "$SANDBOX" /sandbox/.hermes/state.db "$BACKUP_DIR/" openshell sandbox download "$SANDBOX" /sandbox/.hermes/platforms/ "$BACKUP_DIR/platforms/" ``` + + + +```bash +SANDBOX=my-deepagents +BACKUP_DIR=~/.nemoclaw/backups/$(date +%Y%m%d-%H%M%S) +mkdir -p "$BACKUP_DIR" + +openshell sandbox download "$SANDBOX" /sandbox/.deepagents/config.toml "$BACKUP_DIR/" +openshell sandbox download "$SANDBOX" /sandbox/.deepagents/agent/AGENTS.md "$BACKUP_DIR/agent/" +openshell sandbox download "$SANDBOX" /sandbox/.deepagents/agent/memories/ "$BACKUP_DIR/agent/memories/" +openshell sandbox download "$SANDBOX" /sandbox/.deepagents/skills/ "$BACKUP_DIR/skills/" +openshell sandbox download "$SANDBOX" /sandbox/.deepagents/agent/skills/ "$BACKUP_DIR/agent-skills/" +``` + +Do not recursively download `/sandbox/.deepagents/.state/`. +That directory can contain upstream credential state such as `auth.json` and `chatgpt-auth.json`, which can copy secrets to the host and restore state that the managed launcher refuses. +Use `$$nemoclaw snapshot create` when you need NemoClaw's built-in sanitizer for Deep Agents runtime state. + ## Manual Restore @@ -169,6 +224,22 @@ openshell sandbox upload "$SANDBOX" "$BACKUP_DIR/state.db" /sandbox/.hermes/ openshell sandbox upload "$SANDBOX" "$BACKUP_DIR/platforms/" /sandbox/.hermes/platforms/ ``` + + + +```bash +SANDBOX=my-deepagents +BACKUP_DIR=~/.nemoclaw/backups/20260320-120000 # pick a timestamp + +openshell sandbox upload "$SANDBOX" "$BACKUP_DIR/agent/AGENTS.md" /sandbox/.deepagents/agent/ +openshell sandbox upload "$SANDBOX" "$BACKUP_DIR/agent/memories/" /sandbox/.deepagents/agent/memories/ +openshell sandbox upload "$SANDBOX" "$BACKUP_DIR/skills/" /sandbox/.deepagents/skills/ +openshell sandbox upload "$SANDBOX" "$BACKUP_DIR/agent-skills/" /sandbox/.deepagents/agent/skills/ +``` + +Do not upload saved `.deepagents/.state` contents during manual restore. +Restore safe Deep Agents files only, then run the managed rebuild or onboarding flow so NemoClaw regenerates route metadata, managed MCP projection state, and credential handling from host-side state. + ## Back Up All Running Sandboxes @@ -244,6 +315,15 @@ memory/ For Hermes, prefer the built-in snapshot commands for faithful restore of `state.db`. Use manual `openshell sandbox download` / `openshell sandbox upload` only when you need to inspect or transfer a specific file. + + + +For Deep Agents, prefer the built-in snapshot commands for normal rebuild and restore workflows. +Use manual `openshell sandbox download` / `openshell sandbox upload` only when you need to inspect or transfer a specific safe file or directory. +Treat downloaded `config.toml` as inspection context. +Do not upload an old `config.toml` over a rebuilt sandbox unless you are intentionally replacing NemoClaw's generated route metadata. +Never manually back up or restore `.deepagents/.state/auth.json` or `.deepagents/.state/chatgpt-auth.json`. + @@ -275,9 +355,35 @@ Hermes does not use OpenClaw per-agent workspace directories. NemoClaw snapshots preserve the Hermes manifest-defined state tree and durable top-level files instead. Refer to [Workspace Files](workspace-files) for the Hermes state layout. + + + +## Deep Agents State + +Deep Agents does not use OpenClaw per-agent workspace directories. +NemoClaw snapshots preserve the Deep Agents manifest-defined state tree under `/sandbox/.deepagents`. +Generated config and credential-bearing user files are handled by the managed rebuild path rather than ordinary snapshot restore. +If you rely on upstream memory files such as `/sandbox/.deepagents/agent/AGENTS.md` or `/sandbox/.deepagents/agent/memories/`, verify that your release includes them in the manifest-backed state set or copy them manually before destroying the sandbox. + ## Next Steps + + +- [Workspace Files overview](workspace-files) to learn what each file does. +- [Commands reference](../reference/commands). + + + + - [Workspace Files overview](workspace-files) to learn what each file does. - [Commands reference](../reference/commands). + + + + +- [Set Up MCP Servers](set-up-mcp-servers) explains managed MCP configuration for Deep Agents sandboxes. +- [Workspace Files](workspace-files) explains the managed Deep Agents state layout. + + diff --git a/docs/manage-sandboxes/lifecycle.mdx b/docs/manage-sandboxes/lifecycle.mdx index 551f3a5fcc..3aa8ae793c 100644 --- a/docs/manage-sandboxes/lifecycle.mdx +++ b/docs/manage-sandboxes/lifecycle.mdx @@ -3,9 +3,9 @@ # SPDX-License-Identifier: Apache-2.0 title: "Manage Sandbox Lifecycle" sidebar-title: "Manage Sandbox Lifecycle" -description: "List sandboxes, check health, inspect logs, manage dashboard ports, reconfigure providers, rebuild safely, upgrade sandboxes, and uninstall NemoClaw." -description-agent: "Explains operational tasks after the quickstart: listing sandboxes, status and health checks, logs, diagnostics, port forwards, multiple sandboxes, credential reset, rebuilds, network presets, upgrades, and uninstall." -keywords: ["manage nemoclaw sandboxes", "nemoclaw status", "nemoclaw list", "nemoclaw dashboard port", "nemoclaw rebuild", "nemoclaw upgrade sandboxes", "nemoclaw uninstall"] +description: "List sandboxes, check health, inspect logs, reconfigure providers, rebuild safely, upgrade sandboxes, and uninstall NemoClaw." +description-agent: "Explains operational tasks after the quickstart: listing sandboxes, status and health checks, logs, diagnostics, port forwards when present, multiple sandboxes, credential reset, rebuilds, network presets, upgrades, and uninstall." +keywords: ["manage nemoclaw sandboxes", "nemoclaw status", "nemoclaw list", "nemoclaw rebuild", "nemoclaw upgrade sandboxes", "nemoclaw uninstall"] content: type: "how_to" skill: @@ -19,6 +19,9 @@ Use this guide after you finish the [OpenClaw quickstart](../get-started/quickst Use this guide after you finish [Quickstart with Hermes](../get-started/quickstart). + +Use this guide after you finish [Quickstart with Deep Agents](../get-started/quickstart). + It covers ongoing sandbox operations such as listing sandboxes, checking health, managing ports, rebuilding safely, upgrading, and uninstalling. When a workflow uses the lower-level OpenShell CLI, refer to [CLI Selection Guide](../reference/cli-selection-guide) for the boundary between `$$nemoclaw` and `openshell`. @@ -26,6 +29,9 @@ When a workflow uses the lower-level OpenShell CLI, refer to [CLI Selection Guid When a workflow uses the lower-level OpenShell CLI, refer to [CLI Selection Guide](../reference/cli-selection-guide) for the boundary between `$$nemoclaw`, `nemoclaw`, and `openshell`. + +When a workflow uses the lower-level OpenShell CLI, refer to [CLI Selection Guide](../reference/cli-selection-guide) for the boundary between `$$nemoclaw`, `nemo-deepagents`, and `openshell`. + ## List Sandboxes @@ -35,7 +41,10 @@ List every sandbox registered on this host: $$nemoclaw list ``` -The list shows each sandbox's model, provider, policy presets, active SSH session indicator, and dashboard URL when NemoClaw records a dashboard port. +The list shows each sandbox's model, provider, policy presets, and active SSH session indicator. + +It also shows the dashboard URL when NemoClaw records a dashboard port. + Use JSON output for scripts: ```bash @@ -44,7 +53,10 @@ $$nemoclaw list --json ## Check Sandbox Health -Check a specific sandbox's health, inference route, active connections, live policy, update status, and messaging-channel overlap warnings: +Check a specific sandbox's health, inference route, active connections, live policy, and update status: + +For messaging agents, the command also reports messaging-channel overlap warnings. + ```bash $$nemoclaw my-assistant status @@ -76,6 +88,9 @@ The log command reads both OpenClaw gateway output and OpenShell audit events, s The log command reads both Hermes gateway output and OpenShell audit events, so policy denials appear beside gateway logs. + +The log command reads Deep Agents sandbox output and OpenShell audit events, so policy denials appear beside terminal-runtime logs. + ## Collect Diagnostics @@ -91,7 +106,9 @@ Use `--quick` for a smaller local summary: $$nemoclaw debug --quick --sandbox my-assistant ``` -The debug command gathers system information, Docker state, gateway logs, and sandbox status. +The debug command gathers system information, Docker state, sandbox logs, and sandbox status. + + ## Manage Dashboard Ports @@ -107,25 +124,56 @@ To list active forwards across all sandboxes, run the following command. openshell forward list ``` + + ## Run Multiple Sandboxes + Each sandbox needs its own dashboard port because `openshell forward` refuses to bind a port that another sandbox already uses. + + +Deep Agents sandboxes do not expose a dashboard port. +The first `nemo-deepagents onboard` run can use the default sandbox name from the wizard. +When you create another Deep Agents sandbox, choose a distinct sandbox name in the wizard or pass `--name` in scripted runs. + When the default port is already held by another sandbox, `$$nemoclaw onboard` scans ports `18789` through `18799` and uses the next free port. When the default API port is already held by another sandbox, `$$nemoclaw onboard` scans for the next free port and records it for the sandbox. + If you intentionally run separate OpenShell gateways on the same host, set a different `NEMOCLAW_GATEWAY_PORT` before each onboarding run. NemoClaw isolates the gateway name and local state by port so one port-specific gateway does not replace another. Gateway and dashboard cleanup is scoped by sandbox name and port. A later onboarding run that uses a different `NEMOCLAW_GATEWAY_PORT` or `--control-ui-port` does not tear down the first sandbox's gateway or dashboard forward. + + +If you intentionally run separate OpenShell gateways on the same host, set a different `NEMOCLAW_GATEWAY_PORT` before each onboarding run. +NemoClaw isolates the gateway name and local state by port so one port-specific gateway does not replace another. +Gateway cleanup is scoped by sandbox name and port. + + + ```bash $$nemoclaw onboard # first sandbox uses 18789 $$nemoclaw onboard # second sandbox uses the next free port, such as 18790 ``` + + + +```bash +nemo-deepagents onboard +# For an additional named sandbox: +nemo-deepagents onboard --name +``` + + + + + To choose a specific port, pass `--control-ui-port`: ```bash @@ -141,28 +189,61 @@ NEMOCLAW_DASHBOARD_PORT=19000 $$nemoclaw onboard For full details on port conflicts and overrides, refer to [Port already in use](../reference/troubleshooting#port-already-in-use). + + ## Reconfigure or Recover Recover from a misconfigured sandbox without re-running the full onboard wizard or destroying workspace state. ### Change Inference Model or API + Change the active model or provider at runtime without rebuilding the sandbox: ```bash $$nemoclaw inference set --model --provider ``` + + +For Deep Agents, recreate the sandbox when you change the provider or model so `/sandbox/.deepagents/config.toml` and the OpenShell route stay aligned: + +```bash +nemo-deepagents onboard --fresh --name --recreate-sandbox +``` + + Refer to [Switch Inference Providers](../inference/switch-inference-providers) for provider-specific model IDs and API compatibility notes. ### Restart the Gateway and Port Forward If `$$nemoclaw status` reports the sandbox is alive but the gateway is not running, run the recover command instead of opening a shell. + +```bash +$$nemoclaw recover +``` + +The command repairs a stopped in-sandbox gateway and re-establishes the dashboard port-forward in one step. +It is idempotent and safe to script. +If the gateway is already healthy, `recover` exits after the probe and does not restart it. +For built-in OpenClaw sandboxes, recovery sends an authenticated request through registry-scoped privileged direct-container control. +The request reaches either the root PID 1 supervisor in a direct root-entrypoint container or the installed root controller in an OpenShell-managed container. +It does not fall back to ordinary `openshell sandbox exec` or a manual relaunch inside the sandbox. +Refer to [`$$nemoclaw recover`](../reference/commands#$$nemoclaw-name-recover) for details. + +Use `gateway restart` when you intentionally need a supported OpenClaw gateway to reload runtime configuration or plugins. + +```bash +$$nemoclaw gateway restart +``` + +The restart command asks the topology-specific controller to stop the tracked gateway child, wait for the entrypoint to launch a replacement, and prove listener and HTTP health. +The host then checks or recovers host-side dashboard, messaging, and agent forwards. +Refer to [`$$nemoclaw gateway restart`](../reference/commands#$$nemoclaw-name-gateway-restart) for details. If `$$nemoclaw status` reports the sandbox is alive but the Hermes gateway is not running, run the recover command instead of opening a shell. - ```bash $$nemoclaw recover @@ -171,12 +252,12 @@ $$nemoclaw recover The command repairs a stopped in-sandbox gateway and re-establishes the dashboard port-forward in one step. It is idempotent and safe to script. If the gateway is already healthy, `recover` exits after the probe and does not restart it. -For built-in OpenClaw and Hermes sandboxes, recovery sends an authenticated request through registry-scoped privileged direct-container control. +For built-in Hermes sandboxes, recovery sends an authenticated request through registry-scoped privileged direct-container control. The request reaches either the root PID 1 supervisor in a direct root-entrypoint container or the installed root controller in an OpenShell-managed container. It does not fall back to ordinary `openshell sandbox exec` or a manual relaunch inside the sandbox. Refer to [`$$nemoclaw recover`](../reference/commands#$$nemoclaw-name-recover) for details. -Use `gateway restart` when you intentionally need a supported OpenClaw or Hermes gateway to reload runtime configuration or plugins. +Use `gateway restart` when you intentionally need a supported Hermes gateway to reload runtime configuration or plugins. ```bash $$nemoclaw gateway restart @@ -188,7 +269,8 @@ For Hermes, the entrypoint supervisor owns the gateway, dashboard process, inter The nonroot managed supervisor repairs those processes continuously, stops an alive but deaf gateway after four consecutive failed health checks, and quarantines relaunch after five exits within 60 seconds until sandbox recreation. The host does not start the in-sandbox processes independently. Refer to [`$$nemoclaw gateway restart`](../reference/commands#$$nemoclaw-name-gateway-restart) for details. - + + In the direct root-entrypoint topology, the gateway uses a separate `gateway` UID and restart receives the root-only seal. In the OpenShell-managed topology, OpenShell is PID 1 and nonroot `nemoclaw-start`, the gateway, and the agent use the same sandbox UID. The installed root controller validates the stable process shape, targets the exact observed child with a pidfd, preflights config, and proves replacement health. @@ -201,6 +283,13 @@ If a direct-container sandbox uses an older image without the matching superviso $$nemoclaw rebuild --yes ``` + + +Deep Agents sandboxes are terminal runtimes and do not expose an OpenClaw or Hermes in-sandbox gateway. +Use `nemo-deepagents status`, `logs`, `connect`, and `rebuild` for recovery. +If the terminal runtime reports degraded health, rebuild the sandbox instead of using `recover` or `gateway restart`. + + ### Reset a Stored Credential If you entered a provider credential incorrectly during onboarding, clear the gateway-registered value and re-enter it on the next onboard run: @@ -221,12 +310,23 @@ If you changed the underlying Dockerfile, upgraded OpenClaw, or want to pick up If you changed the underlying Dockerfile, upgraded Hermes, or want to pick up a new base image without losing your sandbox's state files, use `rebuild` instead of destroying and recreating: + +If you changed the underlying Dockerfile, upgraded Deep Agents Code, enabled Tavily Search, or want to pick up a new base image without losing manifest-defined Deep Agents state, use `rebuild` instead of destroying and recreating: + ```bash $$nemoclaw rebuild ``` + The rebuild command preserves the mounted workspace and registered policies while recreating the container. + + +The rebuild command preserves Hermes state and registered policies while recreating the container. + + +The rebuild command preserves manifest-defined Deep Agents state, regenerates `config.toml`, reconstructs managed MCP projection state, and reapplies registered policies while recreating the container. + If NemoClaw cannot archive any requested state path, it reports the backup failure and stops before deleting the original sandbox. When rebuild starts with shields up, NemoClaw opens a 30-minute shields-down window for backup and recreation. A detached auto-lock timer remains the recovery authority until NemoClaw commits a successful shields-up state, including when the host rebuild process exits unexpectedly. @@ -335,7 +435,19 @@ Refer to [`$$nemoclaw uninstall` vs. the hosted `uninstall.sh`](../reference/com ## Related Topics + + - [Set Up Messaging Channels](messaging-channels) to connect Telegram, Discord, or Slack. - [Workspace Files](workspace-files) for persistent OpenClaw files inside the sandbox. - [Backup and Restore](backup-restore) for snapshot and restore workflows. - [Monitor Sandbox Activity](../monitoring/monitor-sandbox-activity) for observability tools. + + + + +- [Workspace Files](workspace-files) for Deep Agents state, skills, memory, and managed config files. +- [Backup and Restore](backup-restore) for snapshot and restore workflows. +- [Set Up MCP Servers](set-up-mcp-servers) for managed MCP configuration. +- [Commands reference](../reference/commands) for lifecycle command flags. + + diff --git a/docs/manage-sandboxes/workspace-files.mdx b/docs/manage-sandboxes/workspace-files.mdx index 7ed1d3b9fb..cdc2d5b329 100644 --- a/docs/manage-sandboxes/workspace-files.mdx +++ b/docs/manage-sandboxes/workspace-files.mdx @@ -1,11 +1,11 @@ --- # SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. # SPDX-License-Identifier: Apache-2.0 -title: "Workspace Files" +title: "Workspace and State Files" sidebar-title: "Workspace Files" -description: "What workspace personality and configuration files are, where they live, and how they persist across sandbox restarts." -description-agent: "Explains what workspace personality and configuration files are, where they live, and how they persist across sandbox restarts. Use when users ask about `SOUL.md`, `USER.md`, `IDENTITY.md`, `AGENTS.md`, or other workspace files, or when preparing to back up or restore workspace state." -keywords: ["nemoclaw workspace files", "soul.md", "user.md", "identity.md", "agents.md", "sandbox persistence"] +description: "What agent workspace and state files are, where they live, and how they persist across sandbox restarts." +description-agent: "Explains what agent workspace and state files are, where they live, and how they persist across sandbox restarts. Use when users ask about OpenClaw workspace files, Hermes state, Deep Agents `.deepagents` files, or preparing to back up or restore sandbox state." +keywords: ["nemoclaw workspace files", "deepagents state", "soul.md", "agents.md", "sandbox persistence"] content: type: "concept" --- @@ -149,3 +149,76 @@ Use `$$nemoclaw connect` when you need to inspect runtime files interacti - [Commands reference](../reference/commands) + + +Deep Agents Code stores durable agent configuration, memory, skills, MCP state, and conversation state under its home directory. +In a NemoClaw sandbox, `dcode` runs with `HOME=/sandbox`, so the upstream `~/.deepagents` layout maps to `/sandbox/.deepagents`. +For upstream behavior, refer to the official Deep Agents Code pages for [memory and skills](https://docs.langchain.com/oss/python/deepagents/code/memory-and-skills), [MCP tools](https://docs.langchain.com/oss/python/deepagents/code/mcp-tools), and [Deep Agents Code overview](https://docs.langchain.com/oss/python/deepagents/code/overview). + +## Important Deep Agents State + +| Path | Purpose | +|---|---| +| `/sandbox/.deepagents/config.toml` | NemoClaw-generated model and provider configuration for the managed `inference.local` route. | +| `/sandbox/.deepagents/.state/` | Deep Agents Code runtime state, including persisted session and MCP-related state. | +| `/sandbox/.deepagents/agent/AGENTS.md` | Global memory file for the default Deep Agents Code agent, loaded at session start. | +| `/sandbox/.deepagents/agent/memories/` | Topic-specific markdown memories that Deep Agents Code can read and update across sessions. | +| `/sandbox/.deepagents/skills/` | User-level skills available to Deep Agents Code in the sandbox. | +| `/sandbox/.deepagents/agent/skills/` | Default-agent skills created by the built-in skill creator and preserved by NemoClaw snapshots. | +| `/sandbox/.deepagents/.nemoclaw-mcp.json` | NemoClaw-generated managed MCP projection with OpenShell credential placeholders. NemoClaw reconstructs it from host-side registry state. | +| `/sandbox/.deepagents/.state/auth.json` | Upstream auth state. The managed launchers refuse to start when this file contains credentials. | +| `/sandbox/.deepagents/.state/chatgpt-auth.json` | Upstream ChatGPT auth state. The managed launchers refuse to start when this file exists. | +| `/sandbox/.deepagents/.env` | User-managed Deep Agents Code environment file. NemoClaw treats it as credential-bearing and does not snapshot it. | +| `/sandbox/.deepagents/.mcp.json` | User-authored Deep Agents Code MCP config. NemoClaw treats it as credential-bearing and does not snapshot it. | + +Project-level Deep Agents files can also exist inside the working repository, such as `.deepagents/AGENTS.md`, `.deepagents/skills/`, and `.deepagents/.mcp.json`. +Those files are ordinary project files. +They persist when they live under your sandbox workspace, but NemoClaw's Deep Agents manifest only declares `/sandbox/.deepagents` state for the managed agent home. + +## Persistence Behavior + +Deep Agents state lives in the sandbox's persistent state volume, not in the container image alone. +Normal restarts preserve that state. +Rebuilds and upgrades use NemoClaw's snapshot flow to preserve the manifest-defined Deep Agents state tree. + +The Deep Agents manifest declares these durable directories: + +```text +/sandbox/.deepagents/.state/ +/sandbox/.deepagents/skills/ +/sandbox/.deepagents/agent/skills/ +``` + +It also declares `/sandbox/.deepagents/config.toml` as a durable top-level state file because the file contains non-secret NemoClaw-generated provider and model configuration. +Credential-bearing files such as `.deepagents/.env` and user-authored `.deepagents/.mcp.json` are intentionally omitted from snapshots. +Managed MCP state is rebuilt from the host-side NemoClaw registry and OpenShell provider state instead of treated as user-authored durable state. +Memory files such as `/sandbox/.deepagents/agent/AGENTS.md` and `/sandbox/.deepagents/agent/memories/` are upstream Deep Agents Code files. +If you rely on them before they are manifest-backed in your release, copy them manually with `$$nemoclaw download` before destroying the sandbox. + +Running `$$nemoclaw destroy` deletes the sandbox and its persistent state volume. +Back up important Deep Agents state before destroying the sandbox. + +## Editing State + +Prefer NemoClaw host commands for generated configuration such as model, provider, managed MCP, and policy settings. +Direct edits to `/sandbox/.deepagents/config.toml` can be overwritten by rebuilds because NemoClaw owns the managed inference route. +Use `$$nemoclaw connect` when you need to inspect runtime files interactively, or use `openshell sandbox download` and `openshell sandbox upload` for manual file transfer. + +Use Deep Agents Code commands for upstream-managed memories and skills. +For example, run `dcode skills create ` inside the sandbox to create a user skill, or use `/remember` inside an interactive `dcode` session to update memory. +NemoClaw preserves the manifest-declared skills and state directories, but it does not inspect or validate the content of user-authored memory and skill files beyond the snapshot safety checks. + +## Python Environment + +Deep Agents Code runs from a NemoClaw-managed Python virtual environment at `/opt/venv`. +The sandbox places `/opt/venv/bin` before system Python directories on `PATH`, so `python3` and `pip3` resolve to the managed environment by default. +NemoClaw keeps `/opt/venv` read-only to protect the pinned `dcode` harness. +Create project-specific virtual environments under `/sandbox` when a task needs additional Python packages. + +## Next Steps + +- [Backup and Restore workspace files](backup-restore) explains snapshot and manual transfer workflows. +- [Set Up MCP Servers](set-up-mcp-servers) explains the NemoClaw-managed MCP path for Deep Agents sandboxes. +- [Deep Agents Code memory and skills](https://docs.langchain.com/oss/python/deepagents/code/memory-and-skills) explains upstream memory, `AGENTS.md`, and skill behavior. + + diff --git a/docs/reference/architecture.mdx b/docs/reference/architecture.mdx index dc5c200ff3..3c115bf65c 100644 --- a/docs/reference/architecture.mdx +++ b/docs/reference/architecture.mdx @@ -9,6 +9,8 @@ keywords: ["nemoclaw architecture", "nemoclaw agent architecture", "nemoclaw plu content: type: "reference" --- +import { AgentOnly } from "../_components/AgentGuide"; + NemoClaw combines a host CLI, an in-sandbox integration layer, and a versioned YAML blueprint that defines the sandbox image, policies, and inference profiles applied through OpenShell. ## System Overview @@ -30,7 +32,7 @@ graph LR subgraph EXTERNAL["External Services"] INFERENCE["Inference Provider
NVIDIA Endpoints · OpenAI
Anthropic · Ollama · vLLM · Model Router"]:::external - MSGAPI["Messaging Platforms
Telegram · Discord · Slack"]:::external + INTEGRATIONS["Integration APIs
MCP · GitHub · package indexes"]:::external INTERNET["Internet
PyPI · npm · GitHub · APIs"]:::external end @@ -47,18 +49,18 @@ graph LR direction TB GW["Gateway
Credential store
Inference proxy
Policy engine
Device auth"]:::openshell OSCLI["openshell CLI
provider · sandbox
gateway · policy"]:::openshell - CHMSG["Channel messaging
OpenShell-managed
Telegram · Discord · Slack"]:::openshell + INTEG["Managed integrations
MCP · credentials · policy"]:::openshell subgraph SANDBOX["Sandbox Container 🔒"] direction TB - AGENT["Compatible Agent
OpenClaw, Hermes,
or another supported runtime"]:::agent + AGENT["Compatible Agent
Selected managed runtime"]:::agent PLUG["NemoClaw Integration
Managed configuration
and runtime context"]:::sandbox end end end USER -->|"$$nemoclaw onboard
$$nemoclaw connect"| NCLI - USER -->|"Chat messages"| MSGAPI + USER -->|"Tasks and approvals"| NCLI NCLI -->|"Orchestrates"| OSCLI BP -->|"Defines sandbox
shape + policies"| SANDBOX @@ -67,8 +69,8 @@ graph LR AGENT -->|"Inference requests
no credentials"| GW GW -->|"Proxied with
credential injected"| INFERENCE - MSGAPI -->|"Platform APIs"| CHMSG - CHMSG -->|"Deliver to agent"| AGENT + INTEGRATIONS -->|"External APIs"| INTEG + INTEG -->|"Policy-gated access"| AGENT AGENT -.->|"Policy-gated"| INTERNET GW -.->|"Enforced by
gateway"| INTERNET @@ -85,8 +87,9 @@ Per-user units, partial units, and user-manager or bus outages do not take over That compatibility fallback remains until supported upgrade paths no longer include pre-service OpenShell installs and the package-managed handoff has direct nightly coverage. On Apple Silicon macOS, NemoClaw starts the OpenShell Docker-driver gateway and creates the sandbox as a Docker container. In both Docker-driver modes, the sandbox is a Docker container, not a Kubernetes pod. -The in-container `/tmp/nemoclaw-gateway-local` marker is written only by the entrypoint path that actually launches `openclaw gateway run`; -NemoClaw does not treat sandbox environment hints such as `OPENSHELL_DRIVERS` as authoritative for dashboard-gateway ownership. +The in-container `/tmp/nemoclaw-gateway-local` marker is written only by entrypoint paths that actually launch an in-container gateway. +Terminal runtimes may not write it. +NemoClaw does not treat sandbox environment hints such as `OPENSHELL_DRIVERS` as authoritative for gateway ownership. Legacy non-Docker-driver installs still use the k3s-based gateway path; the diagram below shows the standard Docker-driver topology. ```mermaid @@ -146,9 +149,17 @@ The concrete files differ by agent because each runtime has its own plugin syste | Agent | Integration files | Runtime behavior | |---|---|---| + | OpenClaw | `nemoclaw/openclaw.plugin.json`, `nemoclaw/src/runtime-context.ts`, and the TypeScript package under `nemoclaw/src/` | Registers the `/nemoclaw` slash command, adds the NemoClaw inference provider, and injects sandbox and policy context into OpenClaw turns. | + + | Hermes | `agents/hermes/manifest.yaml`, `agents/hermes/plugin/plugin.yaml`, `agents/hermes/generate-config.ts`, `agents/hermes/config/`, and `agents/hermes/start.sh` | Declares the Hermes agent contract, installs the NemoClaw Hermes plugin, writes `/sandbox/.hermes/config.yaml` and `/sandbox/.hermes/.env`, and launches `hermes gateway run` behind the OpenShell proxy. | + + +| Deep Agents | `agents/langchain-deepagents-code/manifest.yaml`, `agents/langchain-deepagents-code/generate-config.ts`, `agents/langchain-deepagents-code/start.sh`, and the managed `dcode` launchers | Declares the terminal agent contract, writes `/sandbox/.deepagents/config.toml`, installs managed wrappers for `dcode` and `dcode -n`, and routes inference through `inference.local`. | + + The OpenClaw integration is a thin TypeScript plugin that runs in-process with the OpenClaw gateway inside the sandbox. Its durable entry points are `nemoclaw/src/index.ts`, `nemoclaw/src/runtime-context.ts`, and `nemoclaw/openclaw.plugin.json`. The `nemoclaw/src/commands/` directory contains in-sandbox `/nemoclaw` command handlers and migration helpers. @@ -157,11 +168,19 @@ Before an OpenClaw turn starts, the plugin prepends a short system-context block This guidance stays out of the visible chat transcript. When the policy or phase changes during a session, the plugin sends a smaller update block instead of repeating the full context. The context tells the agent to try allowed network and filesystem operations before reporting them unavailable, and to distinguish policy denials from DNS, timeout, TLS, or filesystem errors. + + The Hermes integration follows the generic agent-manifest path instead of the OpenClaw plugin package path. The manifest declares Hermes' binary, health probe, config directory, state directories, and OpenAI-compatible API endpoint. Messaging channel availability is declared by each channel manifest's `supportedAgents` list under `src/lib/messaging/channels/`, not by the Hermes agent manifest. The build-time config generator turns NemoClaw onboarding choices into Hermes YAML and environment files, and the Hermes plugin manifest exposes NemoClaw tools and an `on_session_start` hook. + + +The Deep Agents integration follows the generic agent-manifest path for terminal runtimes. +The manifest declares the `dcode` binary, smoke checks, config directory, state directories, and OpenAI-compatible inference route. +The build-time config generator turns NemoClaw onboarding choices into `config.toml`, and the managed launchers enforce the supported credential, MCP, tracing, and sandbox boundaries before `dcode` starts. + ## NemoClaw Blueprint @@ -175,11 +194,20 @@ nemoclaw-blueprint/ ├── model-specific-setup/ Agent-scoped model/provider compatibility manifests ├── router/ Model Router config and routing engine ├── policies/ -│ └── openclaw-sandbox.yaml Default network + filesystem policy for the OpenClaw profile +│ └── presets/ Shared policy presets ``` + +The default OpenClaw policy starts from `nemoclaw-blueprint/policies/openclaw-sandbox.yaml`. + + Hermes keeps its agent-owned image, plugin, config, entrypoint, and policy additions under `agents/hermes/`. The default Hermes policy starts from `agents/hermes/policy-additions.yaml`. + + +Deep Agents keeps its agent-owned image, config generator, entrypoint, wrappers, and policy additions under `agents/langchain-deepagents-code/`. +The default Deep Agents policy starts from `agents/langchain-deepagents-code/policy-additions.yaml`. + The current blueprint runner implementation lives in the `nemoclaw/` TypeScript package: @@ -210,17 +238,37 @@ flowchart LR ## Sandbox Environment + Normal NemoClaw onboarding builds from the [`ghcr.io/nvidia/nemoclaw/sandbox-base`](https://github.com/NVIDIA/NemoClaw/pkgs/container/nemoclaw%2Fsandbox-base) base image and layers the NemoClaw runtime Dockerfile on top. + + +Deep Agents onboarding builds from the agent-specific `agents/langchain-deepagents-code/Dockerfile.base` image and layers the managed Deep Agents runtime Dockerfile on top. +That base installs Node, Python, shell tools, and the hash-locked `deepagents-code` package needed by the terminal harness. + + The direct blueprint runner still carries a pinned OpenShell Community OpenClaw image for legacy `openshell sandbox create --from` compatibility. + Inside the sandbox: - The selected compatible agent runs with the NemoClaw integration layer installed or generated for that agent. - Inference calls are routed through OpenShell to the configured provider. - Network egress is restricted by the baseline policy for the selected agent profile. - Filesystem access is confined to `/sandbox` and `/tmp` for read-write access, with system paths read-only. + - NemoClaw injects sandbox and policy context into agent turns when the selected agent supports runtime context hooks, so the agent can attempt allowed actions and report policy blocks or infrastructure failures accurately. - The image exposes a Docker health check that probes the in-sandbox gateway, so container runtimes can report whether the agent service is responding. + + +- NemoClaw writes generated Hermes configuration into the sandbox, then the Hermes runtime exposes its own gateway and health surface. +- The image exposes health checks for the managed Hermes runtime. + + +- NemoClaw writes generated Deep Agents configuration into the sandbox, then leaves interactive and headless execution to `dcode`. +- Deep Agents is a terminal runtime, so there is no long-running dashboard or gateway health surface inside the sandbox. + + - The image includes common runtime compatibility helpers such as Homebrew and a `python` to `python3` symlink for tools that still invoke `python`. + ## Inference Routing @@ -253,12 +301,15 @@ NemoClaw keeps non-secret operator-facing state on the host rather than inside t | Path | Purpose | |---|---| | `~/.nemoclaw/sandboxes.json` | Registered sandbox metadata, including the default sandbox selection. | + | `~/.openclaw/openclaw.json` | Host OpenClaw configuration that NemoClaw snapshots or restores during migration flows. | + The following environment variables configure optional services and local access. | Variable | Purpose | |---|---| + | `TELEGRAM_BOT_TOKEN` | Telegram bot token you provide before `$$nemoclaw onboard`. OpenShell stores it in a provider; the sandbox receives placeholders, not the raw secret. | | `TELEGRAM_ALLOWED_IDS` | Comma-separated Telegram user or chat IDs for allowlists when onboarding applies channel restrictions. | | `TELEGRAM_GROUP_POLICY` | OpenClaw Telegram group access policy: `open` by default, `allowlist` to require explicit group entries, or `disabled` to turn off OpenClaw group access. Hermes ignores this value. | @@ -268,6 +319,22 @@ The following environment variables configure optional services and local access | `SLACK_ALLOWED_CHANNELS` | Comma-separated Slack channel IDs where channel `@mention` events are enabled (e.g. `C012AB3CD,C987ZY6XW`). Baked into the sandbox image at build time. Combine with `SLACK_ALLOWED_USERS` to restrict both channel and member. | | `CHAT_UI_URL` | URL for the optional chat UI endpoint. | | `NEMOCLAW_DISABLE_DEVICE_AUTH` | Build-time-only toggle that disables gateway device pairing when set to `1` before the sandbox image is created. | + + +| `TELEGRAM_BOT_TOKEN` | Telegram bot token you provide before `$$nemoclaw onboard`. OpenShell stores it in a provider; the sandbox receives placeholders, not the raw secret. | +| `TELEGRAM_ALLOWED_IDS` | Comma-separated Telegram user or chat IDs for allowlists when onboarding applies channel restrictions. | +| `SLACK_BOT_TOKEN` | Slack bot token (`xoxb-...`) you provide before `$$nemoclaw onboard`. Stored as an OpenShell provider; never passed directly to the sandbox. | +| `SLACK_APP_TOKEN` | Slack app-level token (`xapp-...`) required for Socket Mode. Stored alongside `SLACK_BOT_TOKEN` during onboarding. | +| `SLACK_ALLOWED_USERS` | Comma-separated Slack member IDs for DM and channel `@mention` user allowlisting. | +| `SLACK_ALLOWED_CHANNELS` | Comma-separated Slack channel IDs where channel `@mention` events are enabled (e.g. `C012AB3CD,C987ZY6XW`). Baked into the sandbox image at build time. Combine with `SLACK_ALLOWED_USERS` to restrict both channel and member. | + + +| `NEMOCLAW_POLICY_TIER` | Optional non-interactive policy tier selection during onboarding. | +| `TAVILY_API_KEY` | Host-side input for the optional managed Tavily provider. Register it with `$$nemoclaw credentials add tavily-search --type tavily --credential TAVILY_API_KEY` before attaching the provider to Deep Agents. | +| `NEMOCLAW_GATEWAY_PORT` | Optional host-side gateway port override when running multiple independent OpenShell gateways. | + For normal setup and reconfiguration, prefer `$$nemoclaw onboard` over editing these files by hand. + Do not treat `NEMOCLAW_DISABLE_DEVICE_AUTH` as a runtime setting for an already-created sandbox. + diff --git a/docs/reference/cli-selection-guide.mdx b/docs/reference/cli-selection-guide.mdx index 158ed8e1e4..6be45cecf7 100644 --- a/docs/reference/cli-selection-guide.mdx +++ b/docs/reference/cli-selection-guide.mdx @@ -9,6 +9,8 @@ keywords: ["nemoclaw vs openshell", "which cli", "nemoclaw cli", "openshell cli" content: type: "reference" --- +import { AgentOnly } from "../_components/AgentGuide"; + NemoClaw uses two host-side CLIs. Use `$$nemoclaw` for NemoClaw-managed workflows. Use `openshell` when you need a lower-level OpenShell operation that NemoClaw intentionally leaves available. @@ -24,15 +26,18 @@ Run `$$nemoclaw onboard` afterward if you need to return to a NemoClaw-managed e ## Use `$$nemoclaw` For NemoClaw Workflows -Use `$$nemoclaw` for operations where NemoClaw adds product-specific state, safety checks, backup behavior, credential handling, or OpenClaw configuration. +Use `$$nemoclaw` for operations where NemoClaw adds product-specific state, safety checks, backup behavior, credential handling, or agent configuration. - Install, onboard, or recreate a NemoClaw sandbox: ```bash $$nemoclaw onboard - $$nemoclaw onboard --resume --recreate-sandbox + $$nemoclaw onboard --fresh --name --recreate-sandbox ``` +Use `--resume` only when you are recovering an interrupted onboarding session. +For a completed sandbox, use `--fresh --name --recreate-sandbox` when you need NemoClaw to recreate it. + - List, connect to, check, or delete NemoClaw-managed sandboxes: ```bash @@ -66,16 +71,34 @@ Use `$$nemoclaw` for operations where NemoClaw adds product-specific state, safe $$nemoclaw my-assistant policy-remove pypi --yes ``` -- Manage NemoClaw messaging channels, credentials, diagnostics, and cleanup: +- Manage NemoClaw credentials, diagnostics, and cleanup: ```bash - $$nemoclaw my-assistant channels add slack $$nemoclaw credentials list $$nemoclaw credentials reset nvidia-prod $$nemoclaw debug --sandbox my-assistant $$nemoclaw gc --dry-run ``` + + +- Manage NemoClaw messaging channels: + + ```bash + $$nemoclaw my-assistant channels add slack + ``` + + + + +- Manage NemoClaw messaging channels: + + ```bash + $$nemoclaw my-assistant channels add slack + ``` + + + ## Use `openshell` For OpenShell Operations Use `openshell` when the docs explicitly call for a live OpenShell gateway operation or when you need a lower-level view beneath the NemoClaw wrapper. @@ -86,7 +109,7 @@ Use `openshell` when the docs explicitly call for a live OpenShell gateway opera openshell term ``` -- Manage dashboard or service port forwards: +- Manage service port forwards: ```bash openshell forward start --background @@ -154,10 +177,10 @@ This section covers common decisions when using the NemoClaw CLI and the OpenShe ### First Setup or Full Recreate Use `$$nemoclaw onboard`. -It starts the OpenShell gateway when needed, registers providers, builds the OpenClaw sandbox image, applies NemoClaw policy choices, and creates the sandbox. +It starts the OpenShell gateway when needed, registers providers, builds the selected agent sandbox image, applies NemoClaw policy choices, and creates the sandbox. Avoid running `openshell gateway start --recreate` or `openshell sandbox create` directly for NemoClaw-managed sandboxes. -Those commands do not update NemoClaw's registry, session metadata, workspace-preservation flow, or OpenClaw-specific configuration. +Those commands do not update NemoClaw's registry, session metadata, workspace-preservation flow, or agent-specific configuration. ### Connect to the Sandbox @@ -183,7 +206,7 @@ openshell sandbox exec -n my-assistant -- cat /tmp/gateway.log ### Check Health or Logs Use `$$nemoclaw status` and `$$nemoclaw logs` first. -They combine NemoClaw registry data, OpenShell state, OpenClaw process health, inference health, policy details, and messaging-channel warnings for that sandbox. +They combine NemoClaw registry data, OpenShell state, selected agent process health, inference health, policy details, and messaging-channel warnings for that sandbox. Use `$$nemoclaw status` only for the global all-sandbox and host-service overview. Use `openshell sandbox list`, `openshell sandbox get`, `openshell logs -n 20`, or `openshell doctor check` when debugging lower-level OpenShell behavior. @@ -198,6 +221,18 @@ Approved endpoints are session-scoped unless you also add them to the policy thr ### Change Models or Providers + + +Use the NemoClaw commands for model or provider inspection and switches so the OpenShell route and the running agent config stay consistent: + +```bash +$$nemoclaw inference get +$$nemoclaw inference set --provider nvidia-prod --model nvidia/nemotron-3-super-120b-a12b +``` + + + + Use the NemoClaw commands for model or provider inspection and switches so the OpenShell route and the running agent config stay consistent: ```bash @@ -211,10 +246,21 @@ For Hermes sandboxes, use the alias; it updates the route and `/sandbox/.hermes/ nemohermes inference set --provider hermes-provider --model openai/gpt-5.4-mini ``` + + + +For Deep Agents sandboxes, prefer a fresh recreate when you need to change the provider or model. +The managed `dcode` configuration is written under `/sandbox/.deepagents` during onboarding, so the recreate path keeps the OpenShell route and the sandbox config aligned while the Deep Agents runtime switch path is still being hardened. + +```bash +nemo-deepagents onboard --fresh --name --recreate-sandbox +``` + + For a build-time agent setting change, rerun onboarding so the sandbox configuration is recreated consistently: ```bash -$$nemoclaw onboard --resume --recreate-sandbox +$$nemoclaw onboard --fresh --name --recreate-sandbox ``` Verify either path with: @@ -240,8 +286,30 @@ Use `openshell sandbox upload` and `openshell sandbox download` for manual file ## Related Topics + + - [Commands](commands) for the full NemoClaw command reference. - [Manage Sandbox Lifecycle](../manage-sandboxes/lifecycle) for day-two operations. - [Switch Inference Models](../inference/switch-inference-providers) for inference route examples. - [Customize the Network Policy](../network-policy/customize-network-policy) for persistent network access changes. - [Approve or Deny Network Requests](../network-policy/approve-network-requests) for the OpenShell TUI approval flow. + + + + +- [Commands](commands) for the full NemoClaw command reference. +- [Manage Sandbox Lifecycle](../manage-sandboxes/lifecycle) for day-two operations. +- [Switch Inference Models](../inference/switch-inference-providers) for inference route examples. +- [Customize the Network Policy](../network-policy/customize-network-policy) for persistent network access changes. +- [Approve or Deny Network Requests](../network-policy/approve-network-requests) for the OpenShell TUI approval flow. + + + + +- [Commands](commands) for the full NemoDeepAgents command reference. +- [Network Policies](network-policies) for baseline policy and approval behavior. +- [Workspace Files](../manage-sandboxes/workspace-files) for Deep Agents state and file transfer guidance. +- [Backup and Restore](../manage-sandboxes/backup-restore) for snapshot and restore workflows. +- [Inference Options](../inference/inference-options) for provider configuration details. + + diff --git a/docs/reference/commands-nemohermes.mdx b/docs/reference/commands-nemohermes.mdx deleted file mode 100644 index bf973a54ca..0000000000 --- a/docs/reference/commands-nemohermes.mdx +++ /dev/null @@ -1,2432 +0,0 @@ ---- -# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. -# SPDX-License-Identifier: Apache-2.0 -title: "NemoHermes CLI Commands Reference" -sidebar-title: "Commands" -description: "Full CLI reference for standalone NemoHermes commands and Hermes-specific in-sandbox commands." -description-agent: "Includes the full CLI reference for standalone NemoHermes commands and Hermes-specific in-sandbox commands. Use when looking up a specific `nemohermes` subcommand, flag, argument, or exit code." -keywords: ["nemohermes cli commands", "hermes command reference", "nemohermes command reference"] -content: - type: "reference" -exclude-from-skills-gen: true ---- -{/* This file is generated from docs/reference/commands.mdx by scripts/sync-agent-variant-docs.ts. Run `npm run docs:sync-agent-variants` to regenerate it. Do not edit by hand. */} - -The `nemohermes` alias is the primary interface for managing Hermes sandboxes through NemoClaw. -It is installed automatically by the installer (`curl -fsSL https://www.nvidia.com/nemoclaw.sh | NEMOCLAW_AGENT=hermes bash`). -Most commands in this reference use the same arguments and subcommands across agent variants. -Use `nemohermes` when you want Hermes selected by default. -For guidance on choosing between the agent CLIs and the underlying `openshell` CLI, refer to [CLI Selection Guide](cli-selection-guide). - -## Agent Selection - -Use `nemohermes` for the Hermes variant. -It selects Hermes by default during onboarding and for other commands. -Use `--agent hermes` during onboarding or set `NEMOCLAW_AGENT=hermes` when you need the same selection through another entry point. -Hermes-specific sections below describe the built-in Hermes dashboard, the separate OpenAI-compatible API endpoint, Hermes config under `/sandbox/.hermes`, and provider updates that patch `config.yaml`. - -```bash -nemohermes onboard # selects Hermes by default -nemohermes my-sandbox connect # connects to a Hermes sandbox -``` - -## In-Sandbox Commands - -Hermes does not use the OpenClaw chat slash command. -Use the host-side `nemohermes` commands for lifecycle, status, policy, and inference operations. -The in-sandbox Hermes integration installs the NemoClaw Hermes plugin, which exposes tools for status, environment information, and skill reload support, plus an `on_session_start` hook. - -## Standalone Host Commands - -The CLI handles host-side operations that run outside the selected agent runtime. - -### `nemohermes help`, `nemohermes --help`, `nemohermes -h` - -Show the top-level usage summary and command groups. -Running `nemohermes` with no arguments shows the same help output. - -```bash -nemohermes help -``` - -### `nemohermes --version`, `nemohermes -v` - -Print the installed NemoClaw CLI version. - -```bash -nemohermes --version -``` - -### `nemohermes resources` - -Display host hardware inventory and configured sandbox resource profiles. -Use `--json` for machine-readable CPU, memory, GPU, Kubernetes allocatable-capacity, and profile data. - -```bash -nemohermes resources [--json] -``` - -If the gateway is not running, Kubernetes allocatable fields are omitted and host CPU/RAM totals are still shown. - -### `nemohermes agents list` - -List the installed agent runtimes that can be selected with `nemohermes onboard --agent `. -Use this global command when you need valid runtime names before creating or recreating a sandbox. -It lists runtime names with the descriptions from their installed manifests. - -```bash -nemohermes agents list -``` - -Expected output: - -```text -openclaw Gateway-based AI agent with plugin ecosystem (openclaw.ai) -hermes Self-improving AI agent with learning loop (Nous Research) -langchain-deepagents-code Terminal coding agent built on the Deep Agents SDK -``` - -### `nemohermes onboard` - -Run the interactive setup wizard (recommended for new installs). -The wizard creates an OpenShell gateway, registers inference providers, builds the sandbox image, and creates the sandbox. -Use this command for new installs and for recreating a sandbox after changes to policy or configuration. - -```bash -nemohermes onboard [--non-interactive] [--resume | --fresh] [--recreate-sandbox] [--gpu | --no-gpu] [--from ] [--name ] [--sandbox-gpu | --no-sandbox-gpu] [--sandbox-gpu-device ] [--agent ] [--agents ] [--tool-disclosure ] [--control-ui-port ] [--yes | -y] [--no-ollama-autostart] [--yes-i-accept-third-party-software] -``` - -For Hermes, use the alias or pass the agent explicitly: - -```bash -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. -Use `--resume` to continue a resumable onboarding session with the provider, model, sandbox name, agent, and custom Dockerfile path recorded by the original run. -During resume, NemoClaw reruns preflight, gateway, provider, and sandbox repair checks even when the saved session has already reached a later nonterminal onboarding phase. -If the recorded session conflicts with flags you pass on the recovery run, NemoClaw exits and tells you to either rerun with the original settings or start over. - -Use `--fresh` to discard the saved onboarding session and start the wizard from the beginning. -This clears stale or failed session state before NemoClaw creates a new session record. -It also bypasses locally recorded sandbox base-image resolution metadata and reruns normal candidate resolution. -`--fresh` takes precedence over a base-image hint carried from a rebuild, so NemoClaw does not use that recorded hint. -The installer also accepts `--fresh` and forwards it to `nemohermes onboard`, which skips automatic resume detection. -`--resume` and `--fresh` are mutually exclusive. - -#### `--tool-disclosure ` - -Choose how the selected agent presents its session-authorized tools to the model. -`progressive` is the default: OpenClaw and Hermes use their native Tool Search implementations, while Deep Agents Code initially shows its core tools plus `search_tools` after at least one MCP tool loads successfully. -`direct` restores the previous behavior and presents all registered tools directly. -This setting changes model context only; it does not bypass OpenShell policy, credentials, approvals, hooks, or sandbox controls. - -The flag takes precedence over `NEMOCLAW_TOOL_DISCLOSURE`. -A new sandbox defaults to `progressive` when neither is set. -NemoClaw records the selected value with the onboarding session and sandbox so rebuilds preserve it and ambient shell variables cannot silently change an internal rebuild. -Model-specific compatibility safeguards may downgrade a selected `progressive` mode to direct exposure for that model without changing the recorded preference. -To change an existing sandbox, recreate it explicitly: - -```bash -nemohermes onboard --name my-assistant --recreate-sandbox --tool-disclosure direct -``` - -Without an explicit flag or environment value, recreation preserves the recorded setting and only falls back to `progressive` for legacy state. -Resuming an interrupted session with a different explicit setting fails with a conflict instead of changing behavior mid-session. - -When Docker exposes the required identity metadata, NemoClaw records the base-image resolution on managed OpenClaw and Hermes sandbox images. -During a warm recreate or rebuild, it validates the local image identity and platform, plus the exact repository digest for a published image and any active OpenShell ABI requirement, before reusing it. -A valid match avoids candidate discovery and a network pull. -Set `NEMOCLAW_SANDBOX_BASE_IMAGE_REFRESH=1` to bypass the recorded hint without changing onboarding session handling: - -```bash -NEMOCLAW_SANDBOX_BASE_IMAGE_REFRESH=1 nemohermes onboard --recreate-sandbox -NEMOCLAW_SANDBOX_BASE_IMAGE_REFRESH=1 nemohermes rebuild -``` - -Base-image selection follows this precedence: - -1. `--fresh` or `NEMOCLAW_SANDBOX_BASE_IMAGE_REFRESH=1` bypasses recorded metadata and reruns normal candidate resolution. These controls are equivalent for base-image selection. -2. Without a bypass, NemoClaw validates and reuses the recorded hint when possible. -3. When the hint is absent or no longer valid, NemoClaw performs normal resolution. - -After a cache miss, source checkouts require a fresh local build before candidate selection when base-image inputs have dirty or staged changes, or Git cannot inspect the worktree safely. -For a clean checkout, NemoClaw first accepts an exact release-version or source-commit image; only when neither exists does a difference from `main` or a missing comparison ref require a fresh local build before `:latest`. -The required-build path does not reuse an older local tag. -If local builds are disabled or the build fails, resolution stops instead of selecting a stale image. -When the OpenShell sandbox ABI is required, NemoClaw also rejects a built image that does not report a compatible glibc version. - -Otherwise, normal resolution checks compatible images in Docker's local image store before attempting to pull a missing published candidate. -When the OpenShell sandbox ABI is required, NemoClaw can reuse or build an ABI-compatible local fallback when published candidates are unavailable or incompatible. -An offline warm recreate or rebuild can therefore continue when the recorded image or another compatible candidate is available locally. -When source inputs require a fresh local build, NemoClaw fails the operation if that build cannot be produced and validated instead of substituting an older local tag. -When the OpenShell sandbox ABI is required, resolution also fails if no ABI-compatible image can be resolved instead of falling back to an unvalidated cached `:latest` image. - -For Hermes, warm-hint and candidate validation reruns a container probe for the MCP SDK and native Streamable HTTP integration. -During normal resolution, NemoClaw tries the exact published digest declared by the final Hermes Dockerfile after release-version and source-commit candidates and after checking whether source changes require a local build, but before mutable `:latest`. -The digest must also pass any active OpenShell ABI requirement, and a validated result can be recorded for warm-hint reuse. -The final Hermes image accepts only the official published digest tracked by its Dockerfile or a repository-built local base, so an otherwise reachable or ABI-compatible image is not sufficient. - -Bypassing the recorded hint does not clear Docker's local image store or require a network pull. -Only `--fresh` also discards the saved onboarding session; the refresh environment variable affects base-image selection only. - - -For NemoClaw-managed environments, use `nemohermes onboard` when you need to create or recreate the OpenShell gateway or sandbox. -Avoid `openshell self-update`, `npm update -g openshell`, `openshell gateway start --recreate`, or `openshell sandbox create` directly unless you intend to manage OpenShell separately and then rerun `nemohermes onboard`. - - -Use `--fresh` to ignore any saved onboarding session and restart the wizard from scratch. This is useful after an interrupted `nemohermes onboard` run when you want to discard saved state instead of continuing it with `--resume`. - -The installer detects existing sandbox sessions before onboarding and prints a warning if any are found. -To make the installer abort instead of continuing, set `NEMOCLAW_SINGLE_SESSION=1`: - -```bash -NEMOCLAW_SINGLE_SESSION=1 curl -fsSL https://www.nvidia.com/nemoclaw.sh | bash -``` - -When existing sandboxes were created with OpenShell earlier than `0.0.37`, the installer prompts before running the new automatic gateway upgrade path. -For scripted installs, set `NEMOCLAW_ACCEPT_EXPERIMENTAL_OPENSHELL_UPGRADE=1` to allow the installer to prepare the current CLI without replacing OpenShell, back up every registered sandbox with the current state manifest, retire the old gateway, install the supported OpenShell release, and recover the existing sandboxes. -If any registered sandbox cannot be backed up, the installer aborts before it changes the gateway. -When the registry contains a pre-fingerprint OpenClaw or Hermes entry with no recorded custom-image evidence, an interactive install asks you to confirm that the listed sandbox used a NemoClaw-managed image. -For a non-interactive install, set `NEMOCLAW_CONFIRM_LEGACY_MANAGED_RECREATE` to the exact JSON array of names printed by the installer, such as `["my-assistant","preserve-hermes"]`, only after verifying every named sandbox used a managed image. -The confirmation permits those legacy entries to recover onto the current managed image, but it does not override recorded custom-image evidence. -After successful recovery, the installer skips generic onboarding. -For a manually prepared upgrade, set `NEMOCLAW_OPENSHELL_UPGRADE_PREPARED=1` only after preserving every registered sandbox and retiring the old gateway. - -The wizard prompts for a provider first, then collects the provider credential if needed. -Supported non-experimental choices include NVIDIA Endpoints, OpenAI, Anthropic, Google Gemini, and compatible OpenAI or Anthropic endpoints. -Credentials are registered with the OpenShell gateway and never persisted to host disk. -Refer to [Credential Storage](../security/credential-storage) for details on inspection, rotation, and migration from earlier releases. -The legacy `nemohermes setup` command is deprecated; use `nemohermes onboard` instead. - -After provider selection, the wizard reviews the provider, model, credential state, and sandbox name before registering inference. -It then prompts for optional web search and messaging channels, builds and starts the sandbox, and asks for a **policy tier** that controls the default set of network policy presets applied to the sandbox. -Three tiers are available: - -| Tier | Description | -|------|-------------| -| Restricted | No tier defaults. Web search or messaging integrations selected earlier can still add their required presets; deselect them during policy review for baseline-only access. | -| Balanced (default) | Full dev tooling and a selected, supported web search provider. Package installs, model downloads, and inference. No messaging platform access by default. | -| Open | Broad access across third-party services including messaging and productivity. Agent-specific unsupported presets are filtered out. | - -After selecting a tier, the wizard shows a combined preset and access-mode screen where you can include or exclude individual presets and toggle each between read and read-write access. -For details on tiers and the presets each includes, refer to [Network Policies](network-policies#policy-tiers). -When you finish the policy step, NemoClaw records the finalized built-in preset selection for that sandbox. -Later re-onboard runs seed from that finalized selection, so presets you intentionally removed stay removed unless you select them again or override the policy mode. - -In non-interactive mode, set the tier with `NEMOCLAW_POLICY_TIER` (default: `balanced`): - -```bash -NEMOCLAW_POLICY_TIER=restricted nemohermes onboard --non-interactive --yes-i-accept-third-party-software -``` - -Unset, blank, or whitespace-only `NEMOCLAW_POLICY_TIER` values use the `balanced` default. -In non-interactive mode, any non-blank value must be one of `restricted`, `balanced`, or `open`; otherwise onboarding exits before preflight, gateway, or inference side effects with an error listing the valid options. -Interactive onboarding ignores an invalid environment value and shows the normal tier prompt. - -`NEMOCLAW_POLICY_MODE` controls how non-interactive onboarding reconciles the tier-derived suggestions against the sandbox's currently-applied presets. -The default is `suggested`, which is *additive*. -Onboarding applies tier defaults and preserves any presets you previously added with [`nemohermes policy-add`](#nemohermes-name-policy-add) across re-onboards. -Use `custom` with `NEMOCLAW_POLICY_PRESETS` when you want the explicit list to be authoritative. -Onboarding removes any preset that is not in the list. -`skip` leaves the applied set untouched and does not apply tier defaults. -NemoClaw filters tier suggestions and resume selections by active agent support and the selected web search provider. -During automatic suggestion and resume reconciliation, it removes stale `brave`, `tavily`, and Hermes `nous-web` selections when they conflict with the active agent or selected provider. -An explicit `custom` preset list or interactive manual selection remains operator-controlled. - -Hermes managed-tool gateway selections add matching Hermes-specific policy presets, such as `nous-web`, `nous-image`, `nous-audio`, `nous-browser`, and `nous-code`, without applying unsupported OpenClaw-only presets. -When Tavily Search is selected, it replaces `nous-web` as the Hermes web search and extract backend while the other selected Nous tools remain enabled. - -| Value | Behaviour | -|-------|-----------| -| `suggested` (default) | Apply tier defaults and preserve any extra presets already applied. Aliases: `default`, `auto`. | -| `custom` | Apply exactly `NEMOCLAW_POLICY_PRESETS`. Previously-applied presets not in the list are removed. Alias: `list`. | -| `skip` | Skip the policy step entirely. Aliases: `none`, `no`. | - -For non-interactive onboarding, you must explicitly accept the third-party software notice: - -```bash -nemohermes onboard --non-interactive --yes-i-accept-third-party-software -``` - -or: - -```bash -NEMOCLAW_ACCEPT_THIRD_PARTY_SOFTWARE=1 nemohermes onboard --non-interactive -``` - -For scripted installer runs, pass explicit acceptance to the `bash` side of the installer pipe: - -```bash -curl -fsSL https://www.nvidia.com/nemoclaw.sh | NEMOCLAW_NON_INTERACTIVE=1 NEMOCLAW_ACCEPT_THIRD_PARTY_SOFTWARE=1 bash -``` - -If the installer cannot prompt for the notice in a terminal and no explicit acceptance is set, it exits before installing Node.js or the NemoClaw CLI. - -Hermes supports Tavily Search through NemoClaw onboarding and does not support Brave Search. -To enable Tavily in non-interactive mode, set the provider and matching key. - -```bash -NEMOCLAW_WEB_SEARCH_PROVIDER=tavily \ -TAVILY_API_KEY=... \ - nemohermes onboard --non-interactive -``` - -Set `NEMOCLAW_WEB_SEARCH_PROVIDER=none` to disable web search explicitly. -When the selector is unset, NemoClaw enables Tavily when `TAVILY_API_KEY` is available and ignores `BRAVE_API_KEY` for Hermes. -An explicit Tavily selection with no key exits before sandbox creation. -A Tavily key that fails validation prints a warning, disables web search for that run, and lets the rest of onboarding continue. -Changing or disabling Tavily recreates the sandbox because the Hermes backend, environment placeholder, and credential attachment are part of the image. -If you also select the Nous-managed web gateway through Nous Portal OAuth, Tavily replaces `nous-web` while other selected Nous tools remain enabled. -API-key mode is inference-only and does not enable managed Nous tool gateways. - -The wizard prompts for a sandbox name. -Names must be 1 to 63 characters, lowercase, start with a letter, contain only letters, numbers, and internal hyphens, and end with a letter or number. -The CLI rejects names that do not match these rules. -It also prints a `Try: ` recovery line whenever it can derive a valid lowercase, hyphen-separated form from the input, so passing `--name MyAssistant` reports `Try: myassistant`. -Names that match global CLI commands (`status`, `list`, `debug`, etc.) are rejected to avoid routing conflicts. -Use `--agent ` to target a specific installed agent profile during onboarding. -The `nemohermes onboard --help` output lists installed runtime names inline, and `nemohermes agents list` shows the same runtimes with manifest descriptions. - -Use `--control-ui-port ` to choose the host dashboard port for a sandbox. -The value must be an integer from `1024` through `65535`. -This flag takes precedence over `CHAT_UI_URL`, `NEMOCLAW_DASHBOARD_PORT`, the previous registry value, and the default port. - -For Hermes sandboxes, do not use port `8642`; NemoClaw reserves it for the Hermes OpenAI-compatible API and rejects it as a dashboard port before sandbox creation. - -If you enable Slack during onboarding, the wizard collects both the Bot Token (`SLACK_BOT_TOKEN`) and the App-Level Token (`SLACK_APP_TOKEN`). -Socket Mode requires both tokens. -The app-level token is stored in a dedicated `slack-app` OpenShell provider and forwarded to the sandbox alongside the bot token. -The wizard also accepts optional `SLACK_ALLOWED_USERS` and `SLACK_ALLOWED_CHANNELS` values so you can restrict Slack DMs, channel `@mention` users, and channel IDs before the sandbox image is built. - -If you enable Discord during onboarding, the wizard can also prompt for a Discord Server ID, whether the bot should reply only to `@mentions` or to all messages in that server, and an optional Discord User ID. -NemoClaw bakes those values into the sandbox image as Discord guild workspace config so the bot can respond in the selected server, not just in DMs. -If you leave the Discord User ID blank, the guild config omits the user allowlist and any member of the configured server can message the bot. -Guild responses remain mention-gated by default unless you opt into all-message replies. -If `DISCORD_SERVER_ID` is set and `DISCORD_REQUIRE_MENTION` is unset, NemoClaw records the existing mention-only default (`DISCORD_REQUIRE_MENTION=1`). - -If you enable Telegram during onboarding, the wizard can also prompt for whether group chats should reply only to `@mentions` or to all group messages. -Mention-only group replies are the default. -Set `TELEGRAM_REQUIRE_MENTION=0` for non-interactive onboarding when you want all group messages to trigger replies. -For OpenClaw, Telegram group access defaults to `TELEGRAM_GROUP_POLICY=open`; set `TELEGRAM_GROUP_POLICY=allowlist` or `TELEGRAM_GROUP_POLICY=disabled` before non-interactive onboarding when you want stricter group access. -Hermes does not have an equivalent disable-groups policy; `TELEGRAM_ALLOWED_IDS` maps to Hermes `TELEGRAM_ALLOWED_USERS`, which authorizes those users across DMs, groups, and forums. -Pairing and `TELEGRAM_ALLOWED_IDS` still govern direct messages. - -If you cancel a brand-new onboarding run at the policy preset step, NemoClaw rolls back the sandbox, registry entry, and onboarding session instead of leaving a default sandbox with unfinished policy state. -Existing live sandboxes are not deleted by this cancel rollback path. - -If you run onboarding again with the same sandbox name and choose a different inference provider or model, NemoClaw detects the drift and recreates the sandbox so the running agent config matches your selection. -In interactive mode, the wizard asks for confirmation before delete and recreate. -In non-interactive mode, NemoClaw recreates automatically when the stored selection is readable and differs. -For managed Deep Agents Code sandboxes, NemoClaw also recreates when the live `dcode identity` selection is unreadable; other agent paths continue to reuse by default when their stored selection cannot be read. -Set `NEMOCLAW_RECREATE_SANDBOX=1` to force recreation even when no drift is detected. - -Before deleting an existing sandbox during recreation, NemoClaw backs up the workspace state declared by the selected agent profile and restores it into the new sandbox once it is live. -This applies whether the existing sandbox is ready or marked not-ready, so cross-version upgrades that pass `NEMOCLAW_RECREATE_SANDBOX=1` no longer drop user files from the selected agent workspace. -The behaviour matches `nemohermes rebuild --force`. -NemoClaw aborts the recreate when the backup cannot complete in full, including when individual state directories or files fail mid-backup, so failed entries are not silently dropped on delete. -Set `NEMOCLAW_RECREATE_WITHOUT_BACKUP=1` to skip the pre-recreate backup. -The destination sandbox starts with a fresh workspace. - -For Hermes, the backed-up paths come from `agents/hermes/manifest.yaml`, including `/sandbox/.hermes` state such as memories, sessions, skills, plugins, cron, logs, plans, workspace, messaging platform state, and `runtime/state.db`. - -Before creating the gateway, the wizard runs preflight checks. -It verifies that Docker is reachable, warns on untested runtimes such as Podman, and prints host remediation guidance when prerequisites are missing. -The preflight also enforces the OpenShell version range declared in the blueprint (`min_openshell_version` and `max_openshell_version`). -If the installed OpenShell version falls outside this range, onboarding exits with an actionable error and a link to compatible releases. -For fresh OpenShell installs, NemoClaw queries published OpenShell releases and asks the installer to use a release that fits the blueprint range. -If release metadata is unavailable, the installer uses its bundled fallback pin and the post-install version gate still enforces the range. - -When NemoClaw finds an existing gateway to reuse, it probes the host gateway HTTP endpoint before declaring the gateway reusable. -If the container is running but the upstream is still warming up (for example, immediately after a Docker daemon restart), NemoClaw rebuilds the gateway instead of trusting stale metadata. -On the Docker-driver gateway path, preflight stays read-only when it detects a stale gateway (for example, a Docker-driver runtime env hash drift). -It prints a `⚠ Gateway will be recreated when sandbox creation starts` notice and defers the actual teardown to step `[2/8] Starting OpenShell gateway`. -This means pressing `Ctrl+C` between preflight and step `[2/8]` leaves the running gateway and existing sandbox containers untouched, so `nemohermes onboard` is safe to run just to check preflight output. -For Linux Docker-driver gateways, onboarding also checks that a helper container on the OpenShell Docker network can reach `host.openshell.internal:`. -If a host firewall blocks that sandbox path, onboarding exits with a `sudo ufw allow from to port proto tcp` command before it reports the gateway healthy. -Set `NEMOCLAW_AUTO_FIX_FIREWALL=1` to opt in to automatic UFW remediation for this specific failure: NemoClaw uses `sudo -n` only, validates the Docker bridge subnet/gateway/port, applies the narrow UFW rule only after a proven TCP reachability failure, and re-probes before continuing. -If passwordless sudo, UFW, or active UFW is unavailable, NemoClaw falls back to the manual guidance path without prompting for a password. -Tune the wait via `NEMOCLAW_REUSE_HEALTH_POLL_COUNT` (default `6`) and `NEMOCLAW_REUSE_HEALTH_POLL_INTERVAL` (default `5` seconds). -The poll count is clamped to a minimum of `1` so the probe always runs at least once, and the interval is clamped to a minimum of `0` (no sleep between attempts). - -#### `--from ` - -Build the sandbox image from a custom Dockerfile instead of the stock NemoClaw image. -The entire parent directory of the specified file is used as the Docker build context, so any files your Dockerfile references (scripts, config, etc.) must live alongside it. -If that directory contains a `.dockerignore`, onboarding applies those rules while calculating the context size and staging files for Docker. -NemoClaw also applies additional secret-safety exclusions that override `.dockerignore` negation rules: credential-style files and directories such as `.env*`, `.ssh/`, `.aws/`, `.netrc`, `.npmrc`, `secrets/`, `*.pem`, and `*.key` are still skipped even if `.dockerignore` tries to include them. -Without a `.dockerignore`, onboarding still skips common large or local-only directories (`node_modules`, `.git`, `.venv`, and `__pycache__`) while staging this context. -Other build outputs such as `dist/`, `target/`, or `build/` are included unless your `.dockerignore` excludes them. -If the staged context is larger than 100 MB, onboarding prints a warning before the Docker build starts. -Move the Dockerfile into a smaller dedicated directory or add `.dockerignore` entries for generated artifacts to shrink the context. -If the directory contains unreadable files (for example, Windows system files visible in WSL), onboarding exits with an error suggesting you move the Dockerfile to a dedicated directory. - - -NemoClaw builds user-supplied `--from` contexts with the OpenShell gateway builder. -The host-side local BuildKit prebuild is limited to build contexts generated entirely by NemoClaw. -On a local Docker-driver gateway, a `Local BuildKit build skipped` notice is expected and onboarding continues with the custom image. - - -```bash -nemohermes onboard --from path/to/Dockerfile -``` - -The Dockerfile path must exist. -Missing paths fail during command parsing before preflight, gateway setup, inference setup, or sandbox creation starts. - -The file can have any name; if it is not already named `Dockerfile`, onboard copies it to `Dockerfile` inside the staged build context automatically. -To create an isolated build context, create a dedicated directory that contains only the Dockerfile and the files it needs: - -```text -build-dir/ -├── Dockerfile -└── files-used-by-COPY/ -``` - -For faster custom builds, plan for Docker cache behavior: - -- Treat the first build on a fresh host as a cold build. - Cold builds download the base image and package indexes, so they take longer than later warm rebuilds even when NemoClaw is healthy. -- A warm rebuild reuses cached layers when the base image and earlier layers are unchanged, so it is much faster than the first build. -- Order Dockerfile instructions from least-changing to most-changing: base image, system packages, dependency manifests, dependency install, then application source. - This lets warm rebuilds reuse cached dependency layers instead of reinstalling on every source change. -- Pin the base image to an explicit tag or digest so warm rebuilds resolve the same cached base instead of pulling a new one. - -To diagnose where a slow build spends time, set `NEMOCLAW_TRACE=1` and read the phase timings in [Onboard Profiling Traces](#onboard-profiling-traces). -NemoClaw does not guarantee exact build timings. - -All NemoClaw build arguments (`NEMOCLAW_MODEL`, `NEMOCLAW_PROVIDER_KEY`, `NEMOCLAW_INFERENCE_BASE_URL`, etc.) are injected as `ARG` overrides at build time, so declare them in your Dockerfile if you need to reference them. - -Custom Dockerfiles must declare `ARG NEMOCLAW_TOOL_DISCLOSURE=progressive` exactly once in the final build stage and promote it into that stage's runtime environment. -The usual runtime contract is: - -```dockerfile -ARG NEMOCLAW_TOOL_DISCLOSURE=progressive -ENV NEMOCLAW_TOOL_DISCLOSURE=${NEMOCLAW_TOOL_DISCLOSURE} -``` - -Onboarding and rebuild preflight reject a missing, duplicate, or unconsumed declaration before replacing an existing sandbox. - -In non-interactive mode, the path can also be supplied via the `NEMOCLAW_FROM_DOCKERFILE` environment variable. -You must also supply a sandbox name via `--name ` or `NEMOCLAW_SANDBOX_NAME` so a `--from` build cannot silently clobber the default `my-assistant` sandbox. - -```bash -NEMOCLAW_NON_INTERACTIVE=1 NEMOCLAW_FROM_DOCKERFILE=path/to/Dockerfile NEMOCLAW_SANDBOX_NAME=my-build nemohermes onboard -``` - -If a `--resume` is attempted with a different `--from` path than the original session, onboarding exits with a conflict error rather than silently building from the wrong image. - -#### `--name ` - -Set the sandbox name without going through the interactive prompt. -The same name format and reserved-name rules that the wizard enforces apply here too. Names must be 1 to 63 characters, lowercase, start with a letter, contain only letters, numbers, and internal hyphens, and end with a letter or number. -Names that match a NemoClaw CLI command (`status`, `list`, `debug`, etc.) are rejected up front. - -```bash -nemohermes onboard --non-interactive --name my-build --from path/to/Dockerfile -``` - -The flag wins over `NEMOCLAW_SANDBOX_NAME`. -When prompting is possible, `NEMOCLAW_SANDBOX_NAME` fills the interactive default so you can press Enter to accept it. -When prompting is impossible (no TTY or `--non-interactive`), the env var is also honoured so existing CI scripts keep working. -Combining `--from ` with non-interactive onboarding requires one of `--name` or `NEMOCLAW_SANDBOX_NAME`; otherwise onboarding exits rather than silently defaulting to `my-assistant` and clobbering the default sandbox. - -### `nemohermes onboard --from` - -Use a custom Dockerfile for the sandbox image. -This variant of `nemohermes onboard` accepts a `--from ` argument to build the sandbox from a user-supplied Dockerfile instead of the default NemoClaw image. -The user-supplied context uses the OpenShell gateway builder instead of NemoClaw's host-side local BuildKit prebuild. - -```bash -nemohermes onboard --from ./Dockerfile.custom -``` - -### GPU passthrough - -When `nemohermes onboard` detects an NVIDIA GPU on the host, it enables OpenShell GPU passthrough at both the gateway and sandbox level by default. -Detection proceeds along two paths. The `nvidia-smi`-based paths (the primary `--query-gpu=name,memory.total,memory.free` probe and the unified-memory `--query-gpu=name` fallback) require `nvidia-smi` to succeed and, on hosts whose firmware does not classify as a known NVIDIA platform (DGX Spark, DGX Station, Jetson, or Tegra), additionally require that the GPU name does not match the placeholder family observed on the Windows-on-ARM WSL2 nvidia-smi shim (`JMJWOA-Generic-*`) and that either the host is not ARM64 Linux (the observed shim is Windows-on-ARM only) or the NVIDIA kernel driver is bound (`/proc/driver/nvidia/` present), so that placeholder shims on non-NVIDIA hardware are not mistaken for real GPUs. -Jetson/Tegra hosts that ship without `nvidia-smi` continue to be detected via the devicetree firmware fallback (`/sys/firmware/devicetree/base/model`) or the Tegra device-node fallback (`/dev/nvhost-gpu`, `/dev/nvhost-ctrl-gpu`, `/dev/nvhost-ctrl`, or `/dev/nvmap`); both bypass the trust-tier gate above. -Use `--no-gpu` to opt out when you want host-side inference providers only and do not need direct GPU access inside the sandbox. -Use `--gpu` to require GPU passthrough and fail fast if an NVIDIA GPU is not detected. -Use `--sandbox-gpu` or `--no-sandbox-gpu` to control only direct NVIDIA GPU access inside the sandbox. -Use `--sandbox-gpu --sandbox-gpu-device ` to pass a specific OpenShell GPU device selector to `openshell sandbox create`; device selectors require explicit sandbox GPU enablement. -On ordinary native Linux Docker-driver hosts with usable CDI, NemoClaw uses OpenShell native GPU injection by default. -On Docker Desktop WSL and Jetson/Tegra, NemoClaw creates the sandbox first and then recreates the OpenShell-managed Docker container with NVIDIA GPU access by default. -When you force this compatibility path on ordinary native Linux, NemoClaw uses an available NVIDIA CDI spec before falling back to Docker `--gpus all` or the NVIDIA runtime. -On Docker Desktop WSL, the compatibility path skips CDI and tries Docker `--gpus all` before the NVIDIA runtime. -On Jetson/Tegra hosts, the compatibility path uses the NVIDIA runtime and adds the host group IDs that own `/dev/nvmap` and `/dev/nvhost-*` so the sandbox user can initialize CUDA. -If the patch fails, onboarding keeps diagnostics and prints a manual cleanup command rather than deleting the failed sandbox automatically. - -Prerequisites: - -- Ensure NVIDIA GPU drivers are installed and working. - - On generic NVIDIA hosts, `nvidia-smi` must succeed. - - On Jetson/Tegra hosts shipping without `nvidia-smi`, the devicetree firmware fallback substitutes. -- NVIDIA Container Toolkit configured for Docker. - -When GPU passthrough is enabled and a gateway already exists without it, onboarding first checks whether replacing the CPU-only gateway is safe. -If no other registered sandbox depends on that gateway, or if `--recreate-sandbox` is recreating the only registered sandbox with the same name, onboarding cleans up the stale gateway and continues. -If other sandboxes depend on the gateway or Docker state is unclear, onboarding exits without cleanup and prints targeted destroy or gateway-removal guidance. -To add GPU to an existing sandbox, rerun with `--recreate-sandbox`. -Leave `NEMOCLAW_DOCKER_GPU_PATCH` unset or set it to `auto` to use the platform default. -Set `NEMOCLAW_DOCKER_GPU_PATCH=1` to force the legacy Docker container-swap path on ordinary native Linux. -Set `NEMOCLAW_DOCKER_GPU_PATCH=0` to select native OpenShell GPU injection on ordinary native Linux or Jetson/Tegra. -Use `NEMOCLAW_DOCKER_GPU_PATCH=0` on Jetson/Tegra only for troubleshooting because it bypasses Tegra device-group propagation and CUDA may not initialize. -Docker Desktop WSL ignores `NEMOCLAW_DOCKER_GPU_PATCH=0` because GPU passthrough on that runtime requires the compatibility patch. -Use `--no-sandbox-gpu`, `--no-gpu`, or `NEMOCLAW_SANDBOX_GPU=0` when you want to disable sandbox GPU passthrough on Docker Desktop WSL. - -### `nemohermes list` - -List all registered sandboxes with their model, provider, and policy presets. -Pass `--json` for machine-readable output that includes a `schemaVersion`, the default sandbox, recovery metadata, and the sandbox inventory. -Sandboxes with an active SSH session are marked with a `●` indicator so you can tell at a glance which sandbox you are already connected to in another terminal. -When a sandbox has a recorded dashboard port, the output includes its local dashboard URL. -The default sandbox in text and JSON output honors the same environment override order as host-level status and tunnel commands: `NEMOCLAW_SANDBOX_NAME`, then `NEMOCLAW_SANDBOX`, then `SANDBOX_NAME`, then the registry default. - -```bash -nemohermes list [--json] -nemohermes list --json -``` - -### `nemohermes use ` - -Promote a registered sandbox to the default. -This is the first-class replacement for hand-editing `~/.nemoclaw/sandboxes.json`; it updates the registry through the same atomic, lock-guarded path that `nemohermes onboard` uses for the initial default. -Subsequent commands and the `NEMOCLAW_SANDBOX_NAME` resolution order then pick up the new default automatically. -Pass `--json` to receive a machine-readable result indicating whether the registry was updated, the sandbox was already the default, or the name is unknown. - -`nemohermes use` is a thin selector and never mutates the sandbox itself. -It fails with a non-zero exit and a known-sandbox list when the requested name is not registered, so scripts can branch safely on the outcome. - -```bash -nemohermes use -nemohermes use --json -``` - -### `nemohermes deploy` - - -The `nemohermes deploy` command is deprecated. -Prefer provisioning the remote host separately, then running the standard NemoClaw installer and `nemohermes onboard` on that host. - - -Deploy NemoClaw to a remote GPU instance through [Brev](https://brev.nvidia.com). -This command remains as a compatibility wrapper for the older Brev-specific bootstrap flow. -The Brev instance name is the positional argument. -The sandbox name comes from `NEMOCLAW_SANDBOX_NAME` and defaults to `my-assistant`; invalid sandbox names fail before Brev provisioning starts. - -```bash -nemohermes deploy -``` - -### `nemohermes connect` - -Connect to a sandbox by name. -If the sandbox is not yet in the `Ready` phase, `connect` polls `openshell sandbox list` every few seconds and prints the current phase. This gives you progress output right after onboarding, when the 2.4 GB image is still pulling, instead of a silent hang. -Control the wait budget with `NEMOCLAW_CONNECT_TIMEOUT` (integer seconds, default `120`). When the deadline expires, `connect` exits non-zero with the last-seen phase. - -On a TTY, a one-shot hint prints before dropping into the sandbox shell. -The hint is agent-aware. It names the correct TUI command for the sandbox's agent and reminds you to use `/exit` to leave the chat before `exit` returns you to the host shell. -Set `NEMOCLAW_NO_CONNECT_HINT=1` to suppress the hint in scripted workflows. -If the sandbox is running an outdated agent version, a non-blocking warning prints before connecting with a `nemohermes rebuild` hint. -If another terminal is already connected to the sandbox, `connect` prints a note with the number of existing sessions before proceeding. Multiple concurrent sessions are allowed. - -`connect` does not pull or serve a model itself, but it does inspect managed-vLLM install variables such as `NEMOCLAW_VLLM_MODEL` and `NEMOCLAW_VLLM_EXTRA_ARGS_JSON` if you exported them in the same shell. -An unknown model slug, malformed extra-args JSON, or a gated model (for example `deepseek-r1-distill-70b`) with no `HF_TOKEN` or `HUGGING_FACE_HUB_TOKEN` exits non-zero with the same error the installer would emit, before any sandbox readiness probe or SSH attach. -Unset the managed-vLLM variable, or fix the value, before retrying. - -When the live OpenShell gateway inference route differs from the route recorded in the NemoClaw registry, `connect` checks every registered sandbox on that gateway before attempting a repair. -It realigns the route only when those registry entries are compatible with the requested provider and model. -If another sandbox records a conflicting route, `connect` exits non-zero without changing the gateway and names the affected sandboxes. -Use `nemohermes inference set --provider --model ` to make an intentional compatible route change. -If the sandbox is registered locally but missing from a healthy gateway, `connect` preserves the registry entry and points you to `rebuild --yes`, `onboard`, or `destroy` instead of deleting the metadata needed for recovery. - -After a host reboot, the OpenShell gateway rotates its SSH host keys. -`connect` detects the resulting identity drift, prunes stale `openshell-*` entries from `~/.ssh/known_hosts`, and retries automatically. -You no longer need to re-run `nemohermes onboard` after a reboot in this case. - -```bash -nemohermes my-assistant connect [--probe-only] -``` - -The `--probe-only` flag verifies the sandbox is reachable over SSH and exits without opening a shell. -Use it for health checks and scripted readiness probes. - -### `nemohermes exec` - -Run a single command non-interactively in a running sandbox via the OpenShell exec endpoint. -The command runs as the sandbox user with `HOME=/sandbox`, so in-sandbox tooling resolves NemoClaw-provisioned config the same way it does for `connect` and `openshell sandbox connect`. -This is the supported substitute for `docker exec` on the sandbox container; raw `docker exec` runs as root and lands on `HOME=/root`, where the selected agent config is not present. - -Hermes config resolves under `/sandbox/.hermes`. - -```bash -nemohermes my-assistant exec -- hermes --version -nemohermes my-assistant exec --workdir /sandbox/workspace -- ls -la -``` - -Everything after `--` is forwarded verbatim to the sandbox command, including flags the inner command needs. - -The exit code is the remote command's exit code. - -By default, NemoClaw inherits caller stdin only when it is a terminal. -Non-terminal or unavailable stdin is closed so SSH, CI, and other one-shot commands cannot wait on an inherited pipe. -Pass `--stdin` to forward an intentional pipe, or `--no-stdin` to close terminal stdin explicitly. - -```bash -printf 'hello\n' | nemohermes my-assistant exec --stdin -- cat -ssh dgx-spark 'nemohermes my-assistant exec --no-stdin -- pwd' -``` - -The OpenShell exec endpoint rejects any command argument (the values after `--`) that contains a newline or carriage return, so multi-line commands such as a `bash` heredoc cannot be passed through `exec`. -NemoClaw detects this before dispatch, names the offending argument position, and exits with status `2` instead of surfacing the lower-level OpenShell `InvalidArgument` error. -Join the statements with semicolons (`nemohermes exec -- bash -lc "cmd1; cmd2"`). -Pipe the script into the sandbox shell over stdin (`printf 'cmd1\ncmd2\n' | nemohermes exec --stdin -- bash`). -Or write the script to a file in the sandbox and run it (`nemohermes exec -- bash `). - -| Flag | Description | -|------|-------------| -| `--workdir ` | Working directory inside the sandbox. The directory is checked before the command runs; if it does not exist, NemoClaw reports `error: --workdir: does not exist inside the sandbox` and exits with status `1` without invoking the inner command. | -| `--tty` / `--no-tty` | Allocate a pseudo-terminal; defaults to auto-detection (on when stdin and stdout are terminals) | -| `--timeout ` | Timeout in seconds (`0` means no timeout) | -| `--stdin` / `--no-stdin` | Force caller stdin forwarding or closure (default: inherit terminal stdin; close non-terminal or unavailable stdin). | - -### `nemohermes agent` - -The `agent` wrapper rejects Hermes sandboxes with guidance for the Hermes HTTP API. -Hermes sandboxes expose an OpenAI-compatible API on port `8642` inside the sandbox, so non-interactive use does not need a wrapper command. - -Forward the port and POST chat completions directly: - -```bash -openshell forward start --background 8642 my-hermes -curl -sN http://127.0.0.1:8642/v1/chat/completions \ - -H 'Content-Type: application/json' \ - -d '{"model":"","messages":[{"role":"user","content":"What is 2+2?"}],"stream":true}' -``` - -### Advanced Sandbox Maintenance Commands - -The following commands are available for targeted host-side maintenance, but they are not part of the top-level public command list. - -#### `nemohermes config get` - -Read the sanitized agent configuration from a sandbox. -The output removes credential-bearing sections such as the OpenClaw gateway token before printing. -Use `--key` to read one dotpath and `--format` to choose JSON or YAML output. - -```bash -nemohermes my-assistant config get -nemohermes my-assistant config get --key model --format yaml -``` - -| Flag | Description | -|------|-------------| -| `--key ` | Print one value from the sanitized config | -| `--format json\|yaml` | Output format. Defaults to JSON | - -#### `nemohermes shields` - -Manage the sandbox config lockdown posture from the host. -Use `shields status` to inspect the current state, `shields up` to lock the sandbox config and restore the captured restrictive policy, and `shields down` to temporarily unlock the config for maintenance. -For the full mutability matrix, refer to [Runtime Controls](../manage-sandboxes/runtime-controls). - -```bash -nemohermes my-assistant shields status -nemohermes my-assistant shields up -nemohermes my-assistant shields down --timeout 5m --reason "maintenance" -``` - -| Subcommand | Description | -|------|-------------| -| `shields status` | Show whether lockdown is configured, active, temporarily unlocked, or in error | -| `shields up` | Lock the sandbox config and restore the saved restrictive policy | -| `shields down` | Temporarily unlock the sandbox config. Supports `--timeout`, `--reason`, and `--policy` | - -If `shields up` reports that the config remains unlocked or drifted, confirm that the sandbox is running and ready, then retry `nemohermes shields up`. -If the retry still fails, rebuild a known-good baseline with `nemohermes rebuild --yes`. - -Host-side config and inference writes, snapshot mutation, sandbox destruction, and shields transitions serialize per sandbox. -When a timed shields-down window reaches its deadline, auto-restore can interrupt the exact process tree holding that transition and restore lockdown. -Retry an interrupted command in a new shields-down window. - -### `nemohermes recover` - -Repair a stopped in-sandbox gateway and re-establish host-side forwards without opening an SSH session. -Use this after a direct sandbox container restart, a sandbox crash, or whenever `nemohermes status` reports the gateway is not running but the sandbox is alive. - -For built-in OpenClaw and Hermes sandboxes, `recover` sends an authenticated lifecycle request through registry-scoped privileged direct-container control. -The host selects the controller from the live container topology. -In a direct root-entrypoint container, the request reaches the root PID 1 supervisor. -In an OpenShell-managed container, the request enters the root-owned mode `0500` managed controller through a sanitized root exec while OpenShell remains PID 1. -It does not use ordinary `openshell sandbox exec` or an in-sandbox manual relaunch as a fallback. -It is idempotent. -When `recover` repairs a stopped built-in OpenClaw or Hermes gateway, it retries only when stdout is empty and stderr is exactly one `SUPERVISOR_BUSY` or `SUPERVISOR_UNAVAILABLE` line, with at most three controller attempts. -Other controller failures stop immediately. -If the gateway is already running, the command exits zero without force-restarting it; it can still re-evaluate supported safety checks and check or recover host-side forwards. -Use [`nemohermes gateway restart`](#nemohermes-name-gateway-restart) when you deliberately need a running gateway to reload runtime configuration or plugins. - -```bash -nemohermes my-assistant recover -``` - -`recover` re-evaluates the documented Hermes secret boundary against `/sandbox/.hermes/.env` and the supervisor runtime environment on every run, including when the gateway is already healthy. -If the file contains raw secret-shaped values (for example a pasted Telegram, Discord, or Slack bot token in place of the expected `openshell:resolve:env:` placeholder), the command exits non-zero and prints the offending key. -The direct root-entrypoint supervisor stops a running gateway after this refusal, while the managed controller refuses before signaling the observed child. -Replace each flagged value with the `openshell:resolve:env:` placeholder and re-run. -The direct root-entrypoint supervisor verifies the strict root-owned config hash. -The managed controller verifies that strict hash when both Hermes config inputs are root-owned and locked. -Mutable config under the managed topology has no durable root-owned hash anchor and retains the same trust and time-of-check/time-of-use limits as managed cold start. -If the boundary validator or supervisor helper is missing, recovery fails closed, names the sandbox, explains that `/sandbox/.hermes/.env` could not be re-evaluated, and leaves an otherwise healthy gateway untouched. -Rebuild an older sandbox image with `nemohermes rebuild --yes` before retrying. - -The privileged control path requires a running direct sandbox container that belongs to the named registry entry. -Supported built-in images use either a direct root entrypoint or the OpenShell-managed process shape with OpenShell as PID 1 and exactly one nonroot `nemoclaw-start` supervisor. -An arbitrary nonroot entrypoint that does not match the supported OpenShell-managed process shape fails with the `privileged control unavailable` failure layer. -Kubernetes and other deployments without a matching direct container also fail with that layer. - -### `nemohermes gateway restart` - -Force-restart the supported in-sandbox gateway process through the controller for the live container topology. -Use this after runtime configuration or plugin changes that the agent reads only at gateway startup, such as Hermes Langfuse plugin settings. -Unlike `recover`, this command restarts a healthy gateway instead of exiting after the health probe. - -```bash -nemohermes my-assistant gateway restart [--quiet|-q] -``` - -On success, the command reports that the gateway was restarted, health passed, and forwards were checked or recovered. -It also checks the dashboard forward, messaging forward, and manifest-declared agent forwards. -`--quiet` suppresses progress lines but still prints refusal diagnostics. -In the direct root-entrypoint topology, PID 1 stops only the gateway child whose process ID and process start identity match the tracked child, applies the restart seal, and launches the replacement under the separate `gateway` UID. -In the OpenShell-managed topology, the installed root controller verifies a stable OpenShell to `nemoclaw-start` to gateway process shape, holds a root-only lifecycle lock, publishes one root-owned exit authorization bound to the exact gateway process ID, kernel start identity, and live controller identity, pidfd-targets the observed child, waits for the nonroot entrypoint supervisor to respawn it under the sandbox UID, and proves the replacement listener and HTTP health. -That managed process proof prevents PID reuse from redirecting the signal but cannot establish provenance against a malicious same-UID process or create gateway and agent UID isolation. -For Hermes, the entrypoint supervisor also owns the dashboard process, internal API relay, dashboard relay, and gateway log stream. -The managed nonroot supervisor continuously repairs those processes, stops an alive but deaf gateway after four consecutive failed health checks, and quarantines relaunch after five unexpected exits or failed replacement candidates within 60 seconds until sandbox recreation. -That authorization keeps an authenticated host-requested exit out of the crash budget while its exact root controller remains live; it records host intent for the exit but does not claim that the host signal was the only possible cause in the shared-UID topology. -The host repairs only the host-side OpenShell forwards after the supervisor reports a healthy gateway. - -For Hermes, both controllers validate `/sandbox/.hermes/.env` against the secret-boundary guard and validate the supervisor runtime environment before restart. -The direct root-entrypoint supervisor verifies `/sandbox/.hermes/config.yaml` and `.env` against the root-owned strict hash and relaunches the process as the `gateway` user. -The managed controller verifies the strict hash when both config inputs are root-owned and locked, but mutable managed config retains cold-start-equivalent trust and time-of-check/time-of-use limits. -Neither controller recomputes a trusted strict hash to adopt direct in-sandbox edits. -Use supported host commands such as `nemohermes config set` and `nemohermes inference set` for intended runtime configuration changes because those commands update the managed config metadata together. -When a strict hash is available and does not match, the command reports the `config hash mismatch` failure layer. -Hermes host config writes, shields transitions, and lifecycle seals share one root-only mutation lock. -Config writes are bound to the digest of the matching read and atomically refresh the strict and compatibility hashes before the prior ownership and mode posture is restored. -The shields transition keeps that lock through recursive filesystem updates, verification, and content-seal capture, and replaces sensitive inodes before lockdown. -If a concurrent lifecycle request reports `SUPERVISOR_BUSY`, or a config or shields command reports `Hermes config mutation is already in progress`, wait for the active operation to finish and retry. -Run `nemohermes shields down` before a Hermes config or inference change; these commands refuse to mutate a shields-up sandbox. - -The command can fail at these layers: unsupported agent, privileged control unavailable, secret-boundary refusal, unsafe config path, config hash mismatch when a strict hash is available, launch failure, health timeout, or forward recovery failure. -An older direct-container image without the matching supervisor or managed controller helper reports `privileged control unavailable` and requires `nemohermes rebuild --yes`. -Ordinary OpenShell exec and manual in-sandbox relaunch are not fallback paths. -Terminal agents do not have a gateway runtime and fail as unsupported. - -### `nemohermes status` - -Show sandbox-scoped status, health, and inference configuration for one registered sandbox. -Use this form when you care about a specific sandbox's live OpenShell state, agent runtime, inference health, GPU proof, permissions, and recovery hints. -Do not pass a sandbox name to `nemohermes status`; that command is the global all-sandbox/service overview. - -Pass `--json` to emit a structured per-sandbox report instead of the text renderer. -The JSON output includes at least `schemaVersion`, `name`, `found`, `model`, `provider`, `phase`, `gatewayState`, `inferenceHealth`, `rpcIssue`, `hostGpuDetected`, `sandboxGpuEnabled`, `sandboxGpuMode`, `sandboxGpuDevice`, `openshellDriver`, `openshellVersion`, `policies`, `failureLayer`, `terminalRuntimeHealth`, and `dockerPaused`. -`openshellDriver` and `openshellVersion` are always strings (falling back to `"unknown"` when the registry has no value), so consumers can rely on `typeof` checks. -`failureLayer` is `null` when no preflight failure was detected and otherwise one of `docker_unreachable`, `sandbox_container_stopped`, or `sandbox_dashboard_port_conflict`; when set, `inferenceHealth` is suppressed to `null` so automation does not see a stale remote-provider healthy status during a local outage. -`dockerPaused` is `true` when NemoClaw detects that the Docker-driver sandbox container is paused. -In that case, text output keeps OpenShell's authoritative phase but prints a `docker unpause ` recovery hint instead of sending you directly to rebuild. -For terminal runtime sandboxes, the command also checks cgroup OOM kill counters. -If the counter records an OOM kill, text output prints `Runtime health: degraded (... OOM kill recorded)` and points you to `nemohermes rebuild`; JSON output reports `terminalRuntimeHealth.kind: "degraded"` with the OOM kill count and source counter path. -The command exits non-zero when the sandbox is missing locally, the gateway state is not `present`, the gateway reports a schema/protobuf mismatch (mirrored as `rpcIssue`), `failureLayer` is non-null, or a terminal runtime sandbox reports a recorded OOM kill. -The alias form `nemohermes status --json` requires the sandbox to be registered locally; the canonical form `nemohermes sandbox status --json` is the one to use from automation that may run against an unknown sandbox name, since it still emits a JSON document with `found: false` instead of a text error. - -```bash -nemohermes my-assistant status -nemohermes my-assistant status --json -nemohermes sandbox status my-assistant --json -``` - -The command probes every inference provider and reports one of three states on the `Inference` line: - -| State | Meaning | -|-------|---------| -| `healthy` | The provider endpoint returned a reachable response. | -| `unreachable` | The probe failed. The output includes the endpoint URL and a remediation hint. | -| `not probed` | The endpoint URL is not known (for example, `compatible-*` providers). | -| `not verified` | NemoClaw could not verify the sandbox or gateway state, so it skips inference probing. | - -Local providers (Ollama, vLLM) probe the host-side health endpoint. -Remote providers (NVIDIA Endpoints, OpenAI, Anthropic, Gemini) use a lightweight reachability check; any HTTP response, including `401` or `403`, counts as reachable. -No API keys are sent. - -For Local Ollama, the command also probes the authenticated proxy and prints an `Inference (auth proxy)` line when a proxy token is available. -Use that line to distinguish a healthy backend from a broken proxy path that the sandbox uses for inference. - -For cloud-only providers, the output omits the NIM status line unless a NIM container is registered or an unexpected NIM container is running. - -When the sandbox's recorded driver is `docker` and the host Docker daemon is not reachable, the command prints the `docker_unreachable` failure layer with the message `Docker daemon is not reachable.` as the first line of stdout, suppresses the host-side `Inference` probe (which otherwise hits the remote provider directly and is misleading when the local stack is down), and exits with a non-zero status. - -When the host Docker daemon is reachable but the per-sandbox container is stopped, the command prints the `sandbox_container_stopped` failure layer with the message `sandbox container exists but is not running.` as the first line of stdout, suppresses the host-side `Inference` probe, and exits with a non-zero status. -If the sandbox's recorded dashboard port is also held by a foreign listener, the header escalates to the `sandbox_dashboard_port_conflict` failure layer with the message `sandbox container is stopped and the dashboard port is held by a foreign listener.` so the operator can recover the port before restarting the sandbox. - -If the sandbox or gateway cannot be verified, the command exits non-zero instead of reporting healthy inference from stale registry state. -When a locally registered sandbox is missing from the live gateway, status preserves the registry entry so the suggested `rebuild --yes` recovery can still find the sandbox metadata. -Gateway and dashboard health checks treat HTTP `401` from device auth as a live service, not as an offline gateway. - -When sandbox GPU passthrough is enabled, the `Sandbox GPU` line includes the last CUDA usability proof state. -It reports `(CUDA verified)`, `(CUDA unverified)`, or `(last CUDA proof failed: