From 7e4e6b5ba3594de3a25a927abef0277cbe75d330 Mon Sep 17 00:00:00 2001 From: Miyoung Choi Date: Wed, 3 Jun 2026 15:13:16 -0700 Subject: [PATCH 1/5] docs: expand generated agent variants --- docs/CONTRIBUTING.md | 15 +- docs/about/overview.mdx | 2 +- docs/about/release-notes.mdx | 76 +-- docs/deployment/deploy-to-remote-gpu.mdx | 2 +- docs/get-started/prerequisites.mdx | 10 +- docs/get-started/windows-preparation.mdx | 16 +- docs/index.yml | 98 ++-- docs/inference/inference-options.mdx | 31 +- docs/inference/switch-inference-providers.mdx | 196 ++----- docs/inference/use-local-inference.mdx | 212 +------ docs/manage-sandboxes/backup-restore.mdx | 61 +- docs/manage-sandboxes/lifecycle.mdx | 36 +- docs/manage-sandboxes/messaging-channels.mdx | 206 ++----- docs/manage-sandboxes/runtime-controls.mdx | 42 +- docs/manage-sandboxes/workspace-files.mdx | 14 +- docs/monitoring/monitor-sandbox-activity.mdx | 64 +-- .../customize-network-policy.mdx | 145 +---- .../integration-policy-examples.mdx | 301 ++-------- docs/reference/architecture.mdx | 12 +- docs/reference/cli-selection-guide.mdx | 76 +-- docs/reference/commands-nemohermes.mdx | 2 +- docs/reference/commands.mdx | 532 +++++++++--------- docs/reference/network-policies.mdx | 4 +- docs/reference/troubleshooting.mdx | 202 +++---- docs/security/best-practices.mdx | 6 +- docs/security/credential-storage.mdx | 74 +-- scripts/sync-agent-variant-docs.ts | 188 ++++++- test/agent-variant-docs.test.ts | 16 +- 28 files changed, 957 insertions(+), 1682 deletions(-) diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index 8ec2cad168..8b6e4f90c8 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -145,15 +145,16 @@ Fern `.mdx` pages are the source for generated user skills. Legacy `.md` pages m ## Agent Variant Generation Some Fern pages appear in both the OpenClaw and Hermes guide variants. -When the 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`. +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. +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. -The `scripts/sync-agent-variant-docs.ts` script renders variant-specific pages before Fern validates or publishes the site. -For the sandbox lifecycle guide, the source page remains at `docs/manage-sandboxes/lifecycle.mdx`. -The generated OpenClaw and Hermes pages are written under `docs/_build/agent-variants/`, which is ignored by Git. -Navigation in `docs/index.yml` points Fern at those generated pages so Fern still renders normal fenced code blocks with copy buttons and syntax highlighting. +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`. +Use literal command names on those single-variant pages rather than `$$nemoclaw`, because no generated page will rewrite the placeholder. -Run `npm run docs:sync-agent-variants` after editing a shared variant source page. +Run `npm run docs:sync-agent-variants` after editing shared variant source pages or navigation. Run `npm run docs` before opening a PR to verify the generated pages, rewritten relative links, and Fern navigation. If content differs by behavior, setup flow, state layout, or agent-specific wording, keep using `` blocks for that content. diff --git a/docs/about/overview.mdx b/docs/about/overview.mdx index 4963bfb9b6..04d4174e86 100644 --- a/docs/about/overview.mdx +++ b/docs/about/overview.mdx @@ -83,7 +83,7 @@ Navigate to the following topics to learn more about NemoClaw and how to install - [Architecture Overview](how-it-works) to understand how NemoClaw works. - [Ecosystem](ecosystem-hermes) to understand how Hermes, OpenShell, and NemoClaw relate in the wider stack, and when to use NemoClaw versus OpenShell. -- [Quickstart with Hermes](../get-started/quickstart-hermes) to install NemoClaw and run your first Hermes sandbox with `nemohermes`. +- [Quickstart with Hermes](../get-started/quickstart-hermes) to install NemoClaw and run your first Hermes sandbox with `$$nemoclaw`. - [Agent Skills](../resources/agent-skills) to load NemoClaw guidance into an AI coding assistant. - [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 6bdd017d94..d061ea0358 100644 --- a/docs/about/release-notes.mdx +++ b/docs/about/release-notes.mdx @@ -21,20 +21,20 @@ NemoClaw v0.0.57 improves multi-agent command workflows, local inference setup, - Local inference setup is more observable and more resilient. Managed vLLM on DGX Spark defaults to `nvidia/Qwen3.6-35B-A3B-NVFP4`, streams Hugging Face model-download progress, polls `/v1/models` for readiness, and uses a progress-aware Docker pull watchdog. Local Ollama routes request streaming usage metadata so OpenClaw token counters can update, and `connect` warns when the recorded inference route diverges from the live gateway route instead of reverting silently. For more information, refer to [Use a Local Inference Server](../inference/use-local-inference). - Onboarding and re-onboarding preserve more operator intent. Linux Docker-driver onboarding can auto-apply a narrow UFW rule for the sandbox-to-gateway bridge when `NEMOCLAW_AUTO_FIX_FIREWALL=1`, verifies host-network local-inference reachability before reporting success, reuses healthy containerized gateways, binds gateway state by port, rolls back a freshly-created sandbox when setup is cancelled at the policy preset step, and carries finalized policy preset selections across later re-onboard runs. For more information, refer to [NemoClaw CLI Commands Reference](../reference/commands). - Messaging channel setup fails earlier and leaves fewer partial changes. Slack setup validates both Socket Mode tokens before saving credentials, `channels add` checks the matching built-in policy preset before prompting or persisting channel state, failed preset application rolls back staged bridge changes when possible, WhatsApp pairing renders a compact QR code with clearer gateway diagnostics, and Slack runtime placeholders are normalized before OpenClaw starts. For more information, refer to [Messaging Channels](../manage-sandboxes/messaging-channels). -- Sandbox status and repair output are more actionable. `nemoclaw status` reports Docker daemon, stopped-container, dashboard-port-conflict, and paused-container layers without running misleading inference probes, `doctor` skips stale Kubernetes-only gateway container checks on Docker-driver installs, and stale local registry entries are preserved so the suggested `rebuild --yes` recovery path still has the metadata it needs. For more information, refer to [NemoClaw CLI Commands Reference](../reference/commands). +- Sandbox status and repair output are more actionable. `$$nemoclaw status` reports Docker daemon, stopped-container, dashboard-port-conflict, and paused-container layers without running misleading inference probes, `doctor` skips stale Kubernetes-only gateway container checks on Docker-driver installs, and stale local registry entries are preserved so the suggested `rebuild --yes` recovery path still has the metadata it needs. For more information, refer to [NemoClaw CLI Commands Reference](../reference/commands). - Installer and policy guidance tightened. Piped installs show the correct `NEMOCLAW_INSTALL_TAG` placement and fail clearly when a requested ref is unavailable, the `pypi` preset allows the `uv` package manager binary, and Jira validation now uses a body-visible Atlassian API probe so operators can distinguish blocked and approved curl traffic. For more information, refer to [Common NemoClaw Integration Policy Examples](../network-policy/integration-policy-examples). ## v0.0.56 NemoClaw v0.0.56 improves install safety, local-inference validation, messaging diagnostics, sandbox lifecycle reporting, and day-two command behavior: -- Public installer and `nemoclaw update` flows now follow the admin-promoted `lkg` release tag by default, so curl-piped installs and update checks target the maintained build while validation catches up to newer semver tags. Non-interactive Linux installs can also reactivate Docker group membership through `sg docker` and continue in the same installer run when that path is available. For more information, refer to [Manage Sandbox Lifecycle](../manage-sandboxes/lifecycle). -- `nemoclaw status`, `nemoclaw connect`, and `nemoclaw upgrade-sandboxes` now probe the live sandbox agent version before deciding whether a rebuild is needed, instead of trusting stale host metadata. Status output reports when the version cannot be verified and points at rebuild when the running agent may predate the current install. For more information, refer to [NemoClaw CLI Commands Reference](../reference/commands). +- Public installer and `$$nemoclaw update` flows now follow the admin-promoted `lkg` release tag by default, so curl-piped installs and update checks target the maintained build while validation catches up to newer semver tags. Non-interactive Linux installs can also reactivate Docker group membership through `sg docker` and continue in the same installer run when that path is available. For more information, refer to [Manage Sandbox Lifecycle](../manage-sandboxes/lifecycle). +- `$$nemoclaw status`, `$$nemoclaw connect`, and `$$nemoclaw upgrade-sandboxes` now probe the live sandbox agent version before deciding whether a rebuild is needed, instead of trusting stale host metadata. Status output reports when the version cannot be verified and points at rebuild when the running agent may predate the current install. For more information, refer to [NemoClaw CLI Commands Reference](../reference/commands). - GPU Docker-driver local-inference onboarding now verifies that host-network sandboxes can reach the selected Ollama or vLLM health endpoint before onboarding reports success. Failures now include the provider endpoint, container network mode, and recovery guidance, which avoids discovering the broken route only after the first agent prompt. For more information, refer to [Use a Local Inference Server](../inference/use-local-inference). - Messaging setup is more diagnosable. Slack setup validates both required Slack credentials before enabling the channel, WhatsApp pairing renders a compact scan-friendly QR for OpenClaw sandboxes and separates gateway close errors from QR rendering, and Telegram DM allowlist aliases continue to work for existing automation. For more information, refer to [Messaging Channels](../manage-sandboxes/messaging-channels). -- Command ergonomics are clearer for common day-two paths. `nemoclaw inference set` without both `--provider` and `--model` now points users to the underlying `openshell inference set` command, `nemoclaw skill remove ` removes uploaded skills by `SKILL.md` name, `nemoclaw status --json` supports per-sandbox automation, and `nemoclaw debug --sandbox` validates explicit sandbox names before writing diagnostics. For more information, refer to [NemoClaw CLI Commands Reference](../reference/commands). +- Command ergonomics are clearer for common day-two paths. `$$nemoclaw inference set` without both `--provider` and `--model` now points users to the underlying `openshell inference set` command, `nemoclaw skill remove ` removes uploaded skills by `SKILL.md` name, `$$nemoclaw status --json` supports per-sandbox automation, and `$$nemoclaw debug --sandbox` validates explicit sandbox names before writing diagnostics. For more information, refer to [NemoClaw CLI Commands Reference](../reference/commands). - Policy and sandbox base-image compatibility improved. The `pypi` preset allows the `uv` package manager binary, the sandbox base image includes `tmux` for OpenClaw's bundled tmux-session flow, and Jira preset validation docs now use observable status probes. For more information, refer to [Common NemoClaw Integration Policy Examples](../network-policy/integration-policy-examples). -- Uninstall, rebuild, and snapshot flows protect user state more consistently. `nemoclaw uninstall` preserves host-side backups and the sandbox registry by default, rebuilds preserve explicit CPU-only sandbox intent, and snapshot restore blocks ambiguous existing-destination rollbacks unless you opt in with `--force`. For more information, refer to [Manage Sandbox Lifecycle](../manage-sandboxes/lifecycle). +- Uninstall, rebuild, and snapshot flows protect user state more consistently. `$$nemoclaw uninstall` preserves host-side backups and the sandbox registry by default, rebuilds preserve explicit CPU-only sandbox intent, and snapshot restore blocks ambiguous existing-destination rollbacks unless you opt in with `--force`. For more information, refer to [Manage Sandbox Lifecycle](../manage-sandboxes/lifecycle). ## v0.0.55 @@ -49,9 +49,9 @@ NemoClaw v0.0.55 improves local Ollama onboarding reliability, plugin secret-sca NemoClaw v0.0.54 updates messaging activation, Windows WSL onboarding, NemoHermes dashboard access, and sandbox repair paths: - Generated OpenClaw config now marks Telegram, Discord, Slack, and WhatsApp as enabled at the channel level. Selected messaging plugins are pinned during the image build, and `channels add` verifies Telegram, Discord, and Slack bridge startup after the rebuild instead of leaving silent channel failures for later debugging. For more information, refer to [Messaging Channels](../manage-sandboxes/messaging-channels). -- The Windows bootstrap flow waits for Ubuntu account creation before touching Docker settings, enables Docker Desktop WSL integration for the target distro, avoids changing the global WSL default distro, and adds WSL-specific Docker reachability hints during onboarding. For more information, refer to [Prepare Windows for NemoClaw](../get-started/prerequisites/windows-preparation). +- The Windows bootstrap flow waits for Ubuntu account creation before touching Docker settings, enables Docker Desktop WSL integration for the target distro, avoids changing the global WSL default distro, and adds WSL-specific Docker reachability hints during onboarding. For more information, refer to [Prepare Windows for NemoClaw](../get-started/windows-preparation.mdx). - Windows-host Ollama setup inside WSL now requires the Docker Desktop WSL integration path. NemoClaw still shows Windows-host Ollama options when it detects them, but labels the Docker Desktop requirement and blocks unsupported native Docker-in-WSL selections before it tries to start or install Ollama. For more information, refer to [Use a Local Inference Server](../inference/use-local-inference). -- NemoHermes can expose the optional native Hermes web dashboard separately from the OpenAI-compatible API. Set `NEMOCLAW_HERMES_DASHBOARD=1` before onboarding to start and forward the dashboard on port `9119`, with `NEMOCLAW_HERMES_DASHBOARD_PORT` and `NEMOCLAW_HERMES_DASHBOARD_TUI` available for port and TUI tab control. For more information, refer to [NemoClaw Quickstart with Hermes](../../hermes/get-started/quickstart-hermes). +- NemoHermes can expose the optional native Hermes web dashboard separately from the OpenAI-compatible API. Set `NEMOCLAW_HERMES_DASHBOARD=1` before onboarding to start and forward the dashboard on port `9119`, with `NEMOCLAW_HERMES_DASHBOARD_PORT` and `NEMOCLAW_HERMES_DASHBOARD_TUI` available for port and TUI tab control. For more information, refer to [NemoClaw Quickstart with Hermes](../get-started/quickstart-hermes.mdx). - Onboarding diagnostics include more copy-paste-ready recovery hints. Invalid sandbox names now include a `Try: ` line when NemoClaw can derive a valid name, and non-interactive NVIDIA Endpoints setup prints the exact `export NVIDIA_API_KEY=nvapi-...` shape when the key is missing. For more information, refer to [NemoClaw CLI Commands Reference](../reference/commands). - Homebrew stays on the Linuxbrew prefix while exposing installed formula commands in sandbox shell sessions, the `/nemoclaw` slash command activates at OpenClaw startup again, Hermes rebuilds tolerate older release tarballs that lack optional UI package lockfiles, and device scope-upgrade approvals recover without being pinned to the old gateway-scoped request. For more information, refer to [Common NemoClaw Integration Policy Examples](../network-policy/integration-policy-examples). - The host-gateway allowance for OpenClaw `web_fetch` is confined to the trusted proxy path, while strict and direct paths continue to block host-gateway names. Hermes Provider onboarding skips the host-side smoke probe only for OAuth-backed setup and keeps direct validation for Nous API key setup. For more information, refer to [NemoClaw Inference Options](../inference/inference-options). @@ -75,7 +75,7 @@ NemoClaw v0.0.52 upgrades the bundled OpenClaw runtime, repairs Hermes sandbox s - Bundles OpenClaw 2026.5.22 as the NemoClaw runtime target through `OPENCLAW_VERSION` in the NemoClaw Dockerfiles. The runtime upgrade addresses Telegram, Discord, and Slack channel registration issues seen on the 2026.5.18 runtime. `nemoclaw-blueprint/blueprint.yaml` keeps `min_openclaw_version` as a compatibility floor for direct blueprint consumers, so the blueprint floor can be lower than the Dockerfile target. Run `nemoclaw rebuild` to pick up the new OpenClaw runtime in existing sandboxes. - Hermes sandbox startup is more reliable on the v0.14 root entrypoint. NemoClaw precreates `hooks`, `image_cache`, `audio_cache`, and `logs/curator` under `HERMES_HOME`, makes `/sandbox/.hermes` sticky group-writable so the `gateway` user can create runtime state without removing sandbox-owned config files, stops precreating `/sandbox/.hermes/gateway.pid` as a symlink that Hermes v0.14 treats as a PID race, and clears legacy PID and lock state before launch. -- `nemoclaw onboard` ready output points users at `nemoclaw dashboard-url --quiet` again, restoring the dashboard guidance that regressed during an earlier onboarding refactor. +- `$$nemoclaw onboard` ready output points users at `$$nemoclaw dashboard-url --quiet` again, restoring the dashboard guidance that regressed during an earlier onboarding refactor. - Slack onboarding validates preconfigured Slack tokens before treating Slack as configured. Invalid `SLACK_BOT_TOKEN` values from the environment or stored credentials no longer cause onboarding to skip the Slack prompt, so the wizard re-prompts for a valid `xoxb-...` token instead of silently advancing with a token Slack cannot use. - The Windows bootstrap script defers first-run Ubuntu account setup to a separate WSL handoff window again, which keeps PowerShell prompt alignment intact during install. The default distro is `Ubuntu-24.04`, and `bootstrap-windows.ps1 -DistroName Ubuntu` reuses an existing `Ubuntu` distribution. - The blueprint private-network blocklist reloads when `private-networks.yaml` changes on disk, so long-running NemoClaw processes validate SSRF and private-network rules against the current file instead of stale cached data. @@ -88,9 +88,9 @@ NemoClaw v0.0.51 improves messaging controls, local inference setup, sandbox dia - Local Ollama setup now detects host installations that are below the minimum supported version and offers an explicit upgrade path. On macOS, NemoClaw uses Homebrew. On Linux, NemoClaw uses the system installer for upgrades and refuses non-interactive upgrade paths that would require a hidden sudo prompt. - Non-interactive Linux Ollama setup can use a sudo-free user-local install path when passwordless sudo is unavailable. The docs now describe `NEMOCLAW_OLLAMA_INSTALL_MODE`, the user-local install trade-offs, and the manual `zstd` requirement. - Managed Ollama model selection now uses a memory-aware registry for starter models. If a known bootstrap model does not fit currently available GPU memory, NemoClaw warns and falls back to the largest known model that does fit instead of starting a model that is likely to fail. -- `nemoclaw onboard` restores the managed vLLM menu entry for DGX Spark and DGX Station hosts, which had been hidden after a previous onboard refactor dropped the `gpu.platform` value the vLLM menu builder relies on. -- `nemoclaw resources` and `NEMOCLAW_RESOURCE_PROFILE` expose sandbox CPU and memory profiles. Profiles can be selected during onboarding, and `NEMOCLAW_CPU` or `NEMOCLAW_RAM` can override the selected profile for scripted runs. -- Cloudflare named tunnels are supported through `CLOUDFLARE_TUNNEL_TOKEN`. `nemoclaw tunnel start` passes the token through the environment and expects the named tunnel route to already point at the dashboard port. +- `$$nemoclaw onboard` restores the managed vLLM menu entry for DGX Spark and DGX Station hosts, which had been hidden after a previous onboard refactor dropped the `gpu.platform` value the vLLM menu builder relies on. +- `$$nemoclaw resources` and `NEMOCLAW_RESOURCE_PROFILE` expose sandbox CPU and memory profiles. Profiles can be selected during onboarding, and `NEMOCLAW_CPU` or `NEMOCLAW_RAM` can override the selected profile for scripted runs. +- Cloudflare named tunnels are supported through `CLOUDFLARE_TUNNEL_TOKEN`. `$$nemoclaw tunnel start` passes the token through the environment and expects the named tunnel route to already point at the dashboard port. - Jira policy validation guidance now matches the maintained preset. Use a Node HTTPS status probe for Atlassian API access and an explicit status-only curl probe for `auth.atlassian.com` when validating approved requests manually. - Sandbox logs merge OpenClaw gateway output and OpenShell audit events into one stream, and `--tail` applies once to the merged result so policy denials appear beside gateway logs. - Onboarding recovers more cleanly across host and runtime edge cases, including root-owned config sync directories, stale dashboard port allocation, unreachable Docker daemons, stale dashboard forwards, default NVIDIA CDI spec directories, and Linux Docker-driver health checks. @@ -99,7 +99,7 @@ NemoClaw v0.0.51 improves messaging controls, local inference setup, sandbox dia NemoClaw v0.0.50 focused on onboarding reliability, local inference hardening, messaging diagnostics, and sandbox lifecycle cleanup: -- `nemoclaw onboard` detects DGX Spark hosts where managed Ollama falls back to CPU execution. Local inference setup fails the Ollama validation step with a tailored diagnostic, adds a Spark `OLLAMA_LLM_LIBRARY=cuda_v13` systemd override when that backend is installed, and enables the managed Linux Ollama service so local inference survives reboot. +- `$$nemoclaw onboard` detects DGX Spark hosts where managed Ollama falls back to CPU execution. Local inference setup fails the Ollama validation step with a tailored diagnostic, adds a Spark `OLLAMA_LLM_LIBRARY=cuda_v13` systemd override when that backend is installed, and enables the managed Linux Ollama service so local inference survives reboot. - Compatible endpoint setup rejects `host.docker.internal` inference URLs because OpenShell sandboxes do not have a portable host-service route through that name. Use Local Ollama's authenticated proxy path or a policy-managed host service instead. - Telegram setup now surfaces BotFather group privacy guidance. Disable privacy mode, then remove and re-add the bot to each group before testing group delivery. - Maintenance commands recover the OpenShell gateway before retrying sandbox-list operations, which makes rebuild, recover, upgrade, and backup flows more resilient after gateway drift. @@ -110,13 +110,13 @@ NemoClaw v0.0.50 focused on onboarding reliability, local inference hardening, m NemoClaw v0.0.49 is a hardening release focused on reliability, clearer diagnostics, OpenClaw compatibility, and stronger validation coverage: -- Gateway failures now fail faster and explain more. `nemoclaw status` classifies gateway probe failures by layer, distinguishing a named gateway port that is not accepting connections, a named gateway that is present but not Connected, the active OpenShell gateway pointing at a different name, and a named gateway that is not configured at all. `nemoclaw connect` exits early with recovery guidance when the OpenShell gateway is down. +- Gateway failures now fail faster and explain more. `$$nemoclaw status` classifies gateway probe failures by layer, distinguishing a named gateway port that is not accepting connections, a named gateway that is present but not Connected, the active OpenShell gateway pointing at a different name, and a named gateway that is not configured at all. `$$nemoclaw connect` exits early with recovery guidance when the OpenShell gateway is down. - Gateway upgrade and fallback paths are more stable. The release hardens older gateway fallback coverage, OpenShell gateway upgrade checks, crash-loop detection tests, and Brev GPU bridge gateway traffic coverage. -- Status and doctor now report a fresh mutable sandbox as not configured instead of `down`, and `nemoclaw logs --tail ` is locked in as a NemoClaw line count rather than OpenShell's follow-flag pun. `nemoclaw debug --quick` reports restricted kernel-log access as a skipped section instead of surfacing raw `dmesg` permission errors. +- Status and doctor now report a fresh mutable sandbox as not configured instead of `down`, and `$$nemoclaw logs --tail ` is locked in as a NemoClaw line count rather than OpenShell's follow-flag pun. `$$nemoclaw debug --quick` reports restricted kernel-log access as a skipped section instead of surfacing raw `dmesg` permission errors. - OpenClaw compatibility is more resilient across runtime changes. Kimi mixed tool calls are normalized more consistently, compatible OpenClaw JSON envelope changes are tolerated in tests, and OpenClaw patch drift is easier to classify during image builds. - Messaging channel removal is now a clean teardown. The sandbox registry and onboard session policy preset state stay in sync so removed presets do not return during later `onboard --resume` or rebuild flows; QR-paired channels also have their durable in-sandbox session directory wiped before the rebuild and removal aborts cleanly when that wipe cannot be confirmed; and `~/.nemoclaw/config.json` is re-synced from the host across every rebuild resume path so the OpenClaw plugin no longer crashes on the Dockerfile placeholder. - Hermes sandboxes apply only the messaging channel policies the operator selects instead of pre-enabling every Hermes messaging provider, and dynamic preset application resolves Hermes-specific policy content so Discord on Hermes no longer falls back to generic Node allowlists. -- `nemoclaw snapshot restore --to ` now refuses to overwrite an existing destination unless you pass `--force`, which makes destructive clone restores an explicit opt-in. +- `$$nemoclaw snapshot restore --to ` now refuses to overwrite an existing destination unless you pass `--force`, which makes destructive clone restores an explicit opt-in. - Source-checkout installs bootstrap OpenShell when needed before running preflight, so `git clone` based installs can reach the same managed OpenShell setup path as packaged installs. The Linux installer, onboard preflight, and prerequisites docs also explain why NemoClaw needs Docker group membership and the privilege impact of granting it. - NVIDIA NIM preflight rejects WDDM placeholder GPU names on hosts without NVIDIA firmware, and Jetson onboarding refuses sandbox GPU passthrough instead of creating a configuration the sandbox cannot use. - CLI and E2E coverage cover more real user paths. Missing `channels` arguments now print the correct usage, scenario suites use supported sandbox subcommands, scenario tests build against the full repository CLI, and security-sensitive credential paths have broader coverage. @@ -128,7 +128,7 @@ NemoClaw v0.0.48 improves onboarding, sandbox builds, local inference, messaging - Windows WSL onboarding detects Windows-host Ollama through both the HTTP endpoint and a Windows process probe, so the installer can offer start or restart actions even when the daemon is installed but not yet reachable from WSL. - Onboarding no longer prints a noisy `No active forward found` warning when it performs best-effort dashboard forward cleanup before rebuilding or recovering a sandbox. -- `nemoclaw share mount` verifies the requested remote path against the target sandbox name, so probes for non-default sandboxes no longer accidentally inspect the default sandbox. +- `$$nemoclaw share mount` verifies the requested remote path against the target sandbox name, so probes for non-default sandboxes no longer accidentally inspect the default sandbox. - The OpenClaw plugin tolerates an empty or malformed onboard `config.json` by falling back to default onboard status instead of failing during startup. - Hermes messaging policies are scoped to Hermes-supported channel behavior, keeping unsupported OpenClaw-specific messaging access out of Hermes sandboxes. - Onboard session snapshots persist machine-readable state for resume flows, which makes provider and policy decisions more durable across retries. @@ -156,36 +156,36 @@ NemoClaw v0.0.46 improves Windows setup, messaging channels, Hermes sandboxes, i - Windows users can start from the bootstrap PowerShell script, and WSL installs can accept express install to use the Windows-host Ollama path automatically. - Messaging channels add WhatsApp support. `channels add whatsapp` records the channel, rebuilds the sandbox, and then pairs through the agent-specific QR command inside the sandbox. -- `nemoclaw exec` runs non-interactive commands inside a running sandbox through OpenShell and exits with the remote command's status. +- `$$nemoclaw exec` runs non-interactive commands inside a running sandbox through OpenShell and exits with the remote command's status. - Hermes sandboxes can use the managed tool gateway broker for supported tool routes, and Hermes startup recovers its readiness marker more reliably. - Compatible Anthropic endpoint setup auto-detects Amazon Bedrock Runtime endpoints and starts the local adapter needed for OpenShell routing. - Local Ollama setup on WSL native Docker now routes through NemoClaw's authenticated proxy, and subprocesses inherit the proxy bypass settings used by onboarding. - Model Router setup probes supported host Python interpreters and falls back to the next usable one when virtual environment creation fails. - The NemoClaw OpenClaw plugin registers the `/nemoclaw` command again after package metadata changes, and sandbox extension backups restore compatibility with current snapshots. - Sandbox builds patch OpenClaw's tool catalog to reduce startup latency for Nemotron-focused sandboxes. -- `nemoclaw uninstall` docs now show how to pass flags through the hosted install script form. +- `$$nemoclaw uninstall` docs now show how to pass flags through the hosted install script form. ## v0.0.45 NemoClaw v0.0.45 improves onboarding recovery, local inference behavior, channel cleanup, sandbox sharing diagnostics, and uninstall cleanup: -- `nemoclaw onboard` handles GPU setup failures more directly. It can replace a stale CPU-only gateway when doing so is safe, skips GPU advice when you explicitly pass `--no-gpu`, points working-driver hosts toward NVIDIA Container Toolkit setup, and enforces the 63-character sandbox name limit before names reach OpenShell. +- `$$nemoclaw onboard` handles GPU setup failures more directly. It can replace a stale CPU-only gateway when doing so is safe, skips GPU advice when you explicitly pass `--no-gpu`, points working-driver hosts toward NVIDIA Container Toolkit setup, and enforces the 63-character sandbox name limit before names reach OpenShell. - Preflight checks catch more host setup issues before the sandbox build starts. Container DNS probing uses a fresh `.invalid` lookup so cached DNS answers do not hide blocked resolver egress, and restrictive checkout file modes no longer make model-specific setup manifests unreadable inside the image. - Local inference setup is more predictable. Managed vLLM accepts `NEMOCLAW_VLLM_MODEL` for supported registry slugs and checks Hugging Face tokens before pulling gated models. Ollama-backed sandboxes now enable streamed usage accounting so OpenClaw token counters update after each turn. -- Messaging channel removal is a clean inverse of channel add. `nemoclaw channels remove ` detaches live bridge providers before deleting them and un-applies the matching built-in network policy preset when it was active. -- `nemoclaw share mount` fails earlier with clearer guidance when the sandbox path cannot be verified or the host mount target is on a read-only filesystem. -- `nemoclaw uninstall` stops host `openshell-gateway` processes, and subprocesses add IPv6 loopback plus wildcard local bind addresses to `NO_PROXY` so local traffic stays off forwarded proxies. +- Messaging channel removal is a clean inverse of channel add. `$$nemoclaw channels remove ` detaches live bridge providers before deleting them and un-applies the matching built-in network policy preset when it was active. +- `$$nemoclaw share mount` fails earlier with clearer guidance when the sandbox path cannot be verified or the host mount target is on a read-only filesystem. +- `$$nemoclaw uninstall` stops host `openshell-gateway` processes, and subprocesses add IPv6 loopback plus wildcard local bind addresses to `NO_PROXY` so local traffic stays off forwarded proxies. - Diagnostics and internal command output redact more credential-shaped values and use private temporary directories for generated SSH and config files. ## v0.0.44 NemoClaw v0.0.44 improves onboarding reliability, GPU sandbox networking, local inference verification, messaging recovery, and remote dashboard access: -- `nemoclaw onboard` handles DGX Spark and Jetson hosts more conservatively. Unified-memory GPU detection works for Spark, Jetson defaults to CPU-only sandbox passthrough unless you opt in, and local Ollama validation tolerates slow unified-memory model loads that still fit host memory. +- `$$nemoclaw onboard` handles DGX Spark and Jetson hosts more conservatively. Unified-memory GPU detection works for Spark, Jetson defaults to CPU-only sandbox passthrough unless you opt in, and local Ollama validation tolerates slow unified-memory model loads that still fit host memory. - Linux Docker-driver GPU sandboxes preserve `host.openshell.internal` during recreation and inject a reachable DNS resolver when the host uses a systemd-resolved loopback nameserver, which keeps local inference and external DNS working after GPU patching. - Onboarding and sandbox builds fail less often on first run. Preflight can guide missing NVIDIA Container Toolkit setup, Docker builds force BuildKit for Dockerfile bind mounts, npm installs retry transient registry resets, and compatible-endpoint onboarding runs a final inference smoke check before reporting success. -- `nemoclaw connect` repairs stale `inference.local` routes before opening the shell, reports local Ollama backend and auth-proxy diagnostics when repair fails, and `--probe-only` keeps dashboard and process recovery from failing just because inference repair needs follow-up. -- `nemoclaw channels add ` applies the matching built-in network policy preset before rebuild, and rebuilds preserve paused channel state so stopped messaging channels stay disabled after destroy and recreate. +- `$$nemoclaw connect` repairs stale `inference.local` routes before opening the shell, reports local Ollama backend and auth-proxy diagnostics when repair fails, and `--probe-only` keeps dashboard and process recovery from failing just because inference repair needs follow-up. +- `$$nemoclaw channels add ` applies the matching built-in network policy preset before rebuild, and rebuilds preserve paused channel state so stopped messaging channels stay disabled after destroy and recreate. - Remote hosts can opt into dashboard forwarding on all interfaces with `NEMOCLAW_DASHBOARD_BIND=0.0.0.0`, and gateway drift checks now stop backup, status, rebuild, recover, and upgrade flows before they trust stale OpenShell state. - Workspace restore uploads backed-up directories file by file, dashboard forwards retry while stopped ports are still releasing, and the in-sandbox OpenClaw gateway respawns after unexpected exits. @@ -195,15 +195,15 @@ NemoClaw v0.0.43 improves GPU onboarding and uninstall cleanup on Linux Docker-d - The standard installer can repair missing NVIDIA CDI device specs before onboarding by enabling the NVIDIA CDI refresh service, then falling back to direct `nvidia-ctk` spec generation when needed. - Linux Docker-driver GPU onboarding handles the Docker flags and sandbox policy needed for NVIDIA GPU proof writes to `/proc//task//comm`, which fixes DGX Spark installs that previously failed with a permission error during direct GPU proof. -- `nemoclaw uninstall` removes the Linux gateway state directory under `~/.local/state/nemoclaw`, including gateway PID, SQLite, audit log, and VM-driver state left by Docker-driver gateways. +- `$$nemoclaw uninstall` removes the Linux gateway state directory under `~/.local/state/nemoclaw`, including gateway PID, SQLite, audit log, and VM-driver state left by Docker-driver gateways. ## v0.0.42 NemoClaw v0.0.42 improves onboarding, status diagnostics, local inference checks, and messaging setup: -- `nemoclaw onboard` uses the Docker-driver OpenShell gateway path on macOS and no longer requires VM driver helper assets for standard macOS onboarding. +- `$$nemoclaw onboard` uses the Docker-driver OpenShell gateway path on macOS and no longer requires VM driver helper assets for standard macOS onboarding. - Dashboard port selection probes occupied ports more thoroughly, including root-owned listeners on macOS, and rolls back a newly-created sandbox if the dashboard forward cannot start after the image build. -- `nemoclaw status` shows `Inference` and `Connected` fields for each listed sandbox, and cloudflared service output now distinguishes stopped, invalid PID file, and stale PID states with a `nemoclaw tunnel start` recovery hint. +- `$$nemoclaw status` shows `Inference` and `Connected` fields for each listed sandbox, and cloudflared service output now distinguishes stopped, invalid PID file, and stale PID states with a `$$nemoclaw tunnel start` recovery hint. - Local Ollama status and doctor checks now probe the authenticated proxy in addition to the backend, so a broken proxy is reported separately from a healthy `127.0.0.1:11434` backend. - Compatible OpenAI endpoint validation retries reasoning-only smoke responses with a larger output budget before classifying the setup as a model output budget problem instead of a route failure. - `channels add` and `channels remove` normalize channel names before saving or rebuilding, and `channels add` hints when a matching built-in policy preset exists but is not applied yet. @@ -215,23 +215,23 @@ NemoClaw v0.0.42 improves onboarding, status diagnostics, local inference checks NemoClaw v0.0.41 improves Docker-driver onboarding and release compatibility: -- `nemoclaw onboard` can pin fresh OpenShell installs to a published release that fits the blueprint's tested version range, while retaining the installer fallback when release metadata is unavailable. +- `$$nemoclaw onboard` can pin fresh OpenShell installs to a published release that fits the blueprint's tested version range, while retaining the installer fallback when release metadata is unavailable. - Docker-driver gateway startup verifies that sandbox containers can reach `host.openshell.internal` before reporting the gateway healthy, and Linux firewall failures include a targeted `ufw` remediation. - Local Ollama setup probes sandbox-to-proxy reachability before it commits the inference route, so blocked `11435` traffic stops onboarding with a rerun-safe fix instead of leaving a broken route. - Linux Docker-driver GPU onboarding can recreate the OpenShell-managed sandbox container with NVIDIA GPU access and leaves diagnostics plus cleanup guidance when GPU readiness fails. -- `nemoclaw uninstall` removes all installer-managed OpenShell helper binaries unless you pass `--keep-openshell`. +- `$$nemoclaw uninstall` removes all installer-managed OpenShell helper binaries unless you pass `--keep-openshell`. ## v0.0.40 NemoClaw v0.0.40 improves onboarding reliability, local inference setup, and sandbox recovery: -- `nemoclaw onboard` uses the Docker-driver OpenShell gateway path on macOS with OpenShell 0.0.37, repairs incomplete Docker-driver installs before startup, and installs the platform-specific gateway asset it needs. +- `$$nemoclaw onboard` uses the Docker-driver OpenShell gateway path on macOS with OpenShell 0.0.37, repairs incomplete Docker-driver installs before startup, and installs the platform-specific gateway asset it needs. - The Docker-driver gateway startup check waits for the gateway port to accept TCP connections before it reports the gateway as healthy, and startup failures now include child process exit details. - Local Ollama setup requires the authenticated reverse proxy token on every native Ollama API route, including `GET /api/tags`. - The Linux Ollama install path preflights `zstd` before running the official installer and explains why each sudo-backed setup step needs elevated privileges. - The onboarding provider menu offers an already-running local vLLM server directly when `localhost:8000` responds. Managed vLLM install and start options now appear by default on DGX Spark and DGX Station, while generic Linux NVIDIA GPU hosts remain behind the experimental opt-in. - Policy tier defaults are filtered by active agent support, so presets such as Brave Search are not reapplied to agents that do not support that integration. -- `nemoclaw connect` checks dashboard forward reachability with a TCP probe before it reports a forward as stale. +- `$$nemoclaw connect` checks dashboard forward reachability with a TCP probe before it reports a forward as stale. - Sandbox startup captures a known-good OpenClaw config baseline and restores it on restart if `/sandbox/.openclaw/openclaw.json` becomes empty. - The NemoClaw OpenClaw plugin package declares compatibility metadata for OpenClaw package tooling. @@ -243,10 +243,10 @@ NemoClaw v0.0.39 improves several day-two workflows: - DGX Spark and DGX Station users can accept an express install prompt that preselects the local inference path and suggested policy defaults. - NemoClaw now creates GPU-capable OpenShell Docker sandboxes by default when an NVIDIA GPU is available, with explicit `--sandbox-gpu`, `--no-sandbox-gpu`, and `--sandbox-gpu-device` controls. - `nemohermes` supports Hermes Provider onboarding and runtime model switches through `nemohermes inference set`. -- `nemoclaw hosts-add`, `hosts-list`, and `hosts-remove` manage sandbox host aliases for LAN-only services. -- `nemoclaw update` checks and runs the maintained installer flow, while `nemoclaw upgrade-sandboxes` remains responsible for rebuilding existing sandboxes. -- `nemoclaw destroy` preserves the shared gateway by default unless `--cleanup-gateway` is selected. -- `nemoclaw connect` repairs stale `inference.local` DNS proxy routes before opening the session. +- `$$nemoclaw hosts-add`, `hosts-list`, and `hosts-remove` manage sandbox host aliases for LAN-only services. +- `$$nemoclaw update` checks and runs the maintained installer flow, while `$$nemoclaw upgrade-sandboxes` remains responsible for rebuilding existing sandboxes. +- `$$nemoclaw destroy` preserves the shared gateway by default unless `--cleanup-gateway` is selected. +- `$$nemoclaw connect` repairs stale `inference.local` DNS proxy routes before opening the session. - Windows-host Ollama onboarding relaunches the daemon with the reachable binding after install or restart. - Local NVIDIA NIM onboarding passes `NGC_API_KEY` or `NVIDIA_API_KEY` into the managed container without putting the secret in process arguments, detects early container exits during health checks, and prints a per-GPU preflight breakdown on mixed-model hosts. - The sandbox startup path strips additional Linux capabilities before and during privilege step-down. @@ -257,8 +257,8 @@ NemoClaw v0.0.39 improves several day-two workflows: NemoClaw v0.0.38 improves several day-two workflows: -- `nemoclaw status` shows the gateway's active policy version in the displayed policy YAML when OpenShell reports one. -- `nemoclaw uninstall` stops matching Local Ollama auth proxy processes before it removes `~/.nemoclaw`, which prevents stale listeners from blocking a later reinstall. +- `$$nemoclaw status` shows the gateway's active policy version in the displayed policy YAML when OpenShell reports one. +- `$$nemoclaw uninstall` stops matching Local Ollama auth proxy processes before it removes `~/.nemoclaw`, which prevents stale listeners from blocking a later reinstall. - Local Ollama onboarding validates structured chat-completions tool calls and rejects models that leak tool-call payloads as plain text. - Blueprint policy additions under `components.policy.additions` are validated, merged into the live policy, applied through OpenShell, and recorded in run metadata. - Rebuild backups tolerate partial archive output when usable data was produced, then report only the manifest-defined paths that could not be archived. diff --git a/docs/deployment/deploy-to-remote-gpu.mdx b/docs/deployment/deploy-to-remote-gpu.mdx index 6ab522d291..65a2388f8c 100644 --- a/docs/deployment/deploy-to-remote-gpu.mdx +++ b/docs/deployment/deploy-to-remote-gpu.mdx @@ -147,4 +147,4 @@ nemoclaw deploy - [Set Up Messaging Channels](../manage-sandboxes/messaging-channels) to connect Telegram, Discord, or Slack through OpenShell-managed channel messaging. - [Monitor Sandbox Activity](../monitoring/monitor-sandbox-activity) for sandbox monitoring tools. -- [Commands](../reference/commands) for the full `deploy` command reference. +- [`nemoclaw deploy`](../reference/commands#nemoclaw-deploy) for the full `deploy` command reference. diff --git a/docs/get-started/prerequisites.mdx b/docs/get-started/prerequisites.mdx index 7d90b9d6e4..8688d5c015 100644 --- a/docs/get-started/prerequisites.mdx +++ b/docs/get-started/prerequisites.mdx @@ -51,12 +51,12 @@ On macOS, NemoClaw uses the Docker-driver OpenShell gateway path with Docker Des You do not need to install or sign a separate OpenShell VM driver helper for standard macOS onboarding. -For NemoClaw-managed environments, use `nemoclaw 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 `nemoclaw onboard`. +For NemoClaw-managed environments, use `$$nemoclaw 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 `$$nemoclaw onboard`. -On Linux hosts running Docker 26 or later with the [containerd image store](https://docs.docker.com/engine/storage/containerd/) enabled (the install-time default for fresh `docker-ce` installations on Ubuntu 24.04 and similar distros), `nemoclaw onboard` transparently builds a `fuse-overlayfs`-enabled cluster image to bypass a kernel-level nested-overlay limitation in k3s. +On Linux hosts running Docker 26 or later with the [containerd image store](https://docs.docker.com/engine/storage/containerd/) enabled (the install-time default for fresh `docker-ce` installations on Ubuntu 24.04 and similar distros), `$$nemoclaw onboard` transparently builds a `fuse-overlayfs`-enabled cluster image to bypass 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. @@ -72,12 +72,12 @@ The table comes from [`ci/platform-matrix.json`](https://github.com/NVIDIA/NemoC |----|-------------------|--------|-------| | Linux | Docker | Tested | Primary tested path. | | macOS (Apple Silicon) | Colima, Docker Desktop | Tested with limitations | Install Xcode Command Line Tools (`xcode-select --install`) and start the runtime before running the installer. | -| DGX Spark | Docker | Tested | Use the standard installer and `nemoclaw onboard`. For an end-to-end walkthrough with local Ollama inference, see the [NVIDIA Spark playbook](https://build.nvidia.com/spark/nemoclaw). | +| DGX Spark | Docker | Tested | Use the standard installer and `$$nemoclaw onboard`. For an end-to-end walkthrough with local Ollama inference, see the [NVIDIA Spark playbook](https://build.nvidia.com/spark/nemoclaw). | | Windows WSL2 | Docker Desktop (WSL backend) | Tested with limitations | Requires WSL2 with Docker Desktop backend. | {/* platform-matrix:end */} ## Next Steps -- [Prepare Windows for NemoClaw](prerequisites/windows-preparation) if you are using Windows. +- [Prepare Windows for NemoClaw](windows-preparation.mdx) if you are using Windows. - [Quickstart](quickstart) to install NemoClaw and launch your first sandbox. - [Agent Skills](../resources/agent-skills) to load NemoClaw guidance into an AI coding assistant before setup. diff --git a/docs/get-started/windows-preparation.mdx b/docs/get-started/windows-preparation.mdx index 993b7be7b8..44ad2b8e97 100644 --- a/docs/get-started/windows-preparation.mdx +++ b/docs/get-started/windows-preparation.mdx @@ -13,10 +13,10 @@ import { AgentOnly } from "../_components/AgentGuide"; You can run NemoClaw inside Windows Subsystem for Linux (WSL 2) on Windows. -Complete these steps before following the [Quickstart](../quickstart). +Complete these steps before following the [Quickstart](quickstart.mdx). -Complete these steps before following [Quickstart with Hermes](../quickstart-hermes). +Complete these steps before following [Quickstart with Hermes](quickstart-hermes.mdx). Linux and macOS users do not need this page and can go directly to the Quickstart. @@ -31,12 +31,12 @@ Verify the following before you begin: - Windows 10 (build 19041 or later) or Windows 11. -- Hardware requirements are the same as the [Quickstart](../quickstart). +- Hardware requirements are the same as the [Quickstart](quickstart.mdx). -- Hardware requirements are the same as [Quickstart with Hermes](../quickstart-hermes). +- Hardware requirements are the same as [Quickstart with Hermes](quickstart-hermes.mdx). @@ -157,21 +157,21 @@ During onboarding, NemoClaw can use an already-running Windows-host daemon, star If the installer offers express install on WSL, accepting it selects this Windows-host Ollama path automatically. When Ollama runs on the Windows host, NemoClaw detects it from WSL through `host.docker.internal` and pulls missing models through the Ollama HTTP API. Do not run both the Windows and WSL Ollama instances on port `11434` at the same time. -Use one instance, or move one of them to a different port before running `nemoclaw onboard`. +Use one instance, or move one of them to a different port before running `$$nemoclaw onboard`. ## Next Step Your Windows environment is ready. If you used the bootstrap script, follow the installer command it printed inside Ubuntu. -If you prepared Windows manually, open a WSL terminal (type `wsl` in PowerShell, or open Ubuntu from Windows Terminal) and continue with the [Quickstart](../quickstart) to install NemoClaw and launch your first sandbox. +If you prepared Windows manually, open a WSL terminal (type `wsl` in PowerShell, or open Ubuntu from Windows Terminal) and continue with the [Quickstart](quickstart.mdx) to install NemoClaw and launch your first sandbox. -If you prepared Windows manually, open a WSL terminal (type `wsl` in PowerShell, or open Ubuntu from Windows Terminal) and continue with [Quickstart with Hermes](../quickstart-hermes) to install NemoClaw and launch your first Hermes sandbox. +If you prepared Windows manually, open a WSL terminal (type `wsl` in PowerShell, or open Ubuntu from Windows Terminal) and continue with [Quickstart with Hermes](quickstart-hermes.mdx) to install NemoClaw and launch your first Hermes sandbox. All NemoClaw commands run inside WSL, not in PowerShell. ## Troubleshooting -For Windows-specific troubleshooting, refer to the [Windows Subsystem for Linux section](../../reference/troubleshooting#windows-subsystem-for-linux) in the Troubleshooting guide. +For Windows-specific troubleshooting, refer to the [Windows Subsystem for Linux section](../reference/troubleshooting.mdx#windows-subsystem-for-linux) in the Troubleshooting guide. diff --git a/docs/index.yml b/docs/index.yml index 6c6e58b446..180dd59090 100644 --- a/docs/index.yml +++ b/docs/index.yml @@ -22,27 +22,27 @@ navigation: collapsed: open-by-default contents: - page: "Overview" - path: about/overview.mdx + path: _build/agent-variants/about/overview.openclaw.generated.mdx slug: overview - page: "Architecture Overview" - path: about/how-it-works.mdx + path: _build/agent-variants/about/how-it-works.openclaw.generated.mdx slug: how-it-works - page: "Ecosystem" path: about/ecosystem.mdx slug: ecosystem - page: "Release Notes" - path: about/release-notes.mdx + path: _build/agent-variants/about/release-notes.openclaw.generated.mdx slug: release-notes - section: "Get Started" slug: get-started collapsed: open-by-default contents: - section: "Prerequisites" - path: get-started/prerequisites.mdx + path: _build/agent-variants/get-started/prerequisites.openclaw.generated.mdx slug: prerequisites contents: - page: "(Windows Only) Windows Prerequisites" - path: get-started/windows-preparation.mdx + path: _build/agent-variants/get-started/windows-preparation.openclaw.generated.mdx slug: windows-preparation - page: "Quickstart with OpenClaw" path: get-started/quickstart.mdx @@ -52,16 +52,16 @@ navigation: collapsed: open-by-default contents: - page: "Inference Options" - path: inference/inference-options.mdx + path: _build/agent-variants/inference/inference-options.openclaw.generated.mdx slug: inference-options - page: "Use Local Inference" - path: inference/use-local-inference.mdx + path: _build/agent-variants/inference/use-local-inference.openclaw.generated.mdx slug: use-local-inference - page: "Tool-Calling Reliability" path: inference/tool-calling-reliability.mdx slug: tool-calling-reliability - page: "Switch Inference Providers" - path: inference/switch-inference-providers.mdx + path: _build/agent-variants/inference/switch-inference-providers.openclaw.generated.mdx slug: switch-inference-providers - page: "Set Up Task-Specific Sub-Agents" path: inference/set-up-sub-agent.mdx @@ -74,16 +74,16 @@ navigation: path: _build/agent-variants/manage-sandboxes/lifecycle.openclaw.generated.mdx slug: lifecycle - page: "Runtime Controls" - path: manage-sandboxes/runtime-controls.mdx + path: _build/agent-variants/manage-sandboxes/runtime-controls.openclaw.generated.mdx slug: runtime-controls - page: "Set Up Messaging Channels" - path: manage-sandboxes/messaging-channels.mdx + path: _build/agent-variants/manage-sandboxes/messaging-channels.openclaw.generated.mdx slug: messaging-channels - page: "Workspace Files" - path: manage-sandboxes/workspace-files.mdx + path: _build/agent-variants/manage-sandboxes/workspace-files.openclaw.generated.mdx slug: workspace-files - page: "Backup and Restore" - path: manage-sandboxes/backup-restore.mdx + path: _build/agent-variants/manage-sandboxes/backup-restore.openclaw.generated.mdx slug: backup-restore - page: "Install OpenClaw Plugins" path: deployment/install-openclaw-plugins.mdx @@ -96,13 +96,13 @@ navigation: collapsed: open-by-default contents: - page: "Approve or Deny Network Requests" - path: network-policy/approve-network-requests.mdx + path: _build/agent-variants/network-policy/approve-network-requests.openclaw.generated.mdx slug: approve-network-requests - page: "Customize the Network Policy" - path: network-policy/customize-network-policy.mdx + path: _build/agent-variants/network-policy/customize-network-policy.openclaw.generated.mdx slug: customize-network-policy - page: "Integration Policy Examples" - path: network-policy/integration-policy-examples.mdx + path: _build/agent-variants/network-policy/integration-policy-examples.openclaw.generated.mdx slug: integration-policy-examples - section: "Deployment" slug: deployment @@ -119,17 +119,17 @@ navigation: collapsed: open-by-default contents: - page: "Monitor Sandbox Activity" - path: monitoring/monitor-sandbox-activity.mdx + path: _build/agent-variants/monitoring/monitor-sandbox-activity.openclaw.generated.mdx slug: monitor-sandbox-activity - section: "Security" slug: security collapsed: open-by-default contents: - page: "Security Best Practices" - path: security/best-practices.mdx + path: _build/agent-variants/security/best-practices.openclaw.generated.mdx slug: best-practices - page: "Credential Storage" - path: security/credential-storage.mdx + path: _build/agent-variants/security/credential-storage.openclaw.generated.mdx slug: credential-storage - page: "OpenClaw Controls" path: security/openclaw-controls.mdx @@ -139,31 +139,31 @@ navigation: collapsed: open-by-default contents: - page: "Architecture Details" - path: reference/architecture.mdx + path: _build/agent-variants/reference/architecture.openclaw.generated.mdx slug: architecture - page: "CLI Commands Reference" - path: reference/commands.mdx + path: _build/agent-variants/reference/commands.openclaw.generated.mdx slug: commands - page: "CLI Selection Guide" - path: reference/cli-selection-guide.mdx + path: _build/agent-variants/reference/cli-selection-guide.openclaw.generated.mdx slug: cli-selection-guide - page: "Network Policies" - path: reference/network-policies.mdx + path: _build/agent-variants/reference/network-policies.openclaw.generated.mdx slug: network-policies - page: "Troubleshooting" - path: reference/troubleshooting.mdx + path: _build/agent-variants/reference/troubleshooting.openclaw.generated.mdx slug: troubleshooting - section: "Resources" slug: resources collapsed: open-by-default contents: - page: "Agent Skills" - path: resources/agent-skills.mdx + path: _build/agent-variants/resources/agent-skills.openclaw.generated.mdx slug: agent-skills - link: "Report Vulnerabilities" href: https://github.com/NVIDIA/NemoClaw/blob/main/SECURITY.md - page: "License" - path: resources/license.mdx + path: _build/agent-variants/resources/license.openclaw.generated.mdx slug: license - link: "Discord" href: https://discord.gg/XFpfPv9Uvx @@ -179,27 +179,27 @@ navigation: collapsed: open-by-default contents: - page: "Overview" - path: about/overview.mdx + path: _build/agent-variants/about/overview.hermes.generated.mdx slug: overview - page: "Architecture Overview" - path: about/how-it-works.mdx + path: _build/agent-variants/about/how-it-works.hermes.generated.mdx slug: how-it-works - page: "Ecosystem" path: about/ecosystem-hermes.mdx slug: ecosystem - page: "Release Notes" - path: about/release-notes.mdx + path: _build/agent-variants/about/release-notes.hermes.generated.mdx slug: release-notes - section: "Get Started" slug: get-started collapsed: open-by-default contents: - section: "Prerequisites" - path: get-started/prerequisites.mdx + path: _build/agent-variants/get-started/prerequisites.hermes.generated.mdx slug: prerequisites contents: - page: "(Windows Only) Windows Prerequisites" - path: get-started/windows-preparation.mdx + path: _build/agent-variants/get-started/windows-preparation.hermes.generated.mdx slug: windows-preparation - page: "Quickstart with Hermes" path: get-started/quickstart-hermes.mdx @@ -209,13 +209,13 @@ navigation: collapsed: open-by-default contents: - page: "Inference Options" - path: inference/inference-options.mdx + path: _build/agent-variants/inference/inference-options.hermes.generated.mdx slug: inference-options - page: "Use Local Inference" - path: inference/use-local-inference.mdx + path: _build/agent-variants/inference/use-local-inference.hermes.generated.mdx slug: use-local-inference - page: "Switch Inference Providers" - path: inference/switch-inference-providers.mdx + path: _build/agent-variants/inference/switch-inference-providers.hermes.generated.mdx slug: switch-inference-providers - section: "Manage Sandboxes" slug: manage-sandboxes @@ -225,16 +225,16 @@ navigation: path: _build/agent-variants/manage-sandboxes/lifecycle.hermes.generated.mdx slug: lifecycle - page: "Runtime Controls" - path: manage-sandboxes/runtime-controls.mdx + path: _build/agent-variants/manage-sandboxes/runtime-controls.hermes.generated.mdx slug: runtime-controls - page: "Set Up Messaging Channels" - path: manage-sandboxes/messaging-channels.mdx + path: _build/agent-variants/manage-sandboxes/messaging-channels.hermes.generated.mdx slug: messaging-channels - page: "Workspace Files" - path: manage-sandboxes/workspace-files.mdx + path: _build/agent-variants/manage-sandboxes/workspace-files.hermes.generated.mdx slug: workspace-files - page: "Backup and Restore" - path: manage-sandboxes/backup-restore.mdx + path: _build/agent-variants/manage-sandboxes/backup-restore.hermes.generated.mdx slug: backup-restore - page: "Install Hermes Plugins" path: manage-sandboxes/install-plugins-hermes.mdx @@ -244,61 +244,61 @@ navigation: collapsed: open-by-default contents: - page: "Approve or Deny Network Requests" - path: network-policy/approve-network-requests.mdx + path: _build/agent-variants/network-policy/approve-network-requests.hermes.generated.mdx slug: approve-network-requests - page: "Customize the Network Policy" - path: network-policy/customize-network-policy.mdx + path: _build/agent-variants/network-policy/customize-network-policy.hermes.generated.mdx slug: customize-network-policy - page: "Integration Policy Examples" - path: network-policy/integration-policy-examples.mdx + path: _build/agent-variants/network-policy/integration-policy-examples.hermes.generated.mdx slug: integration-policy-examples - section: "Monitoring" slug: monitoring collapsed: open-by-default contents: - page: "Monitor Sandbox Activity" - path: monitoring/monitor-sandbox-activity.mdx + path: _build/agent-variants/monitoring/monitor-sandbox-activity.hermes.generated.mdx slug: monitor-sandbox-activity - section: "Security" slug: security collapsed: open-by-default contents: - page: "Security Best Practices" - path: security/best-practices.mdx + path: _build/agent-variants/security/best-practices.hermes.generated.mdx slug: best-practices - page: "Credential Storage" - path: security/credential-storage.mdx + path: _build/agent-variants/security/credential-storage.hermes.generated.mdx slug: credential-storage - section: "Reference" slug: reference collapsed: open-by-default contents: - page: "Architecture Details" - path: reference/architecture.mdx + path: _build/agent-variants/reference/architecture.hermes.generated.mdx slug: architecture - page: "CLI Commands Reference" path: reference/commands-nemohermes.mdx slug: commands - page: "CLI Selection Guide" - path: reference/cli-selection-guide.mdx + path: _build/agent-variants/reference/cli-selection-guide.hermes.generated.mdx slug: cli-selection-guide - page: "Network Policies" - path: reference/network-policies.mdx + path: _build/agent-variants/reference/network-policies.hermes.generated.mdx slug: network-policies - page: "Troubleshooting" - path: reference/troubleshooting.mdx + path: _build/agent-variants/reference/troubleshooting.hermes.generated.mdx slug: troubleshooting - section: "Resources" slug: resources collapsed: open-by-default contents: - page: "Agent Skills" - path: resources/agent-skills.mdx + path: _build/agent-variants/resources/agent-skills.hermes.generated.mdx slug: agent-skills - link: "Report Vulnerabilities" href: https://github.com/NVIDIA/NemoClaw/blob/main/SECURITY.md - page: "License" - path: resources/license.mdx + path: _build/agent-variants/resources/license.hermes.generated.mdx slug: license - link: "Discord" href: https://discord.gg/XFpfPv9Uvx diff --git a/docs/inference/inference-options.mdx b/docs/inference/inference-options.mdx index fe6a1bb780..9c5012c5cb 100644 --- a/docs/inference/inference-options.mdx +++ b/docs/inference/inference-options.mdx @@ -16,12 +16,12 @@ During onboarding, the NemoClaw onboarding wizard presents a numbered list of pr Your selection determines where NemoClaw routes the agent's inference traffic. -For OpenClaw onboarding, use `nemoclaw onboard`. +For OpenClaw onboarding, use `$$nemoclaw onboard`. The provider flow is the same, with the NVIDIA Endpoints route available for OpenClaw Agent. -For Hermes onboarding, use `nemohermes onboard`. +For Hermes onboarding, use `$$nemoclaw onboard`. The provider flow is the same, with the Hermes Provider route available for Hermes Agent. @@ -137,17 +137,9 @@ The sandbox never sees raw API keys. To use the router in scripted setup, set: - ```bash -NEMOCLAW_PROVIDER=routed NVIDIA_API_KEY= nemoclaw onboard --non-interactive +NEMOCLAW_PROVIDER=routed NVIDIA_API_KEY= $$nemoclaw onboard --non-interactive ``` - - - -```bash -NEMOCLAW_PROVIDER=routed NVIDIA_API_KEY= nemohermes onboard --non-interactive -``` - ### Host Python Requirement @@ -160,24 +152,11 @@ NemoClaw probes `python3.13`, `python3.12`, `python3.11`, `python3.10`, and bare If no candidate qualifies, onboarding aborts and prints the real failure for each candidate. This surfaces issues like Homebrew `python@3.14` whose `pyexpat` extension fails to dlopen against the older system `libexpat` on macOS. - -To pin a specific interpreter, set `NEMOCLAW_MODEL_ROUTER_PYTHON` to its absolute path before running `nemoclaw onboard`: - - -To pin a specific interpreter, set `NEMOCLAW_MODEL_ROUTER_PYTHON` to its absolute path before running `nemohermes onboard`: - - - -```bash -NEMOCLAW_MODEL_ROUTER_PYTHON=/opt/homebrew/bin/python3.12 nemoclaw onboard -``` - +To pin a specific interpreter, set `NEMOCLAW_MODEL_ROUTER_PYTHON` to its absolute path before running `$$nemoclaw onboard`: - ```bash -NEMOCLAW_MODEL_ROUTER_PYTHON=/opt/homebrew/bin/python3.12 nemohermes onboard +NEMOCLAW_MODEL_ROUTER_PYTHON=/opt/homebrew/bin/python3.12 $$nemoclaw onboard ``` - The pin is strict. NemoClaw probes only that interpreter and aborts with the failure reason if it does not qualify, rather than silently falling back to a different python on `PATH`. diff --git a/docs/inference/switch-inference-providers.mdx b/docs/inference/switch-inference-providers.mdx index d37bc28d10..1f70e5b129 100644 --- a/docs/inference/switch-inference-providers.mdx +++ b/docs/inference/switch-inference-providers.mdx @@ -24,16 +24,16 @@ You do not need to restart the sandbox. ## Switch to a Different Model -Use `nemoclaw inference set` with the provider and model that match the upstream you want to use. +Use `$$nemoclaw inference set` with the provider and model that match the upstream you want to use. The command updates the OpenShell inference route and synchronizes the running agent config. For OpenClaw, it updates `agents.defaults.model.primary` and the matching provider namespace. -Use `nemohermes inference set` with the provider and model that match the upstream you want to use. +Use `$$nemoclaw inference set` with the provider and model that match the upstream you want to use. 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`, and `model.provider: custom`) without rebuilding or restarting Hermes. Pass `--sandbox ` when you do not want to use the default registered sandbox. -Under `nemohermes`, pass `--sandbox ` when you have registered more than one Hermes sandbox. +Under `$$nemoclaw`, pass `--sandbox ` when you have registered more than one Hermes sandbox. @@ -42,83 +42,40 @@ Pass `--sandbox ` when you do not want to use the default registered sandb ### NVIDIA Endpoints - ```bash -nemoclaw inference set --provider nvidia-prod --model nvidia/nemotron-3-super-120b-a12b +$$nemoclaw inference set --provider nvidia-prod --model nvidia/nemotron-3-super-120b-a12b ``` - - -```bash -nemohermes inference set --provider nvidia-prod --model nvidia/nemotron-3-super-120b-a12b -``` - ### OpenAI - ```bash -nemoclaw inference set --provider openai-api --model gpt-5.4 +$$nemoclaw inference set --provider openai-api --model gpt-5.4 ``` - - -```bash -nemohermes inference set --provider openai-api --model gpt-5.4 -``` - ### Anthropic - -```bash -nemoclaw inference set --provider anthropic-prod --model claude-sonnet-4-6 -``` - - ```bash -nemohermes inference set --provider anthropic-prod --model claude-sonnet-4-6 +$$nemoclaw inference set --provider anthropic-prod --model claude-sonnet-4-6 ``` - ### Google Gemini - -```bash -nemoclaw inference set --provider gemini-api --model gemini-2.5-flash -``` - - ```bash -nemohermes inference set --provider gemini-api --model gemini-2.5-flash +$$nemoclaw inference set --provider gemini-api --model gemini-2.5-flash ``` - ### Compatible Endpoints If you onboarded a custom compatible endpoint, switch models with the provider created for that endpoint: - - ```bash -nemoclaw inference set --provider compatible-endpoint --model +$$nemoclaw inference set --provider compatible-endpoint --model ``` ```bash -nemoclaw inference set --provider compatible-anthropic-endpoint --model +$$nemoclaw inference set --provider compatible-anthropic-endpoint --model ``` - - - -```bash -nemohermes inference set --provider compatible-endpoint --model -``` - -```bash -nemohermes inference set --provider compatible-anthropic-endpoint --model -``` - - - ### Hermes Provider @@ -126,7 +83,7 @@ nemohermes inference set --provider compatible-anthropic-endpoint --model @@ -136,67 +93,47 @@ nemohermes inference set --provider hermes-provider --model openai/gpt-5.4-mini 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. This can happen when the backend does not emit the streaming events OpenClaw requires. - -```bash -nemoclaw onboard -``` - - ```bash -nemohermes onboard +$$nemoclaw onboard ``` - Select the same provider and endpoint again. The updated streaming probe detects incomplete `/v1/responses` support and selects `/v1/chat/completions` automatically. For the compatible-endpoint provider, NemoClaw uses `/v1/chat/completions` by default, so you do not need an environment variable to keep the safe path. To opt in to `/v1/responses` for a backend you have verified end to end, set `NEMOCLAW_PREFERRED_API` before onboarding: - ```bash -NEMOCLAW_PREFERRED_API=openai-responses nemoclaw onboard +NEMOCLAW_PREFERRED_API=openai-responses $$nemoclaw onboard ``` - - -```bash -NEMOCLAW_PREFERRED_API=openai-responses nemohermes onboard -``` - `NEMOCLAW_INFERENCE_API_OVERRIDE` patches the config at container startup but does not update the Dockerfile ARG baked into the image. If you recreate the sandbox without the override environment variable, the image reverts to the original API path. - -A fresh `nemoclaw onboard` is the reliable fix because it updates both the -session and the baked image. - - -A fresh `nemohermes onboard` is the reliable fix because it updates both the +A fresh `$$nemoclaw onboard` is the reliable fix because it updates both the session and the baked image. - ## Cross-Provider Switching -Switching to a different provider family (for example, from NVIDIA Endpoints to Anthropic) also uses `nemoclaw inference set`. +Switching to a different provider family (for example, from NVIDIA Endpoints to Anthropic) also uses `$$nemoclaw inference set`. The command updates both the gateway route and the OpenClaw provider namespace in the running sandbox config. If the in-sandbox config sync fails after the gateway route is updated, NemoClaw keeps the host registry aligned with the gateway and prints a rebuild hint. Run the rebuild before relying on the running agent if the warning says the image config could not be patched. ```bash -nemoclaw inference set --provider anthropic-prod --model claude-sonnet-4-6 --no-verify +$$nemoclaw inference set --provider anthropic-prod --model claude-sonnet-4-6 --no-verify ``` -Switching to a different provider family (for example, from NVIDIA Endpoints to Anthropic) also uses `nemohermes inference set`. +Switching to a different provider family (for example, from NVIDIA Endpoints to Anthropic) also uses `$$nemoclaw inference set`. The command updates both the gateway route and `/sandbox/.hermes/config.yaml`. If the Hermes config sync fails after the gateway route is updated, NemoClaw keeps the host registry aligned with the gateway and prints a rebuild hint. Run the rebuild before relying on the running agent if the warning says the image config could not be patched. ```bash -nemohermes inference set --provider anthropic-prod --model claude-sonnet-4-6 --no-verify +$$nemoclaw inference set --provider anthropic-prod --model claude-sonnet-4-6 --no-verify ``` @@ -206,12 +143,7 @@ Use `--no-verify` only when OpenShell cannot verify the provider at switch time ## Tune Model Metadata The sandbox image bakes model metadata (context window, max output tokens, reasoning mode, and accepted input modalities) into `openclaw.json` at build time. - -To change these values, set the corresponding environment variables before running `nemoclaw onboard` so they patch into the Dockerfile before the image builds. - - -To change these values, set the corresponding environment variables before running `nemohermes onboard` so they patch into the Dockerfile before the image builds. - +To change these values, set the corresponding environment variables before running `$$nemoclaw onboard` so they patch into the Dockerfile before the image builds. | Variable | Values | Default | |---|---|---| @@ -226,18 +158,6 @@ NemoClaw ignores invalid values and bakes the default into the image. For Local Ollama, onboarding loads the selected model first and uses Ollama's reported runtime context length when `NEMOCLAW_CONTEXT_WINDOW` is unset. Use `NEMOCLAW_INFERENCE_INPUTS=text,image` only for a model that accepts image input through the selected provider. - -```bash -export NEMOCLAW_CONTEXT_WINDOW=65536 -export NEMOCLAW_MAX_TOKENS=8192 -export NEMOCLAW_REASONING=true -export NEMOCLAW_INFERENCE_INPUTS=text,image -export NEMOCLAW_AGENT_TIMEOUT=1800 -export NEMOCLAW_AGENT_HEARTBEAT_EVERY=0m -nemoclaw onboard -``` - - ```bash export NEMOCLAW_CONTEXT_WINDOW=65536 export NEMOCLAW_MAX_TOKENS=8192 @@ -245,9 +165,8 @@ export NEMOCLAW_REASONING=true export NEMOCLAW_INFERENCE_INPUTS=text,image export NEMOCLAW_AGENT_TIMEOUT=1800 export NEMOCLAW_AGENT_HEARTBEAT_EVERY=0m -nemohermes onboard +$$nemoclaw onboard ``` - @@ -255,7 +174,7 @@ nemohermes onboard Increase it for slow local inference, such as CPU-only Ollama or vLLM on modest hardware. NemoClaw writes this value into `openclaw.json` during onboarding. The default sandbox can keep that file writable for agent state, but direct in-sandbox edits are not the supported or durable way to change NemoClaw-managed defaults. -Rebuild the sandbox with `nemoclaw onboard` to apply a new value. +Rebuild the sandbox with `$$nemoclaw onboard` to apply a new value. @@ -263,7 +182,7 @@ Rebuild the sandbox with `nemoclaw onboard` to apply a new value. `NEMOCLAW_AGENT_TIMEOUT` controls the per-request inference timeout baked into the Hermes sandbox image. Increase it for slow local inference, such as CPU-only Ollama or vLLM on modest hardware. Direct in-sandbox edits are not the supported or durable way to change NemoClaw-managed defaults. -Rebuild the sandbox with `nemohermes onboard` to apply a new value. +Rebuild the sandbox with `$$nemoclaw onboard` to apply a new value. @@ -277,42 +196,30 @@ 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. +Rebuild the sandbox with `$$nemoclaw onboard --resume` to apply a new value. Hermes does not use OpenClaw's `HEARTBEAT.md` wake-up mechanism. -Rebuild the sandbox with `nemohermes onboard --resume` to apply build-time inference metadata changes. +Rebuild the sandbox with `$$nemoclaw onboard --resume` 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 -``` - - - - ```bash -nemohermes onboard --resume --recreate-sandbox +$$nemoclaw onboard --resume --recreate-sandbox ``` - - ## Verify the Active Model - -Use `nemoclaw inference get` to print the provider and model the gateway is currently routing to. -Run it before `nemoclaw inference set` to confirm the starting state, or after a switch to verify the new route. +Use `$$nemoclaw inference get` to print the provider and model the gateway is currently routing to. +Run it before `$$nemoclaw inference set` to confirm the starting state, or after a switch to verify the new route. ```console -$ nemoclaw inference get +$ $$nemoclaw inference get Provider: nvidia-prod Model: nvidia/nemotron-3-super-120b-a12b ``` @@ -320,56 +227,21 @@ Model: nvidia/nemotron-3-super-120b-a12b Pass `--json` for machine-readable output. ```console -$ nemoclaw inference get --json +$ $$nemoclaw inference get --json { "provider": "nvidia-prod", "model": "nvidia/nemotron-3-super-120b-a12b" } ``` - - -Use `nemohermes inference get` to print the provider and model the gateway is currently routing to. -Run it before `nemohermes inference set` to confirm the starting state, or after a switch to verify the new route. - -```console -$ nemohermes inference get -Provider: nvidia-prod -Model: nvidia/nemotron-3-super-120b-a12b -``` - -Pass `--json` for machine-readable output. - -```console -$ nemohermes inference get --json -{ - "provider": "nvidia-prod", - "model": "nvidia/nemotron-3-super-120b-a12b" -} -``` - - - The command exits non-zero with `OpenShell inference route is not configured.` when the gateway has no registered inference route. - -Run `nemoclaw onboard` to configure one. - - -Run `nemohermes onboard` to configure one. - +Run `$$nemoclaw onboard` to configure one. Run the status command when you also need sandbox, service, and messaging health: - -```bash -nemoclaw status -``` - - ```bash -nemohermes status +$$nemoclaw status ``` - The status output includes the active provider, model, and endpoint with the rest of the sandbox state. @@ -379,8 +251,8 @@ 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 or 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. +- `$$nemoclaw inference set` patches the selected running OpenClaw or 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. - 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. @@ -388,8 +260,8 @@ 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`. -- `nemohermes inference set` patches the selected running Hermes sandbox config and recomputes its config hash. -- Use `nemohermes onboard --resume --recreate-sandbox` for build-time settings such as context window, max tokens, reasoning mode, heartbeat cadence, or image contents. +- `$$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. - 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. diff --git a/docs/inference/use-local-inference.mdx b/docs/inference/use-local-inference.mdx index 4e875cb5b1..54dd26db5a 100644 --- a/docs/inference/use-local-inference.mdx +++ b/docs/inference/use-local-inference.mdx @@ -73,16 +73,9 @@ Install `zstd` manually, then rerun onboarding. Run the onboard wizard. - -```bash -nemoclaw onboard -``` - - ```bash -nemohermes onboard +$$nemoclaw onboard ``` - Select **Local Ollama** from the provider list. NemoClaw lists installed models or offers starter models if you have not installed any. @@ -148,18 +141,10 @@ For non-WSL Ollama setups, the onboard wizard manages the proxy automatically: On native Linux hosts, a firewall can allow the host proxy health check while still blocking sandbox containers on the OpenShell Docker bridge. When the sandbox-side proxy probe fails with a TCP error, onboarding exits before it saves the inference route and prints a command like: - ```bash sudo ufw allow from to any port 11435 proto tcp -nemoclaw onboard +$$nemoclaw onboard ``` - - -```bash -sudo ufw allow from to any port 11435 proto tcp -nemohermes onboard -``` - If the probe cannot run, for example because Docker Desktop or WSL uses a different host routing model, onboarding continues and relies on the regular proxy health check. @@ -182,20 +167,11 @@ This does not delete downloaded model files. ### Non-Interactive Setup - ```bash NEMOCLAW_PROVIDER=ollama \ NEMOCLAW_MODEL=qwen2.5:14b \ - nemoclaw onboard --non-interactive --yes + $$nemoclaw onboard --non-interactive --yes ``` - - -```bash -NEMOCLAW_PROVIDER=ollama \ - NEMOCLAW_MODEL=qwen2.5:14b \ - nemohermes onboard --non-interactive --yes -``` - If `NEMOCLAW_MODEL` is not set, NemoClaw selects a default model based on available memory. If `NEMOCLAW_MODEL` names a known bootstrap model (for example `qwen3.6:35b`) that does not fit the host's currently available GPU memory, NemoClaw warns and falls back to the largest known model that does fit. @@ -228,17 +204,9 @@ vllm serve meta-llama/Llama-3.1-8B-Instruct --port 8000 Run the onboard wizard. - ```bash -nemoclaw onboard +$$nemoclaw onboard ``` - - - -```bash -nemohermes onboard -``` - When the wizard asks you to choose an inference provider, select **Other OpenAI-compatible endpoint**. Enter the base URL of your local server, for example `http://localhost:8000/v1`. @@ -256,25 +224,13 @@ Route, configuration, and authentication failures still fail immediately. Set the following environment variables for scripted or CI/CD deployments. - ```bash NEMOCLAW_PROVIDER=custom \ NEMOCLAW_ENDPOINT_URL=http://localhost:8000/v1 \ NEMOCLAW_MODEL=meta-llama/Llama-3.1-8B-Instruct \ COMPATIBLE_API_KEY=dummy \ - nemoclaw onboard --non-interactive + $$nemoclaw onboard --non-interactive ``` - - - -```bash -NEMOCLAW_PROVIDER=custom \ - NEMOCLAW_ENDPOINT_URL=http://localhost:8000/v1 \ - NEMOCLAW_MODEL=meta-llama/Llama-3.1-8B-Instruct \ - COMPATIBLE_API_KEY=dummy \ - nemohermes onboard --non-interactive -``` - | Variable | Purpose | |---|---| @@ -291,16 +247,9 @@ without probing the Responses API. To opt in to `/v1/responses`, set `NEMOCLAW_PREFERRED_API` before running onboard: - ```bash -NEMOCLAW_PREFERRED_API=openai-responses nemoclaw onboard +NEMOCLAW_PREFERRED_API=openai-responses $$nemoclaw onboard ``` - - -```bash -NEMOCLAW_PREFERRED_API=openai-responses nemohermes onboard -``` - The wizard then probes `/v1/responses` and only selects it when streaming support is complete. @@ -312,62 +261,33 @@ You can use this variable in both interactive and non-interactive mode. |---|---|---| | `NEMOCLAW_PREFERRED_API` | `openai-completions`, `openai-responses` | `openai-completions` for compatible endpoints | - -If you already onboarded and the sandbox is failing at runtime, re-run `nemoclaw onboard` to re-probe the endpoint and bake the correct API path +If you already onboarded and the sandbox is failing at runtime, re-run `$$nemoclaw onboard` to re-probe the endpoint and bake the correct API path into the image. - - -If you already onboarded and the sandbox is failing at runtime, re-run `nemohermes onboard` to re-probe the endpoint and bake the correct API path -into the image. - Refer to [Switch Inference Models](switch-inference-providers) for more information. ## Anthropic-Compatible Server If your local server implements the Anthropic Messages API (`/v1/messages`), choose **Other Anthropic-compatible endpoint** during onboarding instead. - -```bash -nemoclaw onboard -``` - - ```bash -nemohermes onboard +$$nemoclaw onboard ``` - For non-interactive setup, use `NEMOCLAW_PROVIDER=anthropicCompatible` and set `COMPATIBLE_ANTHROPIC_API_KEY`. - -```bash -NEMOCLAW_PROVIDER=anthropicCompatible \ - NEMOCLAW_ENDPOINT_URL=http://localhost:8080 \ - NEMOCLAW_MODEL=my-model \ - COMPATIBLE_ANTHROPIC_API_KEY=dummy \ - nemoclaw onboard --non-interactive -``` - - ```bash NEMOCLAW_PROVIDER=anthropicCompatible \ NEMOCLAW_ENDPOINT_URL=http://localhost:8080 \ NEMOCLAW_MODEL=my-model \ COMPATIBLE_ANTHROPIC_API_KEY=dummy \ - nemohermes onboard --non-interactive + $$nemoclaw onboard --non-interactive ``` - ## vLLM When vLLM is already running on `localhost:8000`, NemoClaw can detect it automatically and query the `/v1/models` endpoint to determine the loaded model. On supported Linux hosts with NVIDIA GPUs, the onboard wizard can also install or start a managed vLLM container for you. - -For an already-running vLLM server, run `nemoclaw onboard` and select **Local vLLM [experimental]** from the provider list. - - -For an already-running vLLM server, run `nemohermes onboard` and select **Local vLLM [experimental]** from the provider list. - +For an already-running vLLM server, run `$$nemoclaw onboard` and select **Local vLLM [experimental]** from the provider list. If vLLM is already running, NemoClaw detects the running model and validates the endpoint. If vLLM is not running and your host matches a DGX Spark or DGX Station managed profile, NemoClaw shows the **Install vLLM** or **Start vLLM** entry by default. @@ -395,34 +315,18 @@ The vLLM `/v1/responses` endpoint does not run the `--tool-call-parser`, so tool Use an already-running vLLM server: - -```bash -NEMOCLAW_PROVIDER=vllm \ - nemoclaw onboard --non-interactive -``` - - ```bash NEMOCLAW_PROVIDER=vllm \ - nemohermes onboard --non-interactive + $$nemoclaw onboard --non-interactive ``` - Install or start managed vLLM when NemoClaw detects a supported profile. On DGX Spark and DGX Station, `NEMOCLAW_PROVIDER=install-vllm` is enough for non-interactive runs; add `NEMOCLAW_EXPERIMENTAL=1` on generic Linux NVIDIA GPU hosts. - -```bash -NEMOCLAW_PROVIDER=install-vllm \ - nemoclaw onboard --non-interactive -``` - - ```bash NEMOCLAW_PROVIDER=install-vllm \ - nemohermes onboard --non-interactive + $$nemoclaw onboard --non-interactive ``` - NemoClaw records the model returned by vLLM's `/v1/models` endpoint. Start vLLM with the model you want before onboarding if you manage the server yourself. @@ -446,22 +350,12 @@ An unrecognized value fails fast with a list of valid slugs. Gated models require a Hugging Face token; export it before onboarding so NemoClaw can forward it into the managed vLLM container: - -```bash -export HF_TOKEN= -NEMOCLAW_PROVIDER=install-vllm \ - NEMOCLAW_VLLM_MODEL=deepseek-r1-distill-70b \ - nemoclaw onboard --non-interactive -``` - - ```bash export HF_TOKEN= NEMOCLAW_PROVIDER=install-vllm \ NEMOCLAW_VLLM_MODEL=deepseek-r1-distill-70b \ - nemohermes onboard --non-interactive + $$nemoclaw onboard --non-interactive ``` - NemoClaw accepts `HUGGING_FACE_HUB_TOKEN` as an alternative. The token check runs on the host before any docker pull, so a missing or empty token aborts onboarding before bandwidth is spent on a 401. @@ -472,16 +366,9 @@ NemoClaw can pull, start, and manage a NIM container on hosts with a NIM-capable Set the experimental flag and run onboard. - ```bash -NEMOCLAW_EXPERIMENTAL=1 nemoclaw onboard +NEMOCLAW_EXPERIMENTAL=1 $$nemoclaw onboard ``` - - -```bash -NEMOCLAW_EXPERIMENTAL=1 nemohermes onboard -``` - Select **Local NVIDIA NIM [experimental]** from the provider list. NemoClaw filters available models by GPU VRAM, pulls the NIM container image, starts it, and waits for it to become healthy before continuing. @@ -490,12 +377,7 @@ On hosts with mixed NVIDIA GPU models, the preflight summary shows each detected NVIDIA hosts NIM container images on `nvcr.io`, and `docker pull` requires NGC registry authentication. If Docker is not already logged in to `nvcr.io`, onboard prompts for an [NGC API key](https://org.ngc.nvidia.com/setup/api-key) and runs `docker login nvcr.io` over `--password-stdin` so the key is never written to disk or shell history. The prompt masks the key during input and retries one time on a bad key before failing. - -In non-interactive mode, onboard exits with login instructions if Docker is not already authenticated; run `docker login nvcr.io` yourself, then re-run `nemoclaw onboard --non-interactive`. - - -In non-interactive mode, onboard exits with login instructions if Docker is not already authenticated; run `docker login nvcr.io` yourself, then re-run `nemohermes onboard --non-interactive`. - +In non-interactive mode, onboard exits with login instructions if Docker is not already authenticated; run `docker login nvcr.io` yourself, then re-run `$$nemoclaw onboard --non-interactive`. If `NGC_API_KEY` or `NVIDIA_API_KEY` is already exported, NemoClaw passes it into the managed NIM container through the process environment instead of command-line arguments. If the NIM container exits before the health endpoint becomes ready, onboarding stops early and prints the last container log lines. @@ -506,20 +388,11 @@ The same `chat/completions` API path restriction applies. ### Non-Interactive Setup - -```bash -NEMOCLAW_EXPERIMENTAL=1 \ - NEMOCLAW_PROVIDER=nim \ - nemoclaw onboard --non-interactive -``` - - ```bash NEMOCLAW_EXPERIMENTAL=1 \ NEMOCLAW_PROVIDER=nim \ - nemohermes onboard --non-interactive + $$nemoclaw onboard --non-interactive ``` - To select a specific model, set `NEMOCLAW_MODEL`. @@ -530,27 +403,14 @@ Large prompts on hardware such as DGX Spark can exceed shorter timeouts, so Nemo To override the timeout, set the `NEMOCLAW_LOCAL_INFERENCE_TIMEOUT` environment variable before onboarding: - ```bash export NEMOCLAW_LOCAL_INFERENCE_TIMEOUT=300 -nemoclaw onboard +$$nemoclaw onboard ``` - - -```bash -export NEMOCLAW_LOCAL_INFERENCE_TIMEOUT=300 -nemohermes onboard -``` - The value is in seconds. NemoClaw bakes this setting into the sandbox at build time. - -Changing it after onboarding requires re-running `nemoclaw onboard`. - - -Changing it after onboarding requires re-running `nemohermes onboard`. - +Changing it after onboarding requires re-running `$$nemoclaw onboard`. `NEMOCLAW_LOCAL_INFERENCE_TIMEOUT` only governs the inference-server validation probe. During local Ollama setup, NemoClaw treats host-side curl process timeouts as retryable probe failures and retries with a larger timeout before it reports a validation failure. @@ -559,20 +419,11 @@ The post-create readiness wait (image build, gateway upload, in-sandbox boot) ha On hosts where the sandbox image takes minutes to build or upload, raise both settings together. Examples include large quantized models, DGX Station first runs, and remote VMs over a slow link. - -```bash -export NEMOCLAW_LOCAL_INFERENCE_TIMEOUT=300 -export NEMOCLAW_SANDBOX_READY_TIMEOUT=600 -nemoclaw onboard -``` - - ```bash export NEMOCLAW_LOCAL_INFERENCE_TIMEOUT=300 export NEMOCLAW_SANDBOX_READY_TIMEOUT=600 -nemohermes onboard +$$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). @@ -580,16 +431,9 @@ If onboard ends with `Sandbox '' was created but did not become ready with After onboarding completes, confirm the active provider and model. - ```bash -nemoclaw status +$$nemoclaw status ``` - - -```bash -nemohermes status -``` - The output shows the provider label (for example, "Local vLLM" or "Other OpenAI-compatible endpoint") and the active model. For Local Ollama, status also checks the authenticated proxy when a proxy token is available. @@ -602,23 +446,11 @@ Refer to [Switch Inference Models](switch-inference-providers) for the full proc For compatible endpoints, the command is: - ```bash -nemoclaw inference set --provider compatible-endpoint --model +$$nemoclaw inference set --provider compatible-endpoint --model ``` - - -```bash -nemohermes inference set --provider compatible-endpoint --model -``` - - -If the provider itself needs to change (for example, switching from vLLM to a cloud API), pass the new provider to `nemoclaw inference set`. - - -If the provider itself needs to change (for example, switching from vLLM to a cloud API), pass the new provider to `nemohermes inference set`. - +If the provider itself needs to change (for example, switching from vLLM to a cloud API), pass the new provider to `$$nemoclaw inference set`. ## Next Steps diff --git a/docs/manage-sandboxes/backup-restore.mdx b/docs/manage-sandboxes/backup-restore.mdx index e2c6c35036..c01b735dd4 100644 --- a/docs/manage-sandboxes/backup-restore.mdx +++ b/docs/manage-sandboxes/backup-restore.mdx @@ -22,14 +22,14 @@ This guide covers snapshot commands, manual backup with CLI commands, and an aut -- Before running `nemoclaw destroy` +- Before running `$$nemoclaw destroy` - Before major NemoClaw version upgrades - Periodically, if you've invested time customizing your agent -- Before running `nemohermes destroy` +- Before running `$$nemoclaw destroy` - Before major NemoClaw version upgrades - Periodically, if you've invested time customizing your agent or paired messaging channels @@ -43,80 +43,47 @@ 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. Treat snapshot directories as private local data: the Hermes database can contain session metadata and message history needed for a faithful restore. - -```bash -nemoclaw my-assistant snapshot create -nemoclaw my-assistant snapshot list -nemoclaw my-assistant snapshot restore -``` - - ```bash -nemohermes my-assistant snapshot create -nemohermes my-assistant snapshot list -nemohermes my-assistant snapshot restore +$$nemoclaw my-assistant snapshot create +$$nemoclaw my-assistant snapshot list +$$nemoclaw my-assistant snapshot restore ``` - `snapshot list` prints a table of version, name, timestamp, and path. NemoClaw computes versions (`v1`, `v2`, ..., `vN`) from timestamp order, so `vN` is always the newest snapshot. To tag a snapshot with a human-readable label, pass `--name`: - -```bash -nemoclaw my-assistant snapshot create --name before-upgrade -``` - - ```bash -nemohermes my-assistant snapshot create --name before-upgrade +$$nemoclaw my-assistant snapshot create --name before-upgrade ``` - To restore a specific snapshot instead of the latest, pass a version, name, or timestamp prefix: - -```bash -nemoclaw my-assistant snapshot restore v3 -nemoclaw my-assistant snapshot restore before-upgrade -nemoclaw my-assistant snapshot restore 2026-04-14T -``` - - ```bash -nemohermes my-assistant snapshot restore v3 -nemohermes my-assistant snapshot restore before-upgrade -nemohermes my-assistant snapshot restore 2026-04-14T +$$nemoclaw my-assistant snapshot restore v3 +$$nemoclaw my-assistant snapshot restore before-upgrade +$$nemoclaw my-assistant snapshot restore 2026-04-14T ``` - To clone a snapshot into a different sandbox name, pass `--to `. If the destination sandbox already exists, NemoClaw refuses to overwrite it unless you pass `--force`: - -```bash -nemoclaw my-assistant snapshot restore before-upgrade --to my-assistant-clone -nemoclaw my-assistant snapshot restore before-upgrade --to my-assistant-clone --force --yes -``` - - ```bash -nemohermes my-assistant snapshot restore before-upgrade --to my-assistant-clone -nemohermes my-assistant snapshot restore before-upgrade --to my-assistant-clone --force --yes +$$nemoclaw my-assistant snapshot restore before-upgrade --to my-assistant-clone +$$nemoclaw my-assistant snapshot restore before-upgrade --to my-assistant-clone --force --yes ``` - -The `nemoclaw rebuild` command uses the same snapshot mechanism automatically. +The `$$nemoclaw rebuild` command uses the same snapshot mechanism automatically. Snapshot restore performs a targeted repair for legacy `.openclaw-data` symlinks that older images created. NemoClaw rejects unsafe symlinks and hard links inside sandbox state during backup creation before they can enter a snapshot. -The `nemohermes rebuild` command uses the same snapshot mechanism automatically. +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 Hermes files such as `auth.json` are intentionally excluded from snapshots. NemoClaw-regenerated Hermes config files (`config.yaml` and @@ -249,7 +216,7 @@ Use manual `openshell sandbox download` / `openshell sandbox upload` only when y When you configure OpenClaw with multiple named agents, each agent has its own workspace directory (`workspace-main/`, `workspace-support/`, `workspace-ops/`, and so on). Refer to [Multi-Agent Deployments](workspace-files#multi-agent-deployments). -`nemoclaw snapshot create` automatically discovers every `workspace-*/` directory under the sandbox state tree and includes it in the snapshot bundle alongside the default `workspace/`. +`$$nemoclaw snapshot create` automatically discovers every `workspace-*/` directory under the sandbox state tree and includes it in the snapshot bundle alongside the default `workspace/`. `snapshot restore` reapplies the full per-agent set. You do not need a manual per-workspace backup pattern. diff --git a/docs/manage-sandboxes/lifecycle.mdx b/docs/manage-sandboxes/lifecycle.mdx index f0d719bfe1..8eb14c2f49 100644 --- a/docs/manage-sandboxes/lifecycle.mdx +++ b/docs/manage-sandboxes/lifecycle.mdx @@ -21,10 +21,10 @@ Use this guide after you finish [Quickstart with Hermes](../get-started/quicksta It covers day-two sandbox operations such as listing sandboxes, checking health, managing ports, rebuilding safely, upgrading, and uninstalling. -When a workflow uses the lower-level OpenShell CLI, see [CLI Selection Guide](../reference/cli-selection-guide) for the boundary between `nemoclaw` and `openshell`. +When a workflow uses the lower-level OpenShell CLI, see [CLI Selection Guide](../reference/cli-selection-guide) for the boundary between `$$nemoclaw` and `openshell`. -When a workflow uses the lower-level OpenShell CLI, see [CLI Selection Guide](../reference/cli-selection-guide) for the boundary between `nemohermes`, `nemoclaw`, and `openshell`. +When a workflow uses the lower-level OpenShell CLI, see [CLI Selection Guide](../reference/cli-selection-guide) for the boundary between `$$nemoclaw`, `nemoclaw`, and `openshell`. ## List Sandboxes @@ -111,10 +111,10 @@ openshell forward list Each sandbox needs its own dashboard port, since `openshell forward` refuses to bind a port that another sandbox is already using. -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 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, `nemohermes onboard` scans for the next free port and records it for the sandbox. +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. @@ -156,10 +156,10 @@ Refer to [Switch Inference Providers](../inference/switch-inference-providers) f ### 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. +If `$$nemoclaw status` reports the sandbox is alive but the gateway is not running, run the recover command instead of opening a shell. -If `nemohermes status` reports the sandbox is alive but the Hermes gateway is not running, run the recover command instead of opening a shell. +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 @@ -237,14 +237,14 @@ Before it onboards anything, the installer calls [`$$nemoclaw backup-all`](../re If your existing gateway is from OpenShell earlier than `0.0.37`, the installer prompts before it runs the new automatic gateway upgrade path. -The installer offers the automatic path only when the existing `nemoclaw` CLI supports `backup-all`. +The installer offers the automatic path only when the existing `$$nemoclaw` CLI supports `backup-all`. Older installs must preserve sandbox state manually before retiring the gateway. -For unattended installs, set `NEMOCLAW_ACCEPT_EXPERIMENTAL_OPENSHELL_UPGRADE=1`, or manually run `nemoclaw backup-all`, `openshell gateway remove nemoclaw || openshell gateway destroy -g nemoclaw || openshell gateway destroy` (the command tries both verbs so the right one runs on either OpenShell release), and `sudo pkill -f openshell-gateway` if a privileged host gateway remains before rerunning the installer as `curl -fsSL https://www.nvidia.com/nemoclaw.sh | NEMOCLAW_OPENSHELL_UPGRADE_PREPARED=1 bash`. +For unattended installs, set `NEMOCLAW_ACCEPT_EXPERIMENTAL_OPENSHELL_UPGRADE=1`, or manually run `$$nemoclaw backup-all`, `openshell gateway remove nemoclaw || openshell gateway destroy -g nemoclaw || openshell gateway destroy` (the command tries both verbs so the right one runs on either OpenShell release), and `sudo pkill -f openshell-gateway` if a privileged host gateway remains before rerunning the installer as `curl -fsSL https://www.nvidia.com/nemoclaw.sh | NEMOCLAW_OPENSHELL_UPGRADE_PREPARED=1 bash`. -The installer offers the automatic path only when the existing `nemohermes` CLI supports `backup-all`. +The installer offers the automatic path only when the existing `$$nemoclaw` CLI supports `backup-all`. Older installs must preserve sandbox state manually before retiring the gateway. -For unattended installs, set `NEMOCLAW_ACCEPT_EXPERIMENTAL_OPENSHELL_UPGRADE=1`, or manually run `nemohermes backup-all`, `openshell gateway remove nemoclaw || openshell gateway destroy -g nemoclaw || openshell gateway destroy` (the command tries both verbs so the right one runs on either OpenShell release), and `sudo pkill -f openshell-gateway` if a privileged host gateway remains before rerunning the installer as `curl -fsSL https://www.nvidia.com/nemoclaw.sh | NEMOCLAW_AGENT=hermes NEMOCLAW_OPENSHELL_UPGRADE_PREPARED=1 bash`. +For unattended installs, set `NEMOCLAW_ACCEPT_EXPERIMENTAL_OPENSHELL_UPGRADE=1`, or manually run `$$nemoclaw backup-all`, `openshell gateway remove nemoclaw || openshell gateway destroy -g nemoclaw || openshell gateway destroy` (the command tries both verbs so the right one runs on either OpenShell release), and `sudo pkill -f openshell-gateway` if a privileged host gateway remains before rerunning the installer as `curl -fsSL https://www.nvidia.com/nemoclaw.sh | NEMOCLAW_AGENT=hermes NEMOCLAW_OPENSHELL_UPGRADE_PREPARED=1 bash`. ```bash @@ -265,12 +265,12 @@ $$nemoclaw upgrade-sandboxes # manually rebui ``` -`nemoclaw update` is the CLI wrapper around the same installer path as `curl -fsSL https://www.nvidia.com/nemoclaw.sh | bash`. -Use `nemoclaw update --check` when you only want to inspect version state and see the maintained update command. +`$$nemoclaw update` is the CLI wrapper around the same installer path as `curl -fsSL https://www.nvidia.com/nemoclaw.sh | bash`. +Use `$$nemoclaw update --check` when you only want to inspect version state and see the maintained update command. -`nemohermes update` is the CLI wrapper around the same installer path with Hermes selected. -Use `nemohermes update --check` when you only want to inspect version state and see the maintained update command. +`$$nemoclaw update` is the CLI wrapper around the same installer path with Hermes selected. +Use `$$nemoclaw update --check` when you only want to inspect version state and see the maintained update command. For scripted manual rebuilds, use `$$nemoclaw upgrade-sandboxes --auto` to skip the confirmation prompt. @@ -286,17 +286,17 @@ $$nemoclaw snapshot restore pre-upgrade Each rebuild destroys the existing container and creates a new one. -NemoClaw protects your data through the same backup-and-restore flow as [`nemoclaw rebuild`](../reference/commands#nemoclaw-name-rebuild): +NemoClaw protects your data through the same backup-and-restore flow as [`$$nemoclaw rebuild`](../reference/commands#$$nemoclaw-name-rebuild): - NemoClaw preserves manifest-defined workspace state. Before deleting the old container, NemoClaw snapshots the state directories and durable state files defined in the agent manifest, typically `/sandbox/.openclaw/workspace/`; for Hermes this also includes `SOUL.md` and the SQLite database behind `.hermes/state.db`. Stored credentials (`~/.nemoclaw/credentials.json`) and registered policy presets live on the host and are re-applied to the new sandbox automatically. -- NemoClaw does not preserve runtime changes outside the workspace state directories. This includes packages installed inside the running container with `apt` or `pip`, files in non-workspace paths, and in-memory or process state. If you have customized the running container at runtime, capture that as `Dockerfile` changes for `nemoclaw onboard --from` or a manual `openshell sandbox download` before the rebuild starts. +- NemoClaw does not preserve runtime changes outside the workspace state directories. This includes packages installed inside the running container with `apt` or `pip`, files in non-workspace paths, and in-memory or process state. If you have customized the running container at runtime, capture that as `Dockerfile` changes for `$$nemoclaw onboard --from` or a manual `openshell sandbox download` before the rebuild starts. -NemoClaw protects your data through the same backup-and-restore flow as `nemohermes rebuild`: +NemoClaw protects your data through the same backup-and-restore flow as [`$$nemoclaw rebuild`](../reference/commands#$$nemoclaw-name-rebuild): - NemoClaw preserves manifest-defined Hermes state. Before deleting the old container, NemoClaw snapshots the state directories and durable state files defined in the Hermes manifest, including `SOUL.md` and the SQLite database behind `.hermes/state.db`. Stored credentials (`~/.nemoclaw/credentials.json`) and registered policy presets live on the host and are re-applied to the new sandbox automatically. -- NemoClaw does not preserve runtime changes outside the manifest-defined state directories. This includes packages installed inside the running container with `apt` or `pip`, files in non-state paths, and in-memory or process state. If you have customized the running container at runtime, capture that as `Dockerfile` changes for `nemohermes onboard --from` or a manual `openshell sandbox download` before the rebuild starts. +- NemoClaw does not preserve runtime changes outside the manifest-defined state directories. This includes packages installed inside the running container with `apt` or `pip`, files in non-state paths, and in-memory or process state. If you have customized the running container at runtime, capture that as `Dockerfile` changes for `$$nemoclaw onboard --from` or a manual `openshell sandbox download` before the rebuild starts. diff --git a/docs/manage-sandboxes/messaging-channels.mdx b/docs/manage-sandboxes/messaging-channels.mdx index 3684938fa6..4f35274114 100644 --- a/docs/manage-sandboxes/messaging-channels.mdx +++ b/docs/manage-sandboxes/messaging-channels.mdx @@ -26,64 +26,40 @@ Interfaces, defaults, and supported features can change, and NVIDIA does not rec -You can enable channels during `nemoclaw onboard` or add them later with host-side `nemoclaw channels` commands. +You can enable channels during `$$nemoclaw onboard` or add them later with host-side `$$nemoclaw channels` commands. Do not run agent-specific channel mutation commands such as `openclaw channels add` or `openclaw channels remove` inside the sandbox because NemoClaw generates `/sandbox/.openclaw/openclaw.json` at image build time, and changes inside the running container do not persist across rebuilds. -You can enable channels during `nemohermes onboard` or add them later with host-side `nemohermes channels` commands. +You can enable channels during `$$nemoclaw onboard` or add them later with host-side `$$nemoclaw channels` commands. Do not mutate messaging configuration directly inside the sandbox because NemoClaw generates `/sandbox/.hermes/.env` and Hermes config at image build time, and changes inside the running container do not persist across rebuilds. -`nemoclaw tunnel start` does not start Telegram, Discord, Slack, or other chat bridges. -It only starts optional host services such as the cloudflared tunnel when that binary is present. (`nemoclaw start` is kept as a deprecated alias.) +`$$nemoclaw tunnel start` does not start Telegram, Discord, Slack, or other chat bridges. +It only starts optional host services such as the cloudflared tunnel when that binary is present. (`$$nemoclaw start` is kept as a deprecated alias.) -`nemohermes tunnel start` does not start Telegram, Discord, Slack, or other chat bridges. +`$$nemoclaw tunnel start` does not start Telegram, Discord, Slack, or other chat bridges. It only starts optional host services such as the cloudflared tunnel when that binary is present. For details, refer to [Commands](../reference/commands). ## Prerequisites - - -- A machine where you can run `nemoclaw onboard` (local or remote host that runs the gateway and sandbox). - - - - -- A machine where you can run `nemohermes onboard` (local or remote host that runs the gateway and sandbox). - - +- A machine where you can run `$$nemoclaw onboard` (local or remote host that runs the gateway and sandbox). - A token for each token-based messaging platform you want to enable, a personal WeChat account on your phone for the host-side QR scan during onboarding, or a phone you can use to scan the QR code for WhatsApp pairing. - A network policy preset for each enabled channel, or equivalent custom egress rules. ## Channel Requirements - - | Channel | Required tokens | Optional settings | |---------|-----------------|-------------------| | Telegram | `TELEGRAM_BOT_TOKEN` | `TELEGRAM_ALLOWED_IDS` for DM allowlisting, `TELEGRAM_REQUIRE_MENTION` for group-chat replies | | Discord | `DISCORD_BOT_TOKEN` | `DISCORD_SERVER_ID`, `DISCORD_USER_ID`, `DISCORD_REQUIRE_MENTION` | | Slack | `SLACK_BOT_TOKEN`, `SLACK_APP_TOKEN` | `SLACK_ALLOWED_USERS` for DM and channel `@mention` user allowlisting, `SLACK_ALLOWED_CHANNELS` for channel ID allowlisting | -| WeChat (experimental) | None. Captured through host-side QR scan during `nemoclaw onboard` | `WECHAT_ALLOWED_IDS` for DM allowlisting | +| WeChat (experimental) | None. Captured through host-side QR scan during `$$nemoclaw onboard` | `WECHAT_ALLOWED_IDS` for DM allowlisting | | WhatsApp (experimental) | None. Pair through QR after rebuild | None | - - - -| Channel | Required tokens | Optional settings | -|---------|-----------------|-------------------| -| Telegram | `TELEGRAM_BOT_TOKEN` | `TELEGRAM_ALLOWED_IDS` for DM allowlisting, `TELEGRAM_REQUIRE_MENTION` for group-chat replies | -| Discord | `DISCORD_BOT_TOKEN` | `DISCORD_SERVER_ID`, `DISCORD_USER_ID`, `DISCORD_REQUIRE_MENTION` | -| Slack | `SLACK_BOT_TOKEN`, `SLACK_APP_TOKEN` | `SLACK_ALLOWED_USERS` for DM and channel `@mention` user allowlisting, `SLACK_ALLOWED_CHANNELS` for channel ID allowlisting | -| WeChat (experimental) | None. Captured through host-side QR scan during `nemohermes onboard` | `WECHAT_ALLOWED_IDS` for DM allowlisting | -| WhatsApp (experimental) | None. Pair through QR after rebuild | None | - - - Telegram uses a bot token from [BotFather](https://t.me/BotFather). Open Telegram, send `/newbot` to [@BotFather](https://t.me/BotFather), follow the prompts, and copy the token. For Telegram group chats, disable privacy mode before testing group replies: in @BotFather, run `/setprivacy`, choose the bot, then choose **Disable**. @@ -114,12 +90,7 @@ WeChat (experimental) delivers messages over Tencent's iLink gateway through the The supported mode in this release is **personal WeChat** (`bot_type=3`). WeChat Official Account and WeCom/Enterprise WeChat are not wired up. - -Because the bot token only exists after a successful iLink QR handshake, NemoClaw runs the QR login on the host during `nemoclaw onboard`. - - -Because the bot token only exists after a successful iLink QR handshake, NemoClaw runs the QR login on the host during `nemohermes onboard`. - +Because the bot token only exists after a successful iLink QR handshake, NemoClaw runs the QR login on the host during `$$nemoclaw onboard`. You scan the QR with WeChat on your phone (Discover → Scan), confirm the login, and NemoClaw captures the token, `accountId`, `baseUrl`, and `userId` from the iLink response. NemoClaw registers the token as the `-wechat-bridge` OpenShell provider and substitutes the `openshell:resolve:env:WECHAT_BOT_TOKEN` placeholder for it inside the sandbox, so the token never lands in the image or on disk inside the running container. NemoClaw bakes the non-secret per-account metadata (`WECHAT_ACCOUNT_ID`, `WECHAT_BASE_URL`, `WECHAT_USER_ID`) into the sandbox image so the in-sandbox bridge can pre-seed the per-account context tokens without re-running the QR handshake. @@ -179,25 +150,13 @@ export SLACK_ALLOWED_CHANNELS= ``` This release does not support non-interactive WeChat configuration because the iLink QR handshake requires a human to scan the QR on a paired phone. - -Run `nemoclaw onboard` interactively when you want to enable WeChat. - - -Run `nemohermes onboard` interactively when you want to enable WeChat. - +Run `$$nemoclaw onboard` interactively when you want to enable WeChat. Then run onboarding: - -```bash -nemoclaw onboard -``` - - ```bash -nemohermes onboard +$$nemoclaw onboard ``` - Complete the rest of the wizard so the blueprint can create OpenShell providers where needed (for example `-telegram-bridge` or `-wechat-bridge`), bake channel configuration into the image (`NEMOCLAW_MESSAGING_CHANNELS_B64`), and start the sandbox. @@ -206,37 +165,19 @@ Complete the rest of the wizard so the blueprint can create OpenShell providers Run channel commands from the host, not from inside the sandbox. Use `channels list` to see the supported channel names: - -```bash -nemoclaw my-assistant channels list -``` - - ```bash -nemohermes my-assistant channels list +$$nemoclaw my-assistant channels list ``` - Add the channel you want: - ```bash -nemoclaw my-assistant channels add telegram -nemoclaw my-assistant channels add discord -nemoclaw my-assistant channels add slack -nemoclaw my-assistant channels add wechat -nemoclaw my-assistant channels add whatsapp +$$nemoclaw my-assistant channels add telegram +$$nemoclaw my-assistant channels add discord +$$nemoclaw my-assistant channels add slack +$$nemoclaw my-assistant channels add wechat +$$nemoclaw my-assistant channels add whatsapp ``` - - -```bash -nemohermes my-assistant channels add telegram -nemohermes my-assistant channels add discord -nemohermes my-assistant channels add slack -nemohermes my-assistant channels add wechat -nemohermes my-assistant channels add whatsapp -``` - `channels add` collects whatever each channel needs. It prompts for Telegram, Discord, and Slack tokens, runs an interactive host-side QR scan for WeChat, and collects nothing for WhatsApp because pairing happens in-sandbox after rebuild. @@ -249,12 +190,7 @@ When the apply step itself fails after the registry write on a fresh add, NemoCl When the same failure happens on a re-add of an already-enabled channel, NemoClaw restores the prior `messagingChannels` entry, restores staged environment credentials when available, restores registry credential hashes, and attempts to re-upsert the prior bridge providers. It flags `gateway-providers` as residual because the in-flight upsert can leave the gateway with the new token. Verify the gateway bridge before relying on the channel. - -Restore the preset YAML and re-run `nemoclaw channels add `. - - -Restore the preset YAML and re-run `nemohermes channels add `. - +Restore the preset YAML and re-run `$$nemoclaw channels add `. Choose the rebuild so the running sandbox image picks up the new channel. For Telegram, Discord, and Slack, `channels add` also checks the rebuilt runtime for the selected bridge and reports startup, credential, or missing-plugin warnings before returning. If you need optional channel settings such as `TELEGRAM_ALLOWED_IDS`, `TELEGRAM_REQUIRE_MENTION`, `DISCORD_SERVER_ID`, `DISCORD_USER_ID`, `DISCORD_REQUIRE_MENTION`, `SLACK_ALLOWED_USERS`, or `SLACK_ALLOWED_CHANNELS`, export them before the rebuild starts. @@ -262,53 +198,27 @@ Telegram Bot API `sendMessage` calls prove outbound delivery from the bot; to te For a repeatable live Telegram reply check, run `test/e2e/test-messaging-providers.sh` with `TELEGRAM_BOT_TOKEN_REAL`, `TELEGRAM_AUTHORIZED_CHAT_IDS` or `TELEGRAM_CHAT_ID`, and `NEMOCLAW_TELEGRAM_INBOUND_REPLY_E2E=1`. If you defer the rebuild, apply the change later: - ```bash -nemoclaw my-assistant rebuild +$$nemoclaw my-assistant rebuild ``` - - -```bash -nemohermes my-assistant rebuild -``` - In non-interactive mode, set the required environment variables before running `channels add`. Missing credentials fail fast, and the command queues the change for a manual rebuild: - -```bash -NEMOCLAW_NON_INTERACTIVE=1 TELEGRAM_BOT_TOKEN= \ - nemoclaw my-assistant channels add telegram -nemoclaw my-assistant rebuild -``` - - ```bash NEMOCLAW_NON_INTERACTIVE=1 TELEGRAM_BOT_TOKEN= \ - nemohermes my-assistant channels add telegram -nemohermes my-assistant rebuild + $$nemoclaw my-assistant channels add telegram +$$nemoclaw my-assistant rebuild ``` - For Discord server access after onboarding, include the server settings when you add the channel and rebuild: - ```bash DISCORD_BOT_TOKEN= \ DISCORD_SERVER_ID= \ DISCORD_REQUIRE_MENTION=1 \ - nemoclaw my-assistant channels add discord + $$nemoclaw my-assistant channels add discord ``` - - -```bash -DISCORD_BOT_TOKEN= \ - DISCORD_SERVER_ID= \ - DISCORD_REQUIRE_MENTION=1 \ - nemohermes my-assistant channels add discord -``` - ### `channels add wechat` @@ -322,16 +232,9 @@ Keep the terminal in the foreground until you see `✓ WeChat login confirmed`. Second, the command requires an interactive terminal. Non-interactive mode (`NEMOCLAW_NON_INTERACTIVE=1`) fails fast with a clear error because the QR handshake needs a paired phone. - ```bash -nemoclaw my-assistant channels add wechat +$$nemoclaw my-assistant channels add wechat ``` - - -```bash -nemohermes my-assistant channels add wechat -``` - If `WECHAT_BOT_TOKEN` is already cached for this sandbox (the operator onboarded with WeChat earlier), `channels add wechat` reuses the cached token and skips the QR scan to keep the upstream plugin's existing iLink session intact. Re-running QR would invalidate that session. @@ -346,18 +249,10 @@ Rebuild the sandbox after the update so the image reflects the current channel s To remove a channel and clear its stored credentials, run: - ```bash -nemoclaw my-assistant channels remove telegram -nemoclaw my-assistant channels remove wechat +$$nemoclaw my-assistant channels remove telegram +$$nemoclaw my-assistant channels remove wechat ``` - - -```bash -nemohermes my-assistant channels remove telegram -nemohermes my-assistant channels remove wechat -``` - `channels remove wechat` clears the bot token, deletes the `-wechat-bridge` OpenShell provider, and drops `wechat` from the sandbox's enabled-channel set. The next rebuild produces an image without the WeChat channel block in `openclaw.json` and without the per-account state files under `/sandbox/.openclaw/openclaw-weixin/`. @@ -375,29 +270,14 @@ Remove the entry from the phone if you plan to re-pair the same phone with a dif Use `channels stop` when you want to pause a bridge without deleting credentials: - - -```bash -nemoclaw my-assistant channels stop telegram -nemoclaw my-assistant channels start telegram - -nemoclaw my-assistant channels stop wechat -nemoclaw my-assistant channels start wechat -``` - - - - ```bash -nemohermes my-assistant channels stop telegram -nemohermes my-assistant channels start telegram +$$nemoclaw my-assistant channels stop telegram +$$nemoclaw my-assistant channels start telegram -nemohermes my-assistant channels stop wechat -nemohermes my-assistant channels start wechat +$$nemoclaw my-assistant channels stop wechat +$$nemoclaw my-assistant channels start wechat ``` - - For WeChat specifically, `channels stop wechat` followed by a rebuild keeps the per-account state files under `/sandbox/.openclaw/openclaw-weixin/accounts/` intact even though the bridge is no longer wired up in `openclaw.json`. @@ -415,21 +295,16 @@ Running two sandboxes against the same WeChat account causes one of them to lose If you enable a messaging channel and another sandbox already uses the same token, onboarding prompts you to confirm before continuing in interactive mode and exits non-zero in non-interactive mode. If NemoClaw only has legacy channel metadata and cannot compare credential hashes, it keeps the conservative warning. Re-run `channels add ` with the intended token to refresh the stored non-secret hash. - -`nemoclaw status` reports cross-sandbox overlaps so you can resolve duplicates before messages start dropping. - - -`nemohermes status` reports cross-sandbox overlaps so you can resolve duplicates before messages start dropping. - +`$$nemoclaw status` reports cross-sandbox overlaps so you can resolve duplicates before messages start dropping. ## Stop Messaging Delivery Use `channels stop` when you want to pause one bridge and keep the sandbox running. -Use `nemoclaw tunnel stop` or its deprecated alias `nemoclaw stop` when you want to stop host auxiliary services and also ask NemoClaw to stop the OpenClaw gateway inside the selected sandbox. +Use `$$nemoclaw tunnel stop` or its deprecated alias `$$nemoclaw stop` when you want to stop host auxiliary services and also ask NemoClaw to stop the OpenClaw gateway inside the selected sandbox. -Use `nemohermes tunnel stop` when you want to stop host auxiliary services and also ask NemoClaw to stop the Hermes gateway inside the selected sandbox. +Use `$$nemoclaw tunnel stop` when you want to stop host auxiliary services and also ask NemoClaw to stop the Hermes gateway inside the selected sandbox. Stopping the in-sandbox gateway stops Telegram, Discord, Slack, WeChat, and WhatsApp polling for that sandbox until you restart the sandbox or gateway. @@ -442,30 +317,23 @@ Use the matching policy preset (`telegram`, `discord`, `slack`, `wechat`, or `wh ## Tunnel Command -When the host has `cloudflared`, `nemoclaw tunnel start` starts a cloudflared tunnel that can expose the dashboard with a public URL. +When the host has `cloudflared`, `$$nemoclaw tunnel start` starts a cloudflared tunnel that can expose the dashboard with a public URL. -When the host has `cloudflared`, `nemohermes tunnel start` starts a cloudflared tunnel that can expose the forwarded Hermes endpoint with a public URL. +When the host has `cloudflared`, `$$nemoclaw tunnel start` starts a cloudflared tunnel that can expose the forwarded Hermes endpoint with a public URL. Set `CLOUDFLARE_TUNNEL_TOKEN` before running the command when you want to use a Cloudflare named tunnel instead of a generated quick-tunnel URL. -`nemoclaw tunnel stop` stops the tunnel and asks NemoClaw to stop the in-sandbox gateway for the selected or default sandbox. -The older `nemoclaw start` still works as a deprecated alias. +`$$nemoclaw tunnel stop` stops the tunnel and asks NemoClaw to stop the in-sandbox gateway for the selected or default sandbox. +The older `$$nemoclaw start` still works as a deprecated alias. -`nemohermes tunnel stop` stops the tunnel and asks NemoClaw to stop the in-sandbox gateway for the selected or default sandbox. +`$$nemoclaw tunnel stop` stops the tunnel and asks NemoClaw to stop the in-sandbox gateway for the selected or default sandbox. - -```bash -nemoclaw tunnel start -``` - - ```bash -nemohermes tunnel start +$$nemoclaw tunnel start ``` - ## Related Topics diff --git a/docs/manage-sandboxes/runtime-controls.mdx b/docs/manage-sandboxes/runtime-controls.mdx index ca72cdce82..a55ccf862a 100644 --- a/docs/manage-sandboxes/runtime-controls.mdx +++ b/docs/manage-sandboxes/runtime-controls.mdx @@ -24,17 +24,17 @@ The table below maps each commonly changed item to the layer that owns it and th | Item | When the change takes effect | How to change it | |---|---|---| -| Inference provider (cloud, NVIDIA Endpoints, local Ollama / vLLM, compatible-endpoint, …) | Rebuild required (`openclaw.json` is locked at sandbox creation) | `nemoclaw rebuild` after picking a different provider with `nemoclaw inference set` | -| Inference model on the current provider | Rebuild required for OpenClaw; hot-reloadable for managed routers | `nemoclaw rebuild` (OpenClaw) or `nemoclaw inference set` (router-based) | -| Sub-agent (Hermes / OpenClaw / …) | Re-onboard required (the sub-agent and its workspace are baked at onboard) | `nemoclaw onboard --recreate-sandbox` | -| Network policy preset (slack, discord, telegram, brave, …) | Runtime. Applies on the next request; rebuild only required if the preset adds bind-mounted secrets | `nemoclaw policy-add ` / `policy-remove ` | +| Inference provider (cloud, NVIDIA Endpoints, local Ollama / vLLM, compatible-endpoint, …) | Rebuild required (`openclaw.json` is locked at sandbox creation) | `$$nemoclaw rebuild` after picking a different provider with `$$nemoclaw inference set` | +| Inference model on the current provider | Rebuild required for OpenClaw; hot-reloadable for managed routers | `$$nemoclaw rebuild` (OpenClaw) or `$$nemoclaw inference set` (router-based) | +| Sub-agent (Hermes / OpenClaw / …) | Re-onboard required (the sub-agent and its workspace are baked at onboard) | `$$nemoclaw onboard --recreate-sandbox` | +| Network policy preset (slack, discord, telegram, brave, …) | Runtime. Applies on the next request; rebuild only required if the preset adds bind-mounted secrets | `$$nemoclaw policy-add ` / `policy-remove ` | | Network allow-list (custom hosts) | Runtime. Picks up at next request | `openshell policy set` or interactive approval prompt at the gateway | -| Channel tokens (Slack / Discord / Telegram bot credentials) | Rebuild required (tokens are baked into the sandbox image at onboard so they never leave the host clear-text) | `nemoclaw channels add ` then accept the rebuild prompt | -| Channel enable/disable (turn a configured channel off without removing the token) | Rebuild required (`openclaw.json` is the source of truth at runtime, see #3453) | `nemoclaw channels stop ` then rebuild | -| Dashboard forward port | Runtime. Port is re-resolved on next `connect` | `NEMOCLAW_DASHBOARD_PORT= nemoclaw connect` | -| Dashboard bind address (loopback compared to all interfaces) | Runtime. Applies on next `connect` | `NEMOCLAW_DASHBOARD_BIND=0.0.0.0 nemoclaw connect` (see #3259) | -| Web search backend (Brave, Tavily, and so on) | Runtime through `web.backend` config flag; rebuild only if `web.fetchEnabled` flips | `nemoclaw config set --key web.backend --value tavily` | -| Filesystem layout (Landlock zones, read-only mounts, container caps) | **Locked at creation**. No runtime change | Re-onboard with `nemoclaw onboard --recreate-sandbox` | +| Channel tokens (Slack / Discord / Telegram bot credentials) | Rebuild required (tokens are baked into the sandbox image at onboard so they never leave the host clear-text) | `$$nemoclaw channels add ` then accept the rebuild prompt | +| Channel enable/disable (turn a configured channel off without removing the token) | Rebuild required (`openclaw.json` is the source of truth at runtime, see #3453) | `$$nemoclaw channels stop ` then rebuild | +| Dashboard forward port | Runtime. Port is re-resolved on next `connect` | `NEMOCLAW_DASHBOARD_PORT= $$nemoclaw connect` | +| Dashboard bind address (loopback compared to all interfaces) | Runtime. Applies on next `connect` | `NEMOCLAW_DASHBOARD_BIND=0.0.0.0 $$nemoclaw connect` (see #3259) | +| Web search backend (Brave, Tavily, and so on) | Runtime through `web.backend` config flag; rebuild only if `web.fetchEnabled` flips | `$$nemoclaw config set --key web.backend --value tavily` | +| Filesystem layout (Landlock zones, read-only mounts, container caps) | **Locked at creation**. No runtime change | Re-onboard with `$$nemoclaw onboard --recreate-sandbox` | | Sandbox name | **Locked at creation** | Re-onboard with a different `--name` | | GPU passthrough enable / device selector | **Locked at creation** | Re-onboard with `--gpu` / `--sandbox-gpu-device` | | Agents allow-list (`agents.list` in `openclaw.json`) | Runtime. OpenClaw hot-reloads on config change | Prefer agent or NemoClaw commands that keep host and sandbox state aligned | @@ -47,18 +47,18 @@ If a row above conflicts with what you observe, the runtime source of truth insi | Item | When the change takes effect | How to change it | |---|---|---| -| Inference provider (cloud, NVIDIA Endpoints, local Ollama / vLLM, compatible-endpoint, …) | Runtime route changes apply immediately; rebuild if you need to rebake model metadata into the image | `nemohermes inference set` for route changes, or `nemohermes rebuild` after changing build-time settings | -| Inference model on the current provider | Hot-reloadable through the Hermes config sync path | `nemohermes inference set` | -| Agent runtime (Hermes compared to OpenClaw) | Re-onboard required (the agent and its state layout are baked at onboard) | `nemohermes onboard --recreate-sandbox` or `nemoclaw onboard --agent openclaw --recreate-sandbox` | -| Network policy preset (slack, discord, telegram, brave, …) | Runtime. Applies on the next request; rebuild only required if the preset adds bind-mounted secrets | `nemohermes policy-add ` / `policy-remove ` | +| Inference provider (cloud, NVIDIA Endpoints, local Ollama / vLLM, compatible-endpoint, …) | Runtime route changes apply immediately; rebuild if you need to rebake model metadata into the image | `$$nemoclaw inference set` for route changes, or `$$nemoclaw rebuild` after changing build-time settings | +| Inference model on the current provider | Hot-reloadable through the Hermes config sync path | `$$nemoclaw inference set` | +| Agent runtime (Hermes compared to OpenClaw) | Re-onboard required (the agent and its state layout are baked at onboard) | `$$nemoclaw onboard --recreate-sandbox` or `nemoclaw onboard --agent openclaw --recreate-sandbox` | +| Network policy preset (slack, discord, telegram, brave, …) | Runtime. Applies on the next request; rebuild only required if the preset adds bind-mounted secrets | `$$nemoclaw policy-add ` / `policy-remove ` | | Network allow-list (custom hosts) | Runtime. Picks up at next request | `openshell policy set` or interactive approval prompt at the gateway | -| Channel tokens (Slack / Discord / Telegram bot credentials) | Rebuild required (tokens are baked into the sandbox image at onboard so they never leave the host clear-text) | `nemohermes channels add ` then accept the rebuild prompt | -| Channel enable/disable (turn a configured channel off without removing the token) | Rebuild required (`/sandbox/.hermes/.env` and Hermes config are baked at image build time) | `nemohermes channels stop ` then rebuild | -| API/dashboard forward port | Runtime. Port is re-resolved on next `connect` | `nemohermes connect` or `openshell forward start` | -| Filesystem layout (Landlock zones, read-only mounts, container caps) | **Locked at creation**. No runtime change | Re-onboard with `nemohermes onboard --recreate-sandbox` | +| Channel tokens (Slack / Discord / Telegram bot credentials) | Rebuild required (tokens are baked into the sandbox image at onboard so they never leave the host clear-text) | `$$nemoclaw channels add ` then accept the rebuild prompt | +| Channel enable/disable (turn a configured channel off without removing the token) | Rebuild required (`/sandbox/.hermes/.env` and Hermes config are baked at image build time) | `$$nemoclaw channels stop ` then rebuild | +| API/dashboard forward port | Runtime. Port is re-resolved on next `connect` | `$$nemoclaw connect` or `openshell forward start` | +| Filesystem layout (Landlock zones, read-only mounts, container caps) | **Locked at creation**. No runtime change | Re-onboard with `$$nemoclaw onboard --recreate-sandbox` | | Sandbox name | **Locked at creation** | Re-onboard with a different `--name` | | GPU passthrough enable / device selector | **Locked at creation** | Re-onboard with `--gpu` / `--sandbox-gpu-device` | -| Hermes `config.yaml` keys | Mixed. Inference keys can be patched by `nemohermes inference set`; image, policy, and channel changes still require rebuild. | Prefer NemoClaw host commands so the host registry and rebuilt image stay aligned | +| Hermes `config.yaml` keys | Mixed. Inference keys can be patched by `$$nemoclaw inference set`; image, policy, and channel changes still require rebuild. | Prefer NemoClaw host commands so the host registry and rebuilt image stay aligned | If a row above conflicts with what you observe, the runtime source of truth for Hermes is `/sandbox/.hermes/config.yaml` plus `/sandbox/.hermes/.env`; the host @@ -78,7 +78,7 @@ The mutability table above is a consolidated index of information that lives in - [Customize Network Policy](../network-policy/customize-network-policy) and [Approve Network Requests](../network-policy/approve-network-requests) for runtime policy editing and operator approval flow. - [Security Best Practices](../security/best-practices) for the per-attack-surface posture table that this page complements. - [OpenClaw Security Controls](../security/openclaw-controls) for application-layer controls that operate independently of NemoClaw. -- [CLI Commands Reference](../reference/commands) for the full flag surface for every `nemoclaw` command, including the environment variables that affect runtime behavior. +- [CLI Commands Reference](../reference/commands) for the full flag surface for every `$$nemoclaw` command, including the environment variables that affect runtime behavior. @@ -87,6 +87,6 @@ The mutability table above is a consolidated index of information that lives in - [Switch Inference Providers](../inference/switch-inference-providers) for the runtime route and rebuild paths for provider and model changes. - [Customize Network Policy](../network-policy/customize-network-policy) and [Approve Network Requests](../network-policy/approve-network-requests) for runtime policy editing and operator approval flow. - [Security Best Practices](../security/best-practices) for the per-attack-surface posture table that this page complements. -- [CLI Commands Reference](../reference/commands) for the full flag surface for every `nemohermes` and `nemoclaw` command, including the environment variables that affect runtime behavior. +- [CLI Commands Reference](../reference/commands) for the full flag surface for every `$$nemoclaw` and `nemoclaw` command, including the environment variables that affect runtime behavior. diff --git a/docs/manage-sandboxes/workspace-files.mdx b/docs/manage-sandboxes/workspace-files.mdx index 55bef895c1..a7d5b4e642 100644 --- a/docs/manage-sandboxes/workspace-files.mdx +++ b/docs/manage-sandboxes/workspace-files.mdx @@ -64,7 +64,7 @@ Files are per-agent. Changes in `workspace-main/AGENTS.md` are not visible to `workspace-support/`. NemoClaw handles persistence and snapshots automatically for per-agent workspaces: -the sandbox entrypoint provisions each `workspace-/` directly under the writable `.openclaw/` tree so state survives sandbox restart, and `nemoclaw snapshot create` discovers every `workspace-/` directory and includes it in the snapshot bundle alongside the default `workspace/`. +the sandbox entrypoint provisions each `workspace-/` directly under the writable `.openclaw/` tree so state survives sandbox restart, and `$$nemoclaw snapshot create` discovers every `workspace-/` directory and includes it in the snapshot bundle alongside the default `workspace/`. Files that operators typically want consistent across every agent workspace @@ -82,18 +82,18 @@ They survive normal container restarts, but NemoClaw deletes them when you destr Sandbox restarts preserve workspace files because the persistent state volume outlives individual container restarts. -The `nemoclaw rebuild` command and the sandbox upgrade flow also preserve workspace state. +The `$$nemoclaw rebuild` command and the sandbox upgrade flow also preserve workspace state. Before replacing the container, NemoClaw snapshots the workspace state directories and restores them into the rebuilt sandbox. If NemoClaw cannot archive any requested state file or directory, it reports the backup failure and stops before replacing the sandbox. It does not continue with a partial backup. ### Deleted During Sandbox Destroy -Running `nemoclaw destroy` deletes the sandbox and its persistent state volume. +Running `$$nemoclaw destroy` deletes the sandbox and its persistent state volume. NemoClaw removes workspace files from the sandbox unless you created a snapshot or backup first. -Back up your workspace files before running `nemoclaw destroy`. +Back up your workspace files before running `$$nemoclaw destroy`. See [Backup and Restore](backup-restore) for instructions. @@ -103,7 +103,7 @@ The agent reads these files at the start of every session. You can edit them in two ways: 1. Ask your agent to update its persona, memory, or user context. -2. Use `nemoclaw connect` to open a terminal inside the sandbox and edit files directly, or use `openshell sandbox upload` to push edited files from your host. +2. Use `$$nemoclaw connect` to open a terminal inside the sandbox and edit files directly, or use `openshell sandbox upload` to push edited files from your host. ## Next Steps @@ -134,14 +134,14 @@ Hermes state lives in the sandbox's persistent state volume, not only in the con Normal restarts preserve that state. Rebuilds and upgrades use NemoClaw's snapshot flow to preserve manifest-defined Hermes state, including `SOUL.md` and the SQLite database behind `.hermes/state.db`. -Running `nemohermes destroy` deletes the sandbox and its persistent state volume. +Running `$$nemoclaw destroy` deletes the sandbox and its persistent state volume. Back up important state before destroying a Hermes sandbox. ## Editing State Prefer NemoClaw host commands for generated configuration such as model, provider, messaging, and policy settings. Direct edits to `/sandbox/.hermes/config.yaml` or `/sandbox/.hermes/.env` can be overwritten by rebuilds. -Use `nemohermes connect` when you need to inspect runtime files interactively, or use `openshell sandbox download` and `openshell sandbox upload` for manual file transfer. +Use `$$nemoclaw connect` when you need to inspect runtime files interactively, or use `openshell sandbox download` and `openshell sandbox upload` for manual file transfer. ## Next Steps diff --git a/docs/monitoring/monitor-sandbox-activity.mdx b/docs/monitoring/monitor-sandbox-activity.mdx index ae326a8632..01c11df3af 100644 --- a/docs/monitoring/monitor-sandbox-activity.mdx +++ b/docs/monitoring/monitor-sandbox-activity.mdx @@ -24,23 +24,11 @@ Use the NemoClaw status, logs, and TUI tools together to inspect sandbox health, Run the status command to view the sandbox state, gateway health, and active inference configuration: - -```bash -nemoclaw status -``` - - ```bash -nemohermes status +$$nemoclaw status ``` - - -For local Ollama and local vLLM routes, `nemoclaw status` also probes the host-side health endpoint directly. - - -For local Ollama and local vLLM routes, `nemohermes status` also probes the host-side health endpoint directly. - +For local Ollama and local vLLM routes, `$$nemoclaw status` also probes the host-side health endpoint directly. This check catches a stopped local backend before you retry `inference.local` from inside the sandbox. Key output fields include: @@ -50,41 +38,22 @@ Key output fields include: - Inference health for local Ollama and local vLLM shows `healthy` or `unreachable` together with the probed local URL. - NIM status shows whether a NIM container is running and healthy when that path is in use. - -Run `nemoclaw status` on the host to check sandbox state. - - -Run `nemohermes status` on the host to check sandbox state. - +Run `$$nemoclaw status` on the host to check sandbox state. Use `openshell sandbox list` for the underlying sandbox details. ## View Blueprint and Sandbox Logs Stream the most recent log output from the blueprint runner and sandbox: - -```bash -nemoclaw logs -``` - - ```bash -nemohermes logs +$$nemoclaw logs ``` - To follow the log output in real time: - ```bash -nemoclaw logs --follow +$$nemoclaw logs --follow ``` - - -```bash -nemohermes logs --follow -``` - The `logs` command shows lifecycle and gateway output. It does not export the structured per-session agent state that OpenClaw stores under `.openclaw/agents/`. @@ -103,7 +72,7 @@ Use these files when you need an audit trail, a compliance review surface, or re To inspect the session directory from the host, run a sandbox command: ```console -$ nemoclaw sandbox exec -- ls -lh /sandbox/.openclaw/agents/main/sessions +$ $$nemoclaw sandbox exec -- ls -lh /sandbox/.openclaw/agents/main/sessions ``` To copy a session log for offline review, use the OpenShell sandbox download command: @@ -139,38 +108,25 @@ Run a test inference request to verify that the provider is responding: ```bash -nemoclaw my-assistant connect +$$nemoclaw my-assistant connect openclaw agent --agent main -m "Test inference" --session-id debug ``` ```bash -nemohermes my-hermes connect +$$nemoclaw my-hermes connect hermes ``` If the request fails, check the following: - - -1. Run `nemoclaw status` to confirm the active provider and endpoint. +1. Run `$$nemoclaw status` to confirm the active provider and endpoint. For local Ollama and local vLLM, check the `Inference` line first. If it shows `unreachable`, restart the local backend before retrying from inside the sandbox. -2. Run `nemoclaw logs --follow` to view error messages from the blueprint runner. +2. Run `$$nemoclaw logs --follow` to view error messages from the blueprint runner. 3. Verify that the inference endpoint is reachable from the host. - - - -1. Run `nemohermes status` to confirm the active provider and endpoint. - For local Ollama and local vLLM, check the `Inference` line first. - If it shows `unreachable`, restart the local backend before retrying from inside the sandbox. -2. Run `nemohermes logs --follow` to view error messages from the blueprint runner. -3. Verify that the inference endpoint is reachable from the host. - - - ## Related Topics - [Troubleshooting](../reference/troubleshooting) for common issues and resolution steps. diff --git a/docs/network-policy/customize-network-policy.mdx b/docs/network-policy/customize-network-policy.mdx index cc3b3f36d2..8edc8f3dc9 100644 --- a/docs/network-policy/customize-network-policy.mdx +++ b/docs/network-policy/customize-network-policy.mdx @@ -20,12 +20,7 @@ NemoClaw supports both static policy changes that persist across restarts and dy If the sandbox needs to reach an HTTP service running on the host, expose the service on a host IP that the OpenShell gateway can reach. - -Apply a custom NemoClaw preset with `nemoclaw policy-add --from-file`. - - -Apply a custom NemoClaw preset with `nemohermes policy-add --from-file`. - +Apply a custom NemoClaw preset with `$$nemoclaw policy-add --from-file`. Do not rely on `host.docker.internal` as a general host-service path because it bypasses the OpenShell policy path and may not be reachable in every sandbox runtime. See [Agent cannot reach a host-side HTTP service](../reference/troubleshooting#agent-cannot-reach-a-host-side-http-service). @@ -33,7 +28,7 @@ See [Agent cannot reach a host-side HTTP service](../reference/troubleshooting#a Adding a host to the egress policy permits the connection only after the endpoint, port, method, and binary rules match. OpenShell still applies SSRF protection separately, so a request can be denied if the final address resolves to a loopback, private, link-local, or otherwise blocked internal range. -If a package installer or browser runtime download still fails with an SSRF-style denial after you add the public host, install that binary into the sandbox image at build time with [`nemoclaw onboard --from`](/reference/commands#--from-dockerfile) instead of relying on runtime egress. +If a package installer or browser runtime download still fails with an SSRF-style denial after you add the public host, install that binary into the sandbox image at build time with [`$$nemoclaw onboard --from`](/reference/commands#--from-dockerfile) instead of relying on runtime egress. ## Prerequisites @@ -55,17 +50,17 @@ Static changes modify the baseline policy file and take effect after the next sa Open `nemoclaw-blueprint/policies/openclaw-sandbox.yaml` and add or modify endpoint entries. -If you want a built-in preset to be part of the baseline policy, merge its `network_policies` entries into this file and re-run `nemoclaw onboard`. +If you want a built-in preset to be part of the baseline policy, merge its `network_policies` entries into this file and re-run `$$nemoclaw onboard`. -If you only need to apply a preset to a running sandbox, use `nemoclaw policy-add` under [Dynamic Changes](#dynamic-changes). +If you only need to apply a preset to a running sandbox, use `$$nemoclaw policy-add` under [Dynamic Changes](#dynamic-changes). That updates the live policy and does not edit `openclaw-sandbox.yaml`. Open the Hermes policy additions and shared sandbox policy files under `agents/hermes/` and `nemoclaw-blueprint/policies/`, then add or modify endpoint entries. -If you want a built-in preset to be part of the baseline policy, merge its `network_policies` entries into the appropriate policy file and re-run `nemohermes onboard`. +If you want a built-in preset to be part of the baseline policy, merge its `network_policies` entries into the appropriate policy file and re-run `$$nemoclaw onboard`. -If you only need to apply a preset to a running sandbox, use `nemohermes policy-add` under [Dynamic Changes](#dynamic-changes). +If you only need to apply a preset to a running sandbox, use `$$nemoclaw policy-add` under [Dynamic Changes](#dynamic-changes). That updates the live policy and does not edit the baseline policy files. @@ -86,16 +81,9 @@ Each entry in the `network` section defines an endpoint group with the following Apply the updated policy by re-running the onboard wizard: - ```bash -nemoclaw onboard +$$nemoclaw onboard ``` - - -```bash -nemohermes onboard -``` - The wizard reads the modified policy file and applies it to the sandbox. @@ -103,16 +91,9 @@ The wizard reads the modified policy file and applies it to the sandbox. Check that the sandbox is running with the updated policy: - -```bash -nemoclaw status -``` - - ```bash -nemohermes status +$$nemoclaw status ``` - ### Add Blueprint Policy Additions @@ -156,21 +137,10 @@ This is the non-destructive path and the only flow NemoClaw supports out of the 2. Apply it to the running sandbox: - - -```bash -nemoclaw my-assistant policy-add -``` - - - - ```bash -nemohermes my-assistant policy-add +$$nemoclaw my-assistant policy-add ``` - - NemoClaw reads the live policy via `openshell policy get --full`, structurally merges your preset's `network_policies` into it, and writes the merged result back. Existing presets and the baseline remain in place. The preset file under `presets/` also persists across sandbox recreations. @@ -195,10 +165,10 @@ openshell policy set --policy live-policy.yaml my-assistant Dynamic changes apply only to the current session. When the sandbox stops, the running policy resets to the baseline policy plus the presets recorded for the sandbox. -To make a custom policy survive a sandbox recreation, ship the preset file in the repository (Option 1 above; the file under `presets/` persists) or edit `openclaw-sandbox.yaml` and re-run `nemoclaw onboard`. +To make a custom policy survive a sandbox recreation, ship the preset file in the repository (Option 1 above; the file under `presets/` persists) or edit `openclaw-sandbox.yaml` and re-run `$$nemoclaw onboard`. -To make a custom policy survive a sandbox recreation, ship the preset file in the repository (Option 1 above; the file under `presets/` persists) or edit the Hermes policy additions and re-run `nemohermes onboard`. +To make a custom policy survive a sandbox recreation, ship the preset file in the repository (Option 1 above; the file under `presets/` persists) or edit the Hermes policy additions and re-run `$$nemoclaw onboard`. ### Approve Requests Interactively @@ -242,16 +212,9 @@ Available presets: To apply a preset to a running sandbox: - -```bash -nemoclaw policy-add -``` - - ```bash -nemohermes policy-add +$$nemoclaw policy-add ``` - Preset selection is interactive when you omit a preset name. @@ -260,71 +223,39 @@ Pass a preset name with `--yes` for scripted workflows. For example, to interactively add PyPI access to a running sandbox: - -```bash -nemoclaw my-assistant policy-add -``` - - ```bash -nemohermes my-assistant policy-add +$$nemoclaw my-assistant policy-add ``` - To list which presets are applied to a sandbox: - -```bash -nemoclaw policy-list -``` - - ```bash -nemohermes policy-list +$$nemoclaw policy-list ``` - -To include a preset in the baseline, merge its entries into `openclaw-sandbox.yaml` and re-run `nemoclaw onboard`. +To include a preset in the baseline, merge its entries into `openclaw-sandbox.yaml` and re-run `$$nemoclaw onboard`. -To include a preset in the baseline, merge its entries into the Hermes policy additions and re-run `nemohermes onboard`. +To include a preset in the baseline, merge its entries into the Hermes policy additions and re-run `$$nemoclaw onboard`. The `openshell policy set --policy ` command operates on raw policy files and does not accept the `preset:` metadata block used in preset YAML files. - -Use `nemoclaw policy-add` for presets. - - -Use `nemohermes policy-add` for presets. - +Use `$$nemoclaw policy-add` for presets. For scripted workflows, `policy-add` and `policy-remove` accept the preset name as a positional argument: - -```bash -nemoclaw my-assistant policy-add pypi --yes -nemoclaw my-assistant policy-remove pypi --yes -``` - - ```bash -nemohermes my-assistant policy-add pypi --yes -nemohermes my-assistant policy-remove pypi --yes +$$nemoclaw my-assistant policy-add pypi --yes +$$nemoclaw my-assistant policy-remove pypi --yes ``` - Set `NEMOCLAW_NON_INTERACTIVE=1` instead of `--yes` to drive the same flow from an environment variable. -See [Commands](../reference/commands#nemoclaw-name-policy-add) for the full flag reference. +See [Commands](../reference/commands#$$nemoclaw-name-policy-add) for the full flag reference. - -`nemoclaw rebuild` reapplies every policy preset to the recreated sandbox, so presets survive an agent-version upgrade without manual reapplication. - - -`nemohermes rebuild` reapplies every policy preset to the recreated sandbox, so presets survive an agent-version upgrade without manual reapplication. - +`$$nemoclaw rebuild` reapplies every policy preset to the recreated sandbox, so presets survive an agent-version upgrade without manual reapplication. ## Custom Preset Files @@ -357,31 +288,17 @@ Rename `preset.name` if NemoClaw refuses to apply the file because of a collisio ### Apply a Single File - -```bash -nemoclaw my-assistant policy-add --from-file ./presets/my-internal-api.yaml -``` - - ```bash -nemohermes my-assistant policy-add --from-file ./presets/my-internal-api.yaml +$$nemoclaw my-assistant policy-add --from-file ./presets/my-internal-api.yaml ``` - Preview the endpoints without applying with `--dry-run`, and skip the confirmation prompt with `--yes` or by exporting `NEMOCLAW_NON_INTERACTIVE=1`. ### Apply Every File in a Directory - ```bash -nemoclaw my-assistant policy-add --from-dir ./presets/ --yes +$$nemoclaw my-assistant policy-add --from-dir ./presets/ --yes ``` - - -```bash -nemohermes my-assistant policy-add --from-dir ./presets/ --yes -``` - Files are processed in lexicographic order. Processing stops at the first failure; presets already applied are not rolled back. @@ -397,23 +314,11 @@ Review every host in a custom preset before applying it, especially when the fil NemoClaw records custom presets applied with `--from-file` or `--from-dir` in the sandbox registry alongside their full YAML content. You can remove them by name without keeping the original file on disk: - -```bash -nemoclaw my-assistant policy-remove my-internal-api --yes -``` - - ```bash -nemohermes my-assistant policy-remove my-internal-api --yes +$$nemoclaw my-assistant policy-remove my-internal-api --yes ``` - - -`policy-remove` accepts both built-in and custom preset names. Run `nemoclaw policy-list` to see every preset currently applied to the sandbox. - - -`policy-remove` accepts both built-in and custom preset names. Run `nemohermes policy-list` to see every preset currently applied to the sandbox. - +`policy-remove` accepts both built-in and custom preset names. Run `$$nemoclaw policy-list` to see every preset currently applied to the sandbox. ## Related Topics diff --git a/docs/network-policy/integration-policy-examples.mdx b/docs/network-policy/integration-policy-examples.mdx index eb4eb6172c..56b0ffe023 100644 --- a/docs/network-policy/integration-policy-examples.mdx +++ b/docs/network-policy/integration-policy-examples.mdx @@ -29,16 +29,9 @@ Replace `my-assistant` with your sandbox name in the examples. Check the current policy state first: - -```bash -nemoclaw my-assistant policy-list -``` - - ```bash -nemohermes my-assistant policy-list +$$nemoclaw my-assistant policy-list ``` - For a live view of blocked requests, open the OpenShell TUI in a separate host terminal: @@ -74,60 +67,31 @@ NemoClaw ships maintained policy presets for common services in `nemoclaw-bluepr Preview the endpoints before applying: - ```bash -nemoclaw my-assistant policy-add outlook --dry-run +$$nemoclaw my-assistant policy-add outlook --dry-run ``` - - -```bash -nemohermes my-assistant policy-add outlook --dry-run -``` - Apply the preset: - ```bash -nemoclaw my-assistant policy-add outlook --yes +$$nemoclaw my-assistant policy-add outlook --yes ``` - - -```bash -nemohermes my-assistant policy-add outlook --yes -``` - Remove it later if the sandbox no longer needs that access: - ```bash -nemoclaw my-assistant policy-remove outlook --yes +$$nemoclaw my-assistant policy-remove outlook --yes ``` - - -```bash -nemohermes my-assistant policy-remove outlook --yes -``` - ## Email and Calendar With Microsoft 365 Use the `outlook` preset for Microsoft 365 email and calendar workflows that use Microsoft Graph or Outlook endpoints. The preset allows `graph.microsoft.com`, Microsoft login, and Outlook service endpoints. - -```bash -nemoclaw my-assistant policy-add outlook --dry-run -nemoclaw my-assistant policy-add outlook --yes -``` - - ```bash -nemohermes my-assistant policy-add outlook --dry-run -nemohermes my-assistant policy-add outlook --yes +$$nemoclaw my-assistant policy-add outlook --dry-run +$$nemoclaw my-assistant policy-add outlook --yes ``` - Then configure the email or calendar tool credentials through the integration you are running in the sandbox. Keep OAuth client secrets and refresh tokens out of policy files. @@ -140,35 +104,18 @@ If the blocked endpoint is not covered by the maintained `outlook` preset, treat Telegram needs both channel configuration and egress policy. If you already enabled Telegram during onboarding but did not include the preset, add it to the running sandbox: - ```bash -nemoclaw my-assistant policy-add telegram --yes +$$nemoclaw my-assistant policy-add telegram --yes ``` - - -```bash -nemohermes my-assistant policy-add telegram --yes -``` - To add Telegram after onboarding, set the token on the host, add the channel, rebuild so the image picks up the channel config, and make sure the policy preset is applied: - ```bash export TELEGRAM_BOT_TOKEN= -NEMOCLAW_NON_INTERACTIVE=1 nemoclaw my-assistant channels add telegram -nemoclaw my-assistant rebuild -nemoclaw my-assistant policy-add telegram --yes +NEMOCLAW_NON_INTERACTIVE=1 $$nemoclaw my-assistant channels add telegram +$$nemoclaw my-assistant rebuild +$$nemoclaw my-assistant policy-add telegram --yes ``` - - -```bash -export TELEGRAM_BOT_TOKEN= -NEMOCLAW_NON_INTERACTIVE=1 nemohermes my-assistant channels add telegram -nemohermes my-assistant rebuild -nemohermes my-assistant policy-add telegram --yes -``` - If delivery fails, open the TUI and send a test message to the bot: @@ -185,60 +132,30 @@ Use the matching policy preset after you configure the channel credentials. For Slack: - ```bash export SLACK_BOT_TOKEN= export SLACK_APP_TOKEN= -NEMOCLAW_NON_INTERACTIVE=1 nemoclaw my-assistant channels add slack -nemoclaw my-assistant rebuild -nemoclaw my-assistant policy-add slack --yes +NEMOCLAW_NON_INTERACTIVE=1 $$nemoclaw my-assistant channels add slack +$$nemoclaw my-assistant rebuild +$$nemoclaw my-assistant policy-add slack --yes ``` - - -```bash -export SLACK_BOT_TOKEN= -export SLACK_APP_TOKEN= -NEMOCLAW_NON_INTERACTIVE=1 nemohermes my-assistant channels add slack -nemohermes my-assistant rebuild -nemohermes my-assistant policy-add slack --yes -``` - For Discord: - ```bash export DISCORD_BOT_TOKEN= export DISCORD_SERVER_ID= -NEMOCLAW_NON_INTERACTIVE=1 nemoclaw my-assistant channels add discord -nemoclaw my-assistant rebuild -nemoclaw my-assistant policy-add discord --yes +NEMOCLAW_NON_INTERACTIVE=1 $$nemoclaw my-assistant channels add discord +$$nemoclaw my-assistant rebuild +$$nemoclaw my-assistant policy-add discord --yes ``` - - -```bash -export DISCORD_BOT_TOKEN= -export DISCORD_SERVER_ID= -NEMOCLAW_NON_INTERACTIVE=1 nemohermes my-assistant channels add discord -nemohermes my-assistant rebuild -nemohermes my-assistant policy-add discord --yes -``` - If you enabled Slack or Discord during onboarding, apply only the matching preset: - ```bash -nemoclaw my-assistant policy-add slack --yes -nemoclaw my-assistant policy-add discord --yes +$$nemoclaw my-assistant policy-add slack --yes +$$nemoclaw my-assistant policy-add discord --yes ``` - - -```bash -nemohermes my-assistant policy-add slack --yes -nemohermes my-assistant policy-add discord --yes -``` - ## WeChat or WhatsApp Messaging (Experimental) @@ -250,53 +167,27 @@ WeChat uses Tencent's iLink Bot API for personal accounts. The bot token is captured by a host-side QR scan during onboarding rather than pasted from a developer portal. Add the channel interactively and apply the preset: - -```bash -nemoclaw my-assistant channels add wechat -nemoclaw my-assistant rebuild -nemoclaw my-assistant policy-add wechat --yes -``` - - ```bash -nemohermes my-assistant channels add wechat -nemohermes my-assistant rebuild -nemohermes my-assistant policy-add wechat --yes +$$nemoclaw my-assistant channels add wechat +$$nemoclaw my-assistant rebuild +$$nemoclaw my-assistant policy-add wechat --yes ``` - WhatsApp Web pairs entirely inside the sandbox through QR scan, so `channels add` does not collect a host-side token. Apply the preset and complete the in-sandbox pairing after the rebuild: - ```bash -NEMOCLAW_NON_INTERACTIVE=1 nemoclaw my-assistant channels add whatsapp -nemoclaw my-assistant rebuild -nemoclaw my-assistant policy-add whatsapp --yes +NEMOCLAW_NON_INTERACTIVE=1 $$nemoclaw my-assistant channels add whatsapp +$$nemoclaw my-assistant rebuild +$$nemoclaw my-assistant policy-add whatsapp --yes ``` - - -```bash -NEMOCLAW_NON_INTERACTIVE=1 nemohermes my-assistant channels add whatsapp -nemohermes my-assistant rebuild -nemohermes my-assistant policy-add whatsapp --yes -``` - If you enabled WeChat or WhatsApp during onboarding, apply only the matching preset: - -```bash -nemoclaw my-assistant policy-add wechat --yes -nemoclaw my-assistant policy-add whatsapp --yes -``` - - ```bash -nemohermes my-assistant policy-add wechat --yes -nemohermes my-assistant policy-add whatsapp --yes +$$nemoclaw my-assistant policy-add wechat --yes +$$nemoclaw my-assistant policy-add whatsapp --yes ``` - ## GitHub and Jira @@ -305,33 +196,17 @@ Use `jira` when the agent needs Atlassian Jira access. Preview first: - ```bash -nemoclaw my-assistant policy-add github --dry-run -nemoclaw my-assistant policy-add jira --dry-run +$$nemoclaw my-assistant policy-add github --dry-run +$$nemoclaw my-assistant policy-add jira --dry-run ``` - - -```bash -nemohermes my-assistant policy-add github --dry-run -nemohermes my-assistant policy-add jira --dry-run -``` - Apply the preset that matches the workflow: - ```bash -nemoclaw my-assistant policy-add github --yes -nemoclaw my-assistant policy-add jira --yes +$$nemoclaw my-assistant policy-add github --yes +$$nemoclaw my-assistant policy-add jira --yes ``` - - -```bash -nemohermes my-assistant policy-add github --yes -nemohermes my-assistant policy-add jira --yes -``` - The `jira` preset intentionally allows Node.js access to Atlassian Cloud and does not allow `curl`. When validating it manually, avoid plain `curl -s` against `auth.atlassian.com`. @@ -350,36 +225,20 @@ This manual probe proves curl reached Atlassian, but no Jira credentials were su Remove access when the task is done: - ```bash -nemoclaw my-assistant policy-remove github --yes -nemoclaw my-assistant policy-remove jira --yes +$$nemoclaw my-assistant policy-remove github --yes +$$nemoclaw my-assistant policy-remove jira --yes ``` - - -```bash -nemohermes my-assistant policy-remove github --yes -nemohermes my-assistant policy-remove jira --yes -``` - ## Brave Search The default Balanced policy tier includes `brave`. If you chose Restricted during onboarding or removed the preset later, add it before enabling Brave Search workflows: - ```bash -nemoclaw my-assistant policy-add brave --dry-run -nemoclaw my-assistant policy-add brave --yes +$$nemoclaw my-assistant policy-add brave --dry-run +$$nemoclaw my-assistant policy-add brave --yes ``` - - -```bash -nemohermes my-assistant policy-add brave --dry-run -nemohermes my-assistant policy-add brave --yes -``` - The Brave Search API key is still configured separately during onboarding or through the web search setup flow. @@ -396,41 +255,21 @@ Use these presets when an agent workflow installs packages or downloads model as Add only the preset required for the task: - ```bash -nemoclaw my-assistant policy-add npm --yes -nemoclaw my-assistant policy-add pypi --yes -nemoclaw my-assistant policy-add brew --yes -nemoclaw my-assistant policy-add huggingface --yes +$$nemoclaw my-assistant policy-add npm --yes +$$nemoclaw my-assistant policy-add pypi --yes +$$nemoclaw my-assistant policy-add brew --yes +$$nemoclaw my-assistant policy-add huggingface --yes ``` - - -```bash -nemohermes my-assistant policy-add npm --yes -nemohermes my-assistant policy-add pypi --yes -nemohermes my-assistant policy-add brew --yes -nemohermes my-assistant policy-add huggingface --yes -``` - Remove package access after a one-time setup task if the sandbox no longer needs it: - ```bash -nemoclaw my-assistant policy-remove npm --yes -nemoclaw my-assistant policy-remove pypi --yes -nemoclaw my-assistant policy-remove brew --yes -nemoclaw my-assistant policy-remove huggingface --yes +$$nemoclaw my-assistant policy-remove npm --yes +$$nemoclaw my-assistant policy-remove pypi --yes +$$nemoclaw my-assistant policy-remove brew --yes +$$nemoclaw my-assistant policy-remove huggingface --yes ``` - - -```bash -nemohermes my-assistant policy-remove npm --yes -nemohermes my-assistant policy-remove pypi --yes -nemohermes my-assistant policy-remove brew --yes -nemohermes my-assistant policy-remove huggingface --yes -``` - The `pypi` preset allows Python, `pip`, virtual-environment Python and `pip`, and `/usr/local/bin/uv` to reach PyPI endpoints. If `uv` is installed somewhere else in the sandbox, add a custom preset for that binary path instead of broadening the maintained preset locally. @@ -441,20 +280,11 @@ The sandbox base image includes Homebrew (Linuxbrew), so applying the `brew` pre A `/usr/local/bin/brew` wrapper puts the entry point on the sandbox `PATH` while delegating to the Linuxbrew prefix. Installed formula commands are available from the Linuxbrew bin directory in sandbox shell sessions: - ```bash -nemoclaw my-assistant policy-add brew --yes -nemoclaw my-assistant exec -- brew install -nemoclaw my-assistant exec -- bash -lc '' +$$nemoclaw my-assistant policy-add brew --yes +$$nemoclaw my-assistant exec -- brew install +$$nemoclaw my-assistant exec -- bash -lc '' ``` - - -```bash -nemohermes my-assistant policy-add brew --yes -nemohermes my-assistant exec -- brew install -nemohermes my-assistant exec -- bash -lc '' -``` - You do not need to bootstrap Homebrew, install build dependencies, or source `brew shellenv` inside the sandbox. @@ -471,8 +301,8 @@ Apply the `openclaw-pricing` preset to allow both pricing endpoints. The preset pins each host to a single read-only path so it does not widen egress beyond the pricing fetch: ```bash -nemoclaw my-assistant policy-add openclaw-pricing --dry-run -nemoclaw my-assistant policy-add openclaw-pricing --yes +$$nemoclaw my-assistant policy-add openclaw-pricing --dry-run +$$nemoclaw my-assistant policy-add openclaw-pricing --yes ``` After the next gateway restart, the WARN entries stop and `usage.cost` populates from the fetched pricing tables. @@ -490,46 +320,24 @@ Use `local-inference` when the sandbox needs access to host-side local inference Onboarding auto-suggests this preset when you choose a local provider. If you need to add it after onboarding: - -```bash -nemoclaw my-assistant policy-add local-inference --dry-run -nemoclaw my-assistant policy-add local-inference --yes -``` - - ```bash -nemohermes my-assistant policy-add local-inference --dry-run -nemohermes my-assistant policy-add local-inference --yes +$$nemoclaw my-assistant policy-add local-inference --dry-run +$$nemoclaw my-assistant policy-add local-inference --yes ``` - Then verify the sandbox status: - ```bash -nemoclaw my-assistant status +$$nemoclaw my-assistant status ``` - - -```bash -nemohermes my-assistant status -``` - ## Inspect or Replace the Live Policy Use `policy-list` for normal preset state: - ```bash -nemoclaw my-assistant policy-list +$$nemoclaw my-assistant policy-list ``` - - -```bash -nemohermes my-assistant policy-list -``` - Use OpenShell when you need the full enforced YAML: @@ -545,12 +353,7 @@ openshell policy set --policy live-policy.yaml my-assistant --wait `openshell policy set` replaces the live policy with the file you provide. It does not accept a preset file that starts with a `preset:` block, and it does not merge a single endpoint into the existing policy. - -Use `nemoclaw my-assistant policy-add` for maintained NemoClaw presets. - - -Use `nemohermes my-assistant policy-add` for maintained NemoClaw presets. - +Use `$$nemoclaw my-assistant policy-add` for maintained NemoClaw presets. ## Next Steps diff --git a/docs/reference/architecture.mdx b/docs/reference/architecture.mdx index 9d935c28f1..704d3b8c7b 100644 --- a/docs/reference/architecture.mdx +++ b/docs/reference/architecture.mdx @@ -55,7 +55,7 @@ graph LR end end - USER -->|"nemoclaw onboard
nemoclaw connect"| NCLI + USER -->|"$$nemoclaw onboard
$$nemoclaw connect"| NCLI USER -->|"Chat messages"| MSGAPI NCLI -->|"Orchestrates"| OSCLI @@ -93,7 +93,7 @@ graph TB subgraph HOST["Host machine · Linux / Apple Silicon macOS / DGX Spark / DGX Station"] direction TB - CLI["nemoclaw CLI
bin/nemoclaw.js → dist/
onboard · connect · status · logs"]:::cli + CLI["$$nemoclaw CLI
bin/nemoclaw.js → dist/
onboard · connect · status · logs"]:::cli GW["OpenShell gateway
host process by default
credential store · lifecycle · L7 proxy"]:::gateway subgraph DOCKER["Docker daemon"] @@ -119,7 +119,7 @@ Layering from top to bottom: | Layer | Runs as | Role | |---|---|---| -| Host CLI | Host process (`nemoclaw` on Node.js) | Orchestrates OpenShell via `openshell` CLI calls. | +| Host CLI | Host process (`$$nemoclaw` on Node.js) | Orchestrates OpenShell via `openshell` CLI calls. | | OpenShell gateway | Host process by default; optional Linux compatibility container when the gateway binary needs a newer host ABI | Hosts the credential store, owns sandbox lifecycle coordination, and provides the L7 proxy. | | Docker daemon | Host service | Runs the Docker-driver sandbox container and, on affected Linux hosts, the optional gateway compatibility container. | | Sandbox container | Docker container | Runs the selected compatible agent and NemoClaw integration under Landlock + seccomp + netns. | @@ -246,14 +246,14 @@ 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_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_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. | | `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. | -For normal setup and reconfiguration, prefer `nemoclaw onboard` over editing these files by hand. +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 7befd63e34..ee19af6adc 100644 --- a/docs/reference/cli-selection-guide.mdx +++ b/docs/reference/cli-selection-guide.mdx @@ -4,76 +4,76 @@ title: "Choose Between NemoClaw and OpenShell CLIs" sidebar-title: "Which CLI to Use" description: "Choose between the NemoClaw CLI and the OpenShell CLI for common sandbox operations." -description-agent: "Explains when to use `nemoclaw` versus `openshell` for NemoClaw-managed sandboxes, including lifecycle, inference, policy, monitoring, file transfer, and gateway operations." +description-agent: "Explains when to use `$$nemoclaw` versus `openshell` for NemoClaw-managed sandboxes, including lifecycle, inference, policy, monitoring, file transfer, and gateway operations." keywords: ["nemoclaw vs openshell", "which cli", "nemoclaw cli", "openshell cli", "sandbox commands"] content: type: "reference" --- NemoClaw uses two host-side CLIs. -Use `nemoclaw` for NemoClaw-managed workflows. +Use `$$nemoclaw` for NemoClaw-managed workflows. Use `openshell` when you need a lower-level OpenShell operation that NemoClaw intentionally exposes. ## Rule of Thumb -If the task changes how NemoClaw creates, rebuilds, preserves, or configures a sandbox, start with `nemoclaw`. +If the task changes how NemoClaw creates, rebuilds, preserves, or configures a sandbox, start with `$$nemoclaw`. If the task inspects or changes the live OpenShell gateway, TUI, raw policy, port forwarding, inference route, or sandbox file transfer, use `openshell`. Do not create or recreate NemoClaw-managed sandboxes directly with `openshell sandbox create` unless you intend to manage OpenShell yourself. -Run `nemoclaw onboard` afterward if you need to return to a NemoClaw-managed environment. +Run `$$nemoclaw onboard` afterward if you need to return to a NemoClaw-managed environment. -## Use `nemoclaw` For NemoClaw Workflows +## 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 OpenClaw configuration. - Install, onboard, or recreate a NemoClaw sandbox: ```bash - nemoclaw onboard - nemoclaw onboard --resume --recreate-sandbox + $$nemoclaw onboard + $$nemoclaw onboard --resume --recreate-sandbox ``` - List, connect to, check, or delete NemoClaw-managed sandboxes: ```bash - nemoclaw list - nemoclaw my-assistant connect - nemoclaw my-assistant status - nemoclaw my-assistant logs --follow - nemoclaw my-assistant destroy + $$nemoclaw list + $$nemoclaw my-assistant connect + $$nemoclaw my-assistant status + $$nemoclaw my-assistant logs --follow + $$nemoclaw my-assistant destroy ``` - Rebuild or upgrade while preserving workspace state: ```bash - nemoclaw my-assistant rebuild - nemoclaw upgrade-sandboxes --check + $$nemoclaw my-assistant rebuild + $$nemoclaw upgrade-sandboxes --check ``` - Snapshot, restore, or mount sandbox state: ```bash - nemoclaw my-assistant snapshot create --name before-change - nemoclaw my-assistant snapshot restore before-change - nemoclaw my-assistant share mount + $$nemoclaw my-assistant snapshot create --name before-change + $$nemoclaw my-assistant snapshot restore before-change + $$nemoclaw my-assistant share mount ``` - Add or remove NemoClaw policy presets: ```bash - nemoclaw my-assistant policy-add pypi --yes - nemoclaw my-assistant policy-list - nemoclaw my-assistant policy-remove pypi --yes + $$nemoclaw my-assistant policy-add pypi --yes + $$nemoclaw my-assistant policy-list + $$nemoclaw my-assistant policy-remove pypi --yes ``` - Manage NemoClaw messaging channels, 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 + $$nemoclaw my-assistant channels add slack + $$nemoclaw credentials list + $$nemoclaw credentials reset nvidia-prod + $$nemoclaw debug --sandbox my-assistant + $$nemoclaw gc --dry-run ``` ## Use `openshell` For OpenShell Operations @@ -120,7 +120,7 @@ Use `openshell` when the docs explicitly call for a live OpenShell gateway opera `openshell policy update` merges specific endpoint and rule changes into the live sandbox policy. `openshell policy set` replaces the live policy with the file you provide. -For normal NemoClaw network access changes, prefer `nemoclaw policy-add` so NemoClaw preserves presets and records the change for rebuilds. +For normal NemoClaw network access changes, prefer `$$nemoclaw policy-add` so NemoClaw preserves presets and records the change for rebuilds. ## Common Decisions @@ -128,7 +128,7 @@ This section covers common decisions when using the NemoClaw CLI and the OpenShe ### First Setup or Full Recreate -Use `nemoclaw onboard`. +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. Avoid running `openshell gateway start --recreate` or `openshell sandbox create` directly for NemoClaw-managed sandboxes. @@ -136,17 +136,17 @@ Those commands do not update NemoClaw's registry, session metadata, workspace-pr ### Connect to the Sandbox -Use `nemoclaw connect` for an interactive NemoClaw sandbox shell. +Use `$$nemoclaw connect` for an interactive NemoClaw sandbox shell. It waits for readiness, handles stale SSH host keys after gateway restarts, and prints agent-specific hints. Use `openshell sandbox connect ` only when you intentionally want the raw OpenShell connection path. -For a one-off command in a NemoClaw-managed sandbox, use `nemoclaw exec` instead of opening an interactive shell. +For a one-off command in a NemoClaw-managed sandbox, use `$$nemoclaw exec` instead of opening an interactive shell. It resolves the sandbox by its NemoClaw registry name and runs through the standard NemoClaw CLI surface. The command executes as the sandbox user with `HOME=/sandbox` inside the provisioned sandbox, where the agent configuration, inference routing, and policy state are already in place. ```bash -nemoclaw my-assistant exec -- cat /tmp/gateway.log +$$nemoclaw my-assistant exec -- cat /tmp/gateway.log ``` Use `openshell sandbox exec` for the raw OpenShell execution path, for example when addressing a sandbox by its gateway name or intentionally bypassing the NemoClaw CLI and registry. @@ -157,7 +157,7 @@ openshell sandbox exec -n my-assistant -- cat /tmp/gateway.log ### Check Health or Logs -Use `nemoclaw status` and `nemoclaw logs` first. +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. Use `openshell sandbox list`, `openshell sandbox get`, `openshell logs -n 20`, or `openshell doctor check` when debugging lower-level OpenShell behavior. @@ -175,8 +175,8 @@ Approved endpoints are session-scoped unless you also add them to the policy thr 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 +$$nemoclaw inference get +$$nemoclaw inference set --provider nvidia-prod --model nvidia/nemotron-3-super-120b-a12b ``` For Hermes sandboxes, use the alias; it updates the route and `/sandbox/.hermes/config.yaml` without a rebuild or restart: @@ -188,18 +188,18 @@ nemohermes inference set --provider hermes-provider --model openai/gpt-5.4-mini For a build-time agent setting change, rerun onboarding so the sandbox configuration is recreated consistently: ```bash -nemoclaw onboard --resume --recreate-sandbox +$$nemoclaw onboard --resume --recreate-sandbox ``` Verify either path with: ```bash -nemoclaw status +$$nemoclaw status ``` ### Update Network Policy -Use `nemoclaw policy-add` or `policy-remove` for NemoClaw presets and custom preset files. +Use `$$nemoclaw policy-add` or `policy-remove` for NemoClaw presets and custom preset files. NemoClaw merges the new policy with the live policy and reapplies presets during rebuilds. Use `openshell policy update` for precise live endpoint or REST rule changes. @@ -207,7 +207,7 @@ Use `openshell policy get --full` and `openshell policy set` only when you need ### Move Workspace Files -Use `nemoclaw snapshot create`, `snapshot restore`, or `share mount` for normal workspace preservation and editing. +Use `$$nemoclaw snapshot create`, `snapshot restore`, or `share mount` for normal workspace preservation and editing. Use `openshell sandbox upload` and `openshell sandbox download` for manual file copies when you need exact control over source and destination paths. diff --git a/docs/reference/commands-nemohermes.mdx b/docs/reference/commands-nemohermes.mdx index 5edaae4958..7cbc697cc4 100644 --- a/docs/reference/commands-nemohermes.mdx +++ b/docs/reference/commands-nemohermes.mdx @@ -1665,7 +1665,7 @@ These flags change defaults for commands that manage existing sandboxes. These variables seed defaults for `nemohermes deploy` and `nemohermes onboard --remote`, which provision a sandbox on a Brev instance. Each has a flag equivalent on `deploy`; the env var lets non-interactive runs skip the prompt. -For narrative how-to coverage of `NEMOCLAW_BREV_PROVIDER` and `NEMOCLAW_GPU`, see [Deploy to Remote GPU](../deployment/deploy-to-remote-gpu.md). +For narrative how-to coverage of `NEMOCLAW_BREV_PROVIDER` and `NEMOCLAW_GPU`, see [Deploy to Remote GPU](../deployment/deploy-to-remote-gpu.mdx). | Variable | Default | Effect | |----------|---------|--------| diff --git a/docs/reference/commands.mdx b/docs/reference/commands.mdx index a1d5cbe956..55e57147c1 100644 --- a/docs/reference/commands.mdx +++ b/docs/reference/commands.mdx @@ -4,7 +4,7 @@ title: "NemoClaw CLI Commands Reference" sidebar-title: "Commands" description: "Full CLI reference for standalone NemoClaw commands and agent-specific in-sandbox commands." -description-agent: "Includes the full CLI reference for standalone NemoClaw commands and agent-specific in-sandbox commands. Use when looking up a specific `nemoclaw`, `nemohermes`, or `/nemoclaw` subcommand, flag, argument, or exit code." +description-agent: "Includes the full CLI reference for standalone NemoClaw commands and agent-specific in-sandbox commands. Use when looking up a specific `$$nemoclaw`, `nemohermes`, or `/nemoclaw` subcommand, flag, argument, or exit code." keywords: ["nemoclaw cli commands", "nemoclaw command reference"] content: type: "reference" @@ -13,9 +13,9 @@ import { AgentOnly } from "../_components/AgentGuide"; -The `nemoclaw` CLI is the primary interface for managing NemoClaw sandboxes. +The `$$nemoclaw` CLI is the primary interface for managing NemoClaw sandboxes. It is installed automatically by the installer (`curl -fsSL https://www.nvidia.com/nemoclaw.sh | bash`). -For guidance on when to use `nemoclaw` versus the underlying `openshell` CLI, see [CLI Selection Guide](cli-selection-guide). +For guidance on when to use `$$nemoclaw` versus the underlying `openshell` CLI, see [CLI Selection Guide](cli-selection-guide). @@ -32,8 +32,8 @@ For guidance on choosing between the agent CLIs and the underlying `openshell` C -Use `nemoclaw` for the OpenClaw variant. -OpenClaw is the default agent for `nemoclaw onboard` unless you pass `--agent hermes` or set `NEMOCLAW_AGENT=hermes`. +Use `$$nemoclaw` for the OpenClaw variant. +OpenClaw is the default agent for `$$nemoclaw onboard` unless you pass `--agent hermes` or set `NEMOCLAW_AGENT=hermes`. OpenClaw-specific sections below describe the `/nemoclaw` slash command, the OpenClaw dashboard URL, the OpenClaw gateway token, and OpenClaw config paths under `/sandbox/.openclaw`. @@ -77,42 +77,42 @@ The in-sandbox Hermes integration installs the NemoClaw Hermes plugin, which exp The CLI handles host-side operations that run outside the selected agent runtime. -### `nemoclaw help`, `nemoclaw --help`, `nemoclaw -h` +### `$$nemoclaw help`, `$$nemoclaw --help`, `$$nemoclaw -h` Show the top-level usage summary and command groups. -Running `nemoclaw` with no arguments shows the same help output. +Running `$$nemoclaw` with no arguments shows the same help output. ```bash -nemoclaw help +$$nemoclaw help ``` -### `nemoclaw --version`, `nemoclaw -v` +### `$$nemoclaw --version`, `$$nemoclaw -v` Print the installed NemoClaw CLI version. ```bash -nemoclaw --version +$$nemoclaw --version ``` -### `nemoclaw resources` +### `$$nemoclaw 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 -nemoclaw resources [--json] +$$nemoclaw resources [--json] ``` If the gateway is not running, Kubernetes allocatable fields are omitted and host CPU/RAM totals are still shown. -### `nemoclaw onboard` +### `$$nemoclaw 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 -nemoclaw onboard [--non-interactive] [--resume | --fresh] [--recreate-sandbox] [--gpu | --no-gpu] [--from ] [--name ] [--sandbox-gpu | --no-sandbox-gpu] [--sandbox-gpu-device ] [--agent ] [--control-ui-port ] [--yes | -y] [--no-ollama-autostart] [--yes-i-accept-third-party-software] +$$nemoclaw onboard [--non-interactive] [--resume | --fresh] [--recreate-sandbox] [--gpu | --no-gpu] [--from ] [--name ] [--sandbox-gpu | --no-sandbox-gpu] [--sandbox-gpu-device ] [--agent ] [--control-ui-port ] [--yes | -y] [--no-ollama-autostart] [--yes-i-accept-third-party-software] ``` @@ -134,15 +134,15 @@ If the recorded session conflicts with flags you pass on the recovery run, NemoC 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. -The installer also accepts `--fresh` and forwards it to `nemoclaw onboard`, which skips automatic resume detection. +The installer also accepts `--fresh` and forwards it to `$$nemoclaw onboard`, which skips automatic resume detection. `--resume` and `--fresh` are mutually exclusive. -For NemoClaw-managed environments, use `nemoclaw 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 `nemoclaw onboard`. +For NemoClaw-managed environments, use `$$nemoclaw 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 `$$nemoclaw onboard`. -Use `--fresh` to ignore any saved onboarding session and restart the wizard from scratch. This is useful after an interrupted `nemoclaw onboard` run when you want to discard saved state instead of continuing it with `--resume`. +Use `--fresh` to ignore any saved onboarding session and restart the wizard from scratch. This is useful after an interrupted `$$nemoclaw 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`: @@ -153,13 +153,13 @@ 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 back up registered sandbox state, retire the old gateway, install the current supported OpenShell release, and restore state during onboarding. -The automatic path is disabled if the existing `nemoclaw` CLI does not advertise `backup-all`; preserve sandbox state manually before retiring the old gateway in that case. -To perform those steps manually, run `nemoclaw backup-all`, retire the old gateway registration with `openshell gateway remove nemoclaw || openshell gateway destroy -g nemoclaw || openshell gateway destroy` (both verbs are tried so the right one runs on either OpenShell release), stop any remaining privileged host gateway with `sudo pkill -f openshell-gateway`, then rerun the installer as `curl -fsSL https://www.nvidia.com/nemoclaw.sh | NEMOCLAW_OPENSHELL_UPGRADE_PREPARED=1 bash`. +The automatic path is disabled if the existing `$$nemoclaw` CLI does not advertise `backup-all`; preserve sandbox state manually before retiring the old gateway in that case. +To perform those steps manually, run `$$nemoclaw backup-all`, retire the old gateway registration with `openshell gateway remove nemoclaw || openshell gateway destroy -g nemoclaw || openshell gateway destroy` (both verbs are tried so the right one runs on either OpenShell release), stop any remaining privileged host gateway with `sudo pkill -f openshell-gateway`, then rerun the installer as `curl -fsSL https://www.nvidia.com/nemoclaw.sh | NEMOCLAW_OPENSHELL_UPGRADE_PREPARED=1 bash`. 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. See [Credential Storage](../security/credential-storage) for details on inspection, rotation, and migration from earlier releases. -The legacy `nemoclaw setup` command is deprecated; use `nemoclaw onboard` instead. +The legacy `$$nemoclaw setup` command is deprecated; use `$$nemoclaw 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. @@ -179,12 +179,12 @@ Later re-onboard runs seed from that finalized selection, so presets you intenti In non-interactive mode, set the tier with `NEMOCLAW_POLICY_TIER` (default: `balanced`): ```bash -NEMOCLAW_POLICY_TIER=restricted nemoclaw onboard --non-interactive --yes-i-accept-third-party-software +NEMOCLAW_POLICY_TIER=restricted $$nemoclaw onboard --non-interactive --yes-i-accept-third-party-software ``` `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 [`nemoclaw policy-add`](#nemoclaw-name-policy-add) across re-onboards. +Onboarding applies tier defaults and preserves any presets you previously added with [`$$nemoclaw policy-add`](#$$nemoclaw-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. @@ -206,13 +206,13 @@ Treat Brave Search as an explicit opt-in and use a dedicated low-privilege Brave For non-interactive onboarding, you must explicitly accept the third-party software notice: ```bash -nemoclaw onboard --non-interactive --yes-i-accept-third-party-software +$$nemoclaw onboard --non-interactive --yes-i-accept-third-party-software ``` or: ```bash -NEMOCLAW_ACCEPT_THIRD_PARTY_SOFTWARE=1 nemoclaw onboard --non-interactive +NEMOCLAW_ACCEPT_THIRD_PARTY_SOFTWARE=1 $$nemoclaw onboard --non-interactive ``` For scripted installer runs, pass explicit acceptance to the `bash` side of the installer pipe: @@ -227,12 +227,12 @@ To enable Brave Search in non-interactive mode, set: ```bash BRAVE_API_KEY=... \ - nemoclaw onboard --non-interactive + $$nemoclaw onboard --non-interactive ``` `BRAVE_API_KEY` enables Brave Search in non-interactive mode and also enables `web_fetch`. If Brave Search key validation fails in non-interactive mode, onboarding prints a warning, skips web search setup, and continues with the rest of the sandbox setup. -After fixing the key, re-enable web search with `nemoclaw config web-search`. +After fixing the key, re-enable web search with `$$nemoclaw config web-search`. 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. @@ -269,7 +269,7 @@ Set `NEMOCLAW_RECREATE_SANDBOX=1` to force recreation even when no drift is dete 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 `nemoclaw rebuild --force`. +The behaviour matches `$$nemoclaw 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. @@ -296,7 +296,7 @@ When NemoClaw finds an existing gateway to reuse, it probes the host gateway HTT 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 `nemoclaw onboard` is safe to run just to check preflight output. +This means pressing `Ctrl+C` between preflight and step `[2/8]` leaves the running gateway and existing sandbox containers untouched, so `$$nemoclaw 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. @@ -315,7 +315,7 @@ If the staged context is larger than 100 MB, onboarding prints a warning before 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. ```bash -nemoclaw onboard --from path/to/Dockerfile +$$nemoclaw onboard --from path/to/Dockerfile ``` The Dockerfile path must exist. @@ -336,7 +336,7 @@ In non-interactive mode, the path can also be supplied via the `NEMOCLAW_FROM_DO 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 nemoclaw onboard +NEMOCLAW_NON_INTERACTIVE=1 NEMOCLAW_FROM_DOCKERFILE=path/to/Dockerfile NEMOCLAW_SANDBOX_NAME=my-build $$nemoclaw 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. @@ -348,7 +348,7 @@ The same name format and reserved-name rules that the wizard enforces apply here Names that match a NemoClaw CLI command (`status`, `list`, `debug`, etc.) are rejected up front. ```bash -nemoclaw onboard --non-interactive --name my-build --from path/to/Dockerfile +$$nemoclaw onboard --non-interactive --name my-build --from path/to/Dockerfile ``` The flag wins over `NEMOCLAW_SANDBOX_NAME`. @@ -356,18 +356,18 @@ When prompting is possible, `NEMOCLAW_SANDBOX_NAME` fills the interactive defaul 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. -### `nemoclaw onboard --from` +### `$$nemoclaw onboard --from` Use a custom Dockerfile for the sandbox image. -This variant of `nemoclaw onboard` accepts a `--from ` argument to build the sandbox from a user-supplied Dockerfile instead of the default NemoClaw image. +This variant of `$$nemoclaw onboard` accepts a `--from ` argument to build the sandbox from a user-supplied Dockerfile instead of the default NemoClaw image. ```bash -nemoclaw onboard --from ./Dockerfile.custom +$$nemoclaw onboard --from ./Dockerfile.custom ``` ### GPU passthrough -When `nemoclaw onboard` detects an NVIDIA GPU on the host, it enables OpenShell GPU passthrough at both the gateway and sandbox level by default. +When `$$nemoclaw 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. @@ -390,7 +390,7 @@ If other sandboxes depend on the gateway or Docker state is unclear, onboarding To add GPU to an existing sandbox, rerun with `--recreate-sandbox`. Set `NEMOCLAW_DOCKER_GPU_PATCH=0` only when you need to bypass the Linux Docker-driver compatibility patch during troubleshooting. -### `nemoclaw list` +### `$$nemoclaw 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. @@ -398,15 +398,15 @@ Sandboxes with an active SSH session are marked with a `●` indicator so you ca When a sandbox has a recorded dashboard port, the output includes its local dashboard URL. ```bash -nemoclaw list [--json] -nemoclaw list --json +$$nemoclaw list [--json] +$$nemoclaw list --json ``` -### `nemoclaw deploy` +### `$$nemoclaw deploy` -The `nemoclaw deploy` command is deprecated. -Prefer provisioning the remote host separately, then running the standard NemoClaw installer and `nemoclaw onboard` on that host. +The `$$nemoclaw deploy` command is deprecated. +Prefer provisioning the remote host separately, then running the standard NemoClaw installer and `$$nemoclaw onboard` on that host. Deploy NemoClaw to a remote GPU instance through [Brev](https://brev.nvidia.com). @@ -415,10 +415,10 @@ 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 -nemoclaw deploy +$$nemoclaw deploy ``` -### `nemoclaw connect` +### `$$nemoclaw 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. @@ -427,7 +427,7 @@ Control the wait budget with `NEMOCLAW_CONNECT_TIMEOUT` (integer seconds, defaul 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 `nemoclaw rebuild` hint. +If the sandbox is running an outdated agent version, a non-blocking warning prints before connecting with a `$$nemoclaw 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 `NEMOCLAW_VLLM_MODEL` if you exported it for the managed-vLLM install path. @@ -435,21 +435,21 @@ An unknown slug or a gated model (for example `deepseek-r1-distill-70b`) with no Unset the variable, or supply the missing token, before retrying. When the live OpenShell gateway inference route differs from the route recorded in the NemoClaw registry, `connect` prints an explicit warning and realigns the shared gateway to the recorded route. -Use `nemoclaw inference set --provider --model ` to make an intentional route change. +Use `$$nemoclaw inference set --provider --model ` to make an intentional 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 `nemoclaw onboard` after a reboot in this case. +You no longer need to re-run `$$nemoclaw onboard` after a reboot in this case. ```bash -nemoclaw my-assistant connect [--probe-only] +$$nemoclaw 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. -### `nemoclaw exec` +### `$$nemoclaw 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`. @@ -460,8 +460,8 @@ This is the supported substitute for `docker exec` on the sandbox container; raw OpenClaw config resolves under `/sandbox/.openclaw`. ```bash -nemoclaw my-assistant exec -- openclaw agent -m "What is 2+2?" -nemoclaw my-assistant exec --workdir /sandbox/workspace -- ls -la +$$nemoclaw my-assistant exec -- openclaw agent -m "What is 2+2?" +$$nemoclaw my-assistant exec --workdir /sandbox/workspace -- ls -la ``` @@ -485,20 +485,20 @@ The exit code is the remote command's exit code. | `--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) | -### `nemoclaw recover` +### `$$nemoclaw recover` Restart the in-sandbox gateway and re-establish the host-side dashboard port-forward without opening an SSH session. -Use this after a sandbox pod restart, a sandbox crash, or whenever `nemoclaw status` reports the gateway is not running but the sandbox is alive. +Use this after a sandbox pod restart, a sandbox crash, or whenever `$$nemoclaw status` reports the gateway is not running but the sandbox is alive. `recover` runs the same recovery the `connect` command performs as a side effect, but without dropping into a shell, so it is safe to call from scripts and automation. It is idempotent. If the gateway is already running, the command exits zero with a probe message and makes no changes. ```bash -nemoclaw my-assistant recover +$$nemoclaw my-assistant recover ``` -### `nemoclaw status` +### `$$nemoclaw status` Show sandbox status, health, and inference configuration. @@ -509,12 +509,12 @@ The JSON output includes at least `schemaVersion`, `name`, `found`, `model`, `pr `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. 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`), or `failureLayer` is non-null. -The alias form `nemoclaw status --json` requires the sandbox to be registered locally; the canonical form `nemoclaw 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. +The alias form `$$nemoclaw status --json` requires the sandbox to be registered locally; the canonical form `$$nemoclaw 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 -nemoclaw my-assistant status -nemoclaw my-assistant status --json -nemoclaw sandbox status my-assistant --json +$$nemoclaw my-assistant status +$$nemoclaw my-assistant status --json +$$nemoclaw sandbox status my-assistant --json ``` The command probes every inference provider and reports one of three states on the `Inference` line: @@ -549,13 +549,13 @@ The sandbox list in the status output includes the dashboard port suffix for san The Policy section displays the live enforced policy (fetched via `openshell policy get --full`), which reflects presets added or removed after sandbox creation. When OpenShell reports an active policy version, the displayed YAML `version` line uses that active version instead of the static schema version. -If the sandbox is running an outdated agent version, the output includes an `Update` line with the available version and a `nemoclaw rebuild` hint. +If the sandbox is running an outdated agent version, the output includes an `Update` line with the available version and a `$$nemoclaw rebuild` hint. When other sandboxes have the same messaging channel enabled (Telegram, Discord, or Slack) with the same bot token, the output includes a cross-sandbox overlap warning so you can resolve the conflict before messages start dropping. The command also tails `/tmp/gateway.log` inside the default sandbox and flags Telegram `409 Conflict` errors that indicate a duplicate consumer for the bot token. ```bash -nemoclaw my-assistant status +$$nemoclaw my-assistant status ``` @@ -567,16 +567,16 @@ The NemoClaw runtime build target is declared by `OPENCLAW_VERSION` in the NemoC The `min_openclaw_version` field in `nemoclaw-blueprint/blueprint.yaml` remains the compatibility floor for direct blueprint consumers, so it can be lower than the Dockerfile target. Existing sandboxes do not auto-upgrade when a newer NemoClaw release ships a newer pin — you upgrade by rebuilding the sandbox. -`nemoclaw status` prints the running OpenClaw version on the `Agent` line: +`$$nemoclaw status` prints the running OpenClaw version on the `Agent` line: ```console -$ nemoclaw my-assistant status +$ $$nemoclaw my-assistant status ... Agent: OpenClaw v2026.5.22 ... ``` -If the sandbox is running an OpenClaw older than the version this NemoClaw release pins, `status` and `connect` add an `Update` line pointing at `nemoclaw rebuild` to pick up the newer version. +If the sandbox is running an OpenClaw older than the version this NemoClaw release pins, `status` and `connect` add an `Update` line pointing at `$$nemoclaw rebuild` to pick up the newer version. The rebuild reuses the existing sandbox name and persisted credentials, so messaging tokens and provider keys carry over. @@ -602,7 +602,7 @@ The rebuild reuses the existing sandbox name and persisted credentials, so messa -### `nemoclaw doctor` +### `$$nemoclaw doctor` Run a focused health check for one sandbox and the host services it depends on. The command checks the local CLI build, Docker daemon, OpenShell CLI, NemoClaw gateway container, gateway port mapping, live sandbox state, inference route, provider reachability, messaging channel conflicts, Ollama reachability, and the cloudflared tunnel state. @@ -612,17 +612,17 @@ Failed checks exit non-zero so scripts can use `doctor` as a readiness gate. Use `--json` for machine-readable output. ```bash -nemoclaw my-assistant doctor [--json] +$$nemoclaw my-assistant doctor [--json] ``` -### `nemoclaw exec` +### `$$nemoclaw exec` Run a command non-interactively inside a running sandbox through the OpenShell exec endpoint. The command runs as the sandbox user with `HOME=/sandbox` and exits with the remote command's exit code. Use `--` to separate `exec` options from the command you want to run inside the sandbox. ```bash -nemoclaw my-assistant exec [--workdir ] [--tty|--no-tty] [--timeout ] -- [args...] +$$nemoclaw my-assistant exec [--workdir ] [--tty|--no-tty] [--timeout ] -- [args...] ``` | Flag | Description | @@ -631,7 +631,7 @@ nemoclaw my-assistant exec [--workdir ] [--tty|--no-tty] [--timeout ] -- | `--tty`, `--no-tty` | Allocate or disable a pseudo-terminal; defaults to auto-detection | | `--timeout ` | Timeout in seconds. Use `0` for no timeout | -### `nemoclaw logs` +### `$$nemoclaw logs` View sandbox logs. Use `--follow` to stream output in real time. @@ -642,10 +642,10 @@ If one log source is unavailable, NemoClaw prints a warning and keeps reading th NemoClaw's `--tail ` flag is a line-count flag; the lower-level `openshell logs --tail` flag means follow live output, so use `openshell logs -n ` when running OpenShell directly for a fixed line count. ```bash -nemoclaw my-assistant logs [--follow] [--tail |-n ] [--since ] +$$nemoclaw my-assistant logs [--follow] [--tail |-n ] [--since ] ``` -### `nemoclaw dashboard-url` +### `$$nemoclaw dashboard-url` @@ -653,15 +653,15 @@ Print the authenticated OpenClaw dashboard URL for a running sandbox. Use this when you are on a remote machine, using an SSH or reverse tunnel, or need a complete URL for a browser session. ```bash -nemoclaw my-assistant dashboard-url -nemoclaw my-assistant dashboard-url --quiet +$$nemoclaw my-assistant dashboard-url +$$nemoclaw my-assistant dashboard-url --quiet ``` The default output includes a label and a warning. Pass `--quiet` or `-q` to print only the URL to stdout so scripts can capture it: ```bash -URL=$(nemoclaw my-assistant dashboard-url --quiet) +URL=$($$nemoclaw my-assistant dashboard-url --quiet) ``` @@ -679,7 +679,7 @@ If you enabled `NEMOCLAW_HERMES_DASHBOARD=1`, use the optional Hermes dashboard -### `nemoclaw gateway-token` +### `$$nemoclaw gateway-token` @@ -689,7 +689,7 @@ Use `dashboard-url` for browser access; use `gateway-token` only when automation Pipe it into automation or capture it into an environment variable: ```bash -TOKEN=$(nemoclaw my-assistant gateway-token --quiet) +TOKEN=$($$nemoclaw my-assistant gateway-token --quiet) export OPENCLAW_GATEWAY_TOKEN="$TOKEN" ``` @@ -711,7 +711,7 @@ If you need the endpoint for an OpenAI-compatible client, use `nemohermes my-ass -### `nemoclaw destroy` +### `$$nemoclaw destroy` Stop the NIM container, remove the host-side Docker image built during onboard, and delete the sandbox. This removes the sandbox from the registry. @@ -720,8 +720,8 @@ For Ollama-backed sandboxes, `destroy` also asks Ollama to unload currently load This command permanently deletes the sandbox **and its persistent volume**. All [workspace files](../manage-sandboxes/workspace-files) (SOUL.md, USER.md, IDENTITY.md, AGENTS.md, MEMORY.md, and daily memory notes) are lost. -Back up your workspace first with `nemoclaw snapshot create` or see [Backup and Restore](../manage-sandboxes/backup-restore). -If you want to upgrade the sandbox while preserving state, use `nemoclaw rebuild` instead. +Back up your workspace first with `$$nemoclaw snapshot create` or see [Backup and Restore](../manage-sandboxes/backup-restore). +If you want to upgrade the sandbox while preserving state, use `$$nemoclaw rebuild` instead. If another terminal has an active SSH session to the sandbox, `destroy` prints an active-session warning and requires a second confirmation before it proceeds. @@ -730,23 +730,23 @@ By default, `destroy` preserves the shared NemoClaw gateway. Pass `--cleanup-gateway` to remove the shared gateway when destroying the last sandbox, or `--no-cleanup-gateway` to force preservation when environment defaults request cleanup. ```bash -nemoclaw my-assistant destroy [--yes|-y|--force] [--cleanup-gateway|--no-cleanup-gateway] +$$nemoclaw my-assistant destroy [--yes|-y|--force] [--cleanup-gateway|--no-cleanup-gateway] ``` -### `nemoclaw policy-add` +### `$$nemoclaw policy-add` Add a policy preset to a sandbox. Presets extend the baseline network policy with additional endpoints. Before applying, the command shows which endpoints the preset would open and prompts for confirmation. ```bash -nemoclaw my-assistant policy-add +$$nemoclaw my-assistant policy-add ``` To apply a specific preset without the interactive picker, pass its name as a positional argument: ```bash -nemoclaw my-assistant policy-add pypi --yes +$$nemoclaw my-assistant policy-add pypi --yes ``` The positional form is required in scripted workflows. @@ -765,47 +765,47 @@ Custom preset files are tracked with the sandbox that applied them. Use `--dry-run` to audit a preset before applying it: ```bash -nemoclaw my-assistant policy-add --dry-run +$$nemoclaw my-assistant policy-add --dry-run ``` Apply a custom preset file when you need to grant access to an endpoint that is not covered by a built-in preset: ```bash -nemoclaw my-assistant policy-add --from-file ./presets/my-internal-api.yaml +$$nemoclaw my-assistant policy-add --from-file ./presets/my-internal-api.yaml ``` For batch workflows, apply all preset files from a directory: ```bash -nemoclaw my-assistant policy-add --from-dir ./presets/ --yes +$$nemoclaw my-assistant policy-add --from-dir ./presets/ --yes ``` Review every host in custom preset files before applying them. Custom presets bypass the built-in preset review process and can widen sandbox egress. -### `nemoclaw policy-list` +### `$$nemoclaw policy-list` List available policy presets and show which ones are applied to the sandbox. The command cross-references the local registry against the live gateway state (via `openshell policy get`), so it flags presets that are applied in one place but not the other. This catches desync caused by external edits to the gateway policy or stale registry entries after a manual rollback. ```bash -nemoclaw my-assistant policy-list +$$nemoclaw my-assistant policy-list ``` -### `nemoclaw policy-remove` +### `$$nemoclaw policy-remove` Remove a previously applied policy preset from a sandbox. The command lists only the presets currently applied, prompts you to select one, shows the endpoints that would be removed, and asks for confirmation before narrowing egress. ```bash -nemoclaw my-assistant policy-remove +$$nemoclaw my-assistant policy-remove ``` To remove a specific preset non-interactively, pass its name as a positional argument: ```bash -nemoclaw my-assistant policy-remove pypi --yes +$$nemoclaw my-assistant policy-remove pypi --yes ``` Set `NEMOCLAW_NON_INTERACTIVE=1` as an alternative to `--yes`. @@ -818,7 +818,7 @@ If the preset is unknown or not currently applied, the command exits non-zero wi Unchecking a preset in the onboard TUI checkbox also removes it from the sandbox. -### `nemoclaw hosts-add` +### `$$nemoclaw hosts-add` Add a host alias to the sandbox pod template. Use this when a sandbox needs a stable LAN-only name, such as a local SearXNG or internal model endpoint, without dropping to `docker exec` and `kubectl patch`. @@ -826,7 +826,7 @@ Host alias commands use the legacy Kubernetes gateway `Sandbox` resource path. They are not supported on Docker-driver or VM-driver sandboxes because those drivers do not run the gateway cluster container that owns this resource. ```bash -nemoclaw my-assistant hosts-add searxng.local 192.168.1.105 +$$nemoclaw my-assistant hosts-add searxng.local 192.168.1.105 ``` The command validates the hostname and IP address, rejects duplicate hostnames, and patches `spec.podTemplate.spec.hostAliases` on the sandbox resource. @@ -835,37 +835,37 @@ The command validates the hostname and IP address, rejects duplicate hostnames, |------|-------------| | `--dry-run` | Print the JSON patch for the resulting `hostAliases` list without applying it | -### `nemoclaw hosts-list` +### `$$nemoclaw hosts-list` List host aliases configured on the sandbox resource. ```bash -nemoclaw my-assistant hosts-list +$$nemoclaw my-assistant hosts-list ``` -### `nemoclaw hosts-remove` +### `$$nemoclaw hosts-remove` Remove a hostname from the sandbox `hostAliases` list. ```bash -nemoclaw my-assistant hosts-remove searxng.local +$$nemoclaw my-assistant hosts-remove searxng.local ``` | Flag | Description | |------|-------------| | `--dry-run` | Print the JSON patch for the resulting `hostAliases` list without applying it | -### `nemoclaw channels list` +### `$$nemoclaw channels list` List the messaging channels NemoClaw knows about (`telegram`, `discord`, `slack`, `wechat`, `whatsapp`) with a short description. The command is a static reference; it does not consult credentials or the running sandbox. WeChat and WhatsApp are experimental. ```bash -nemoclaw my-assistant channels list +$$nemoclaw my-assistant channels list ``` -### `nemoclaw channels add ` +### `$$nemoclaw channels add ` Register a messaging channel with the sandbox and rebuild so the image picks up the new channel. Channels fall into three login modes: @@ -888,11 +888,11 @@ A missing or malformed preset YAML (no `network_policies:` section) aborts `chan With the preset file in place, NemoClaw applies it to the sandbox before the rebuild so the bridge has egress to its upstream API. When the apply step itself fails after the registry write on a fresh add, NemoClaw attempts to roll back the bridge providers, the `messagingChannels` entry, and any staged environment credentials, then exits without prompting for a rebuild; if any gateway-side step (provider detach or delete) fails the rollback continues and prints a `Rollback could not fully clean ` warning so the operator can clean up manually. When the same failure happens on a re-add of an already-enabled channel, NemoClaw restores the prior `messagingChannels` entry, restores staged environment credentials when available, restores registry credential hashes, and attempts to re-upsert the prior bridge providers, but flags `gateway-providers` as residual because the in-flight upsert may have left the gateway with the new token; verify the gateway bridge before relying on the channel. -Restore the preset YAML and re-run `nemoclaw channels add `. +Restore the preset YAML and re-run `$$nemoclaw channels add `. For Telegram, Discord, and Slack, a rebuild triggered by `channels add` also verifies that the selected bridge starts and reports credential, startup, or plugin discovery warnings. ```bash -nemoclaw my-assistant channels add telegram +$$nemoclaw my-assistant channels add telegram ``` | Flag | Description | @@ -901,10 +901,10 @@ nemoclaw my-assistant channels add telegram Slack requires both `SLACK_BOT_TOKEN` (bot user OAuth) and `SLACK_APP_TOKEN` (app-level Socket Mode token); the command prompts for each in turn. Optional Slack allowlists come from `SLACK_ALLOWED_USERS` and `SLACK_ALLOWED_CHANNELS` at rebuild time. -When `NEMOCLAW_NON_INTERACTIVE=1` is set, any missing token fails fast and no rebuild prompt is shown — instead, the change is queued and you are told to run `nemoclaw rebuild` manually. +When `NEMOCLAW_NON_INTERACTIVE=1` is set, any missing token fails fast and no rebuild prompt is shown — instead, the change is queued and you are told to run `$$nemoclaw rebuild` manually. If you omit the required `` argument, the CLI prints the `channels add ` usage with the supported channel list instead of falling back to top-level help. -### `nemoclaw channels remove ` +### `$$nemoclaw channels remove ` Clear the stored credentials for a messaging channel and rebuild the sandbox so the image drops the channel. Running `remove` for a channel that was never configured is a no-op against the credentials file and still triggers the rebuild prompt. @@ -920,26 +920,26 @@ For QR-paired channels (today: WhatsApp), NemoClaw destructively clears the in-s The cleanup tries `openshell sandbox exec` first and falls back to SSH if the exec wrapper does not return the success sentinel. If both transports fail (the sandbox is stopped, the gateway is down, or SSH cannot reach it) the command refuses to proceed to the rebuild and asks you to start the sandbox and re-run, so a half-removed state cannot leave stale Baileys auth files behind for the next rebuild to restore. ```bash -nemoclaw my-assistant channels remove telegram +$$nemoclaw my-assistant channels remove telegram ``` | Flag | Description | |------|-------------| | `--dry-run` | Report the channel that would be removed without clearing credentials or rebuilding | -As with `channels add`, `NEMOCLAW_NON_INTERACTIVE=1` skips the rebuild prompt and queues the change for a manual `nemoclaw rebuild`. +As with `channels add`, `NEMOCLAW_NON_INTERACTIVE=1` skips the rebuild prompt and queues the change for a manual `$$nemoclaw rebuild`. If you omit the required `` argument, the CLI prints the `channels remove ` usage with the supported channel list. Host-side removal is the supported path because agent channel config is baked into the container image at build time (`/sandbox/.openclaw/openclaw.json` for OpenClaw and `/sandbox/.hermes/.env` for Hermes); agent-specific channel removals inside the sandbox would modify the running config but not persist changes across rebuilds. -### `nemoclaw channels stop ` +### `$$nemoclaw channels stop ` Pause a single messaging bridge (`telegram`, `discord`, `slack`, `wechat`, or `whatsapp`) without clearing its credentials. The channel is marked disabled in the per-sandbox registry, and the sandbox is rebuilt so the onboard step skips registering the bridge with the gateway. The provider stays registered with the OpenShell gateway, so a later `channels start` brings the bridge back without re-entering tokens. ```bash -nemoclaw my-assistant channels stop telegram +$$nemoclaw my-assistant channels stop telegram ``` | Flag | Description | @@ -948,24 +948,24 @@ nemoclaw my-assistant channels stop telegram Use `channels stop` instead of `channels remove` when you want to pause a bridge temporarily. `channels remove` is destructive to credentials; `channels stop` is not. -### `nemoclaw channels start ` +### `$$nemoclaw channels start ` Re-enable a channel previously paused with `channels stop`. The channel is removed from the disabled list, the sandbox is rebuilt, and the bridge registers with the gateway again using the stored credentials. ```bash -nemoclaw my-assistant channels start telegram +$$nemoclaw my-assistant channels start telegram ``` | Flag | Description | |------|-------------| | `--dry-run` | Report the channel that would be re-enabled without updating the registry or rebuilding | -### `nemoclaw channels status` +### `$$nemoclaw channels status` Run channel-specific runtime diagnostics. For WhatsApp the command probes the sandbox to separately report pairing/session state, the Noise WebSocket connection, inbound event delivery, and policy/config coverage; a paired channel with no observed inbound delivery exits non-zero with verdict `idle` so an unhealthy bridge cannot pass as healthy. ```bash -nemoclaw my-assistant channels status --channel whatsapp +$$nemoclaw my-assistant channels status --channel whatsapp ``` | Flag | Description | @@ -975,13 +975,13 @@ nemoclaw my-assistant channels status --channel whatsapp The probe is bounded by an in-sandbox `openshell sandbox exec` with a hard timeout, captures only short matched bridge log signals (e.g. `connection.open`, `401 unauthorized`, `qr expired`), and never forwards message bodies to the host diagnostic output. -### `nemoclaw skill install ` +### `$$nemoclaw skill install ` Deploy a skill directory to a running sandbox. The command validates the `SKILL.md` frontmatter (a `name` field is required), uploads all non-dot files preserving subdirectory structure, and performs agent-specific post-install steps. ```bash -nemoclaw my-assistant skill install ./my-skill/ +$$nemoclaw my-assistant skill install ./my-skill/ ``` The skill directory must contain a `SKILL.md` file with YAML frontmatter that includes a `name` field. @@ -989,7 +989,7 @@ Skill names must contain only alphanumeric characters, dots, hyphens, and unders -OpenClaw plugins are a different kind of extension. To install an OpenClaw plugin, see [Install OpenClaw Plugins](../manage-sandboxes/install-openclaw-plugins). +OpenClaw plugins are a different kind of extension. To install an OpenClaw plugin, see [Install OpenClaw Plugins](../deployment/install-openclaw-plugins.mdx). @@ -999,7 +999,7 @@ Hermes plugins are different from NemoClaw skills. -Run `nemoclaw skill install --help` to print usage for this subcommand. +Run `$$nemoclaw skill install --help` to print usage for this subcommand. If you pass a plugin-shaped directory to `skill install`, the CLI prints a plugin-specific hint instead of treating it as a missing skill file. Files with names starting with `.` (dotfiles) are skipped and listed in the output. @@ -1008,7 +1008,7 @@ Files with unsafe path characters are rejected to prevent shell injection. If the skill already exists on the sandbox, the command updates it in place and preserves chat history. For new installs, the agent session index is refreshed so the agent discovers the skill on the next session. -### `nemoclaw skill remove ` +### `$$nemoclaw skill remove ` Remove an installed skill from a running sandbox by skill name. The command validates the skill name, removes the sandbox upload directory, and refreshes the agent session index so the remaining skills are rediscovered on the next session. @@ -1025,64 +1025,64 @@ For Hermes, restart the Hermes gateway if prompted so the removal takes effect. ```bash -nemoclaw my-assistant skill remove my-skill +$$nemoclaw my-assistant skill remove my-skill ``` Use the skill name from the `SKILL.md` frontmatter, not the local directory name. Skill names must contain only alphanumeric characters, dots, hyphens, and underscores, and cannot be `.` or `..`. -### `nemoclaw agents add` +### `$$nemoclaw agents add` Run the OpenClaw interactive add wizard inside the sandbox. This is a thin pass-through to `openclaw agents add` via `openshell sandbox exec`; flags accepted by the in-sandbox CLI are forwarded verbatim. ```bash -nemoclaw my-assistant agents add -nemoclaw my-assistant agents add work --model gpt-4o +$$nemoclaw my-assistant agents add +$$nemoclaw my-assistant agents add work --model gpt-4o ``` -### `nemoclaw agents delete ` +### `$$nemoclaw agents delete ` Remove an OpenClaw agent from the sandbox. This is a thin pass-through to `openclaw agents delete ` via `openshell sandbox exec`; the OpenClaw CLI owns gateway dispatch (`agents.delete`), host-side workspace removal, and config edits. Flags accepted by the in-sandbox CLI (`--force`, `--json`) are forwarded verbatim. ```bash -nemoclaw my-assistant agents delete work -nemoclaw my-assistant agents delete work --force --json +$$nemoclaw my-assistant agents delete work +$$nemoclaw my-assistant agents delete work --force --json ``` -### `nemoclaw sessions` +### `$$nemoclaw sessions` List OpenClaw conversation sessions in the sandbox. With no subcommand the in-sandbox CLI lists stored sessions for the configured default agent. This is a thin pass-through to `openclaw sessions` via `openshell sandbox exec`; flags accepted by the in-sandbox CLI are forwarded verbatim. ```bash -nemoclaw my-assistant sessions -nemoclaw my-assistant sessions --all-agents --json +$$nemoclaw my-assistant sessions +$$nemoclaw my-assistant sessions --all-agents --json ``` -### `nemoclaw sessions list` +### `$$nemoclaw sessions list` Pass-through to `openclaw sessions list` inside the sandbox. Accepts every flag the in-sandbox CLI does (`--agent`, `--all-agents`, `--active`, `--limit`, `--json`, `--store`, `--verbose`). ```bash -nemoclaw my-assistant sessions list -nemoclaw my-assistant sessions list --agent work --json +$$nemoclaw my-assistant sessions list +$$nemoclaw my-assistant sessions list --agent work --json ``` -### `nemoclaw sessions reset ` +### `$$nemoclaw sessions reset ` Archive a session and rebind its key to a fresh `sessionId` by invoking the OpenClaw gateway `sessions.reset` RPC inside the sandbox. Goes through `openshell sandbox exec` -> `openclaw gateway call sessions.reset`, so the gateway owns archival, lock handling, and lifecycle events; the host never edits `sessions.json` directly. ```bash -nemoclaw my-assistant sessions reset main -nemoclaw my-assistant sessions reset agent:work:telegram:t-1 -nemoclaw my-assistant sessions reset telegram:t-1 --agent work --reason new -nemoclaw my-assistant sessions reset agent:main:main --json +$$nemoclaw my-assistant sessions reset main +$$nemoclaw my-assistant sessions reset agent:work:telegram:t-1 +$$nemoclaw my-assistant sessions reset telegram:t-1 --agent work --reason new +$$nemoclaw my-assistant sessions reset agent:main:main --json ``` | Flag | Description | @@ -1095,17 +1095,17 @@ nemoclaw my-assistant sessions reset agent:main:main --json The `` argument accepts an alias (e.g. `main`, `telegram:t-1`) or the canonical `agent::` form. Mismatched `--agent` plus canonical-key combinations are refused before the gateway is invoked. -### `nemoclaw sessions delete ` +### `$$nemoclaw sessions delete ` Remove a session entry by invoking the OpenClaw gateway `sessions.delete` RPC inside the sandbox. The gateway refuses to remove the agent's main session. The transcript on disk is removed by default; pass `--keep-transcript` to retain it. ```bash -nemoclaw my-assistant sessions delete telegram:t-1 -nemoclaw my-assistant sessions delete agent:work:telegram:t-1 -nemoclaw my-assistant sessions delete telegram:t-1 --agent work --keep-transcript -nemoclaw my-assistant sessions delete agent:main:slack:c-9 --json +$$nemoclaw my-assistant sessions delete telegram:t-1 +$$nemoclaw my-assistant sessions delete agent:work:telegram:t-1 +$$nemoclaw my-assistant sessions delete telegram:t-1 --agent work --keep-transcript +$$nemoclaw my-assistant sessions delete agent:main:slack:c-9 --json ``` | Flag | Description | @@ -1115,7 +1115,7 @@ nemoclaw my-assistant sessions delete agent:main:slack:c-9 --json | `--json` | Print the delete result as JSON. | | `--verbose` | Print the gateway entry payload after a successful delete. | -### `nemoclaw rebuild` +### `$$nemoclaw rebuild` Upgrade a sandbox to the current agent version while preserving workspace state. The command backs up workspace state, destroys the old sandbox (including its host-side Docker image), recreates it with the current image via `onboard --resume`, and restores workspace state into the new sandbox. @@ -1126,7 +1126,7 @@ A sandbox onboarded with an explicit GPU opt-out (stored as `sandboxGpuMode: "0" Auto-mode sandboxes remain auto. ```bash -nemoclaw my-assistant rebuild [--yes|-y|--force] [--verbose|-v] +$$nemoclaw my-assistant rebuild [--yes|-y|--force] [--verbose|-v] ``` | Flag | Description | @@ -1152,7 +1152,7 @@ After restore, the command restores Hermes manifest-defined state and starts the -### `nemoclaw update` +### `$$nemoclaw update` Check for a NemoClaw CLI update and, when requested, run the maintained installer flow. This command is a discoverable CLI wrapper around the supported installer path: @@ -1162,7 +1162,7 @@ curl -fsSL https://www.nvidia.com/nemoclaw.sh | bash ``` ```bash -nemoclaw update [--check] [--yes|-y] +$$nemoclaw update [--check] [--yes|-y] ``` | Flag | Description | @@ -1170,19 +1170,19 @@ nemoclaw update [--check] [--yes|-y] | `--check` | Show the current version, latest maintained version, install type, and maintained update command without changing anything | | `--yes`, `-y` | Skip the confirmation prompt and run the maintained installer flow | -`nemoclaw update` updates the host-side NemoClaw installation. +`$$nemoclaw update` updates the host-side NemoClaw installation. The maintained installer flow follows the admin-promoted `lkg` release tag by default, so it may trail the newest semver or `latest` tag while validation completes. -It does not replace `nemoclaw upgrade-sandboxes`; use that command to inspect or rebuild existing sandboxes after the CLI has been updated. +It does not replace `$$nemoclaw upgrade-sandboxes`; use that command to inspect or rebuild existing sandboxes after the CLI has been updated. When the command is running from a source checkout, it reports that state and does not replace the checkout with a global package install. -### `nemoclaw upgrade-sandboxes` +### `$$nemoclaw upgrade-sandboxes` Rebuild sandboxes whose base image is older than the one currently pinned by NemoClaw. NemoClaw resolves the digest of `ghcr.io/nvidia/nemoclaw/sandbox-base:latest` from the registry, then compares it against the digest each sandbox was created with. Sandboxes that match the current digest are left alone. ```bash -nemoclaw upgrade-sandboxes [--check] [--auto] [--yes|-y] +$$nemoclaw upgrade-sandboxes [--check] [--auto] [--yes|-y] ``` | Flag | Description | @@ -1191,27 +1191,27 @@ nemoclaw upgrade-sandboxes [--check] [--auto] [--yes|-y] | `--auto` | Rebuild every stale sandbox without prompting. Used by the installer to upgrade in place. | | `--yes`, `-y` | Skip the confirmation prompt for the rebuild plan. | -Each rebuild reuses the same workspace backup-and-restore flow as `nemoclaw rebuild`, so workspace files survive the upgrade. +Each rebuild reuses the same workspace backup-and-restore flow as `$$nemoclaw rebuild`, so workspace files survive the upgrade. If the registry is unreachable (offline or firewalled hosts), NemoClaw falls back to the unpinned `:latest` tag and reports that the digest could not be resolved instead of failing. -### `nemoclaw backup-all` +### `$$nemoclaw backup-all` Back up all registered running sandboxes to `~/.nemoclaw/rebuild-backups/`. Sandboxes that are not running are skipped. ```bash -nemoclaw backup-all +$$nemoclaw backup-all ``` The installer calls `backup-all` automatically before onboarding to protect against data loss during OpenShell upgrades. -### `nemoclaw snapshot create` +### `$$nemoclaw snapshot create` Create a timestamped snapshot of sandbox state. Snapshots are stored in `~/.nemoclaw/rebuild-backups//`. ```bash -nemoclaw my-assistant snapshot create +$$nemoclaw my-assistant snapshot create ``` | Flag | Description | @@ -1221,19 +1221,19 @@ nemoclaw my-assistant snapshot create Names must be 1 to 63 characters from `[A-Za-z0-9._-]`, start with an alphanumeric character, and cannot look like a version selector (`v1`, `v2`, ...). Duplicate names per sandbox are rejected; pick a different name or delete the existing snapshot first. ```bash -nemoclaw my-assistant snapshot create --name before-upgrade +$$nemoclaw my-assistant snapshot create --name before-upgrade ``` -### `nemoclaw snapshot list` +### `$$nemoclaw snapshot list` List available snapshots for a sandbox as a table of version, name, timestamp, and path. Versions (`v1`, `v2`, ...) are computed on read from timestamp-ascending order, so `v1` is the oldest snapshot and `vN` is the newest. Snapshots created before this feature landed are numbered retroactively. ```bash -nemoclaw my-assistant snapshot list +$$nemoclaw my-assistant snapshot list ``` -### `nemoclaw snapshot restore [selector] [--to ] [--force] [--yes|-y]` +### `$$nemoclaw snapshot restore [selector] [--to ] [--force] [--yes|-y]` Restore sandbox state from a snapshot. The sandbox must be running before you restore. @@ -1256,35 +1256,35 @@ The snapshot selector and source pod image are both validated before any deletio ```bash # restore latest snapshot in-place -nemoclaw my-assistant snapshot restore +$$nemoclaw my-assistant snapshot restore # restore by version -nemoclaw my-assistant snapshot restore v3 +$$nemoclaw my-assistant snapshot restore v3 # restore by user-assigned name -nemoclaw my-assistant snapshot restore before-upgrade +$$nemoclaw my-assistant snapshot restore before-upgrade # restore by exact timestamp -nemoclaw my-assistant snapshot restore 2026-04-21T07-35-55-987Z +$$nemoclaw my-assistant snapshot restore 2026-04-21T07-35-55-987Z # clone v3 into a new sandbox -nemoclaw my-assistant snapshot restore v3 --to my-assistant-clone +$$nemoclaw my-assistant snapshot restore v3 --to my-assistant-clone # overwrite an existing destination with v3, non-interactively -nemoclaw my-assistant snapshot restore v3 --to my-assistant-clone --force --yes +$$nemoclaw my-assistant snapshot restore v3 --to my-assistant-clone --force --yes ``` When `--to` names an existing sandbox, restore refuses to overwrite it unless you pass `--force`. With `--force`, NemoClaw confirms the destructive restore unless you also pass `--yes` or run with `NEMOCLAW_NON_INTERACTIVE=1`. Use this path only when the destination sandbox can be replaced by the selected snapshot. -### `nemoclaw share mount` +### `$$nemoclaw share mount` Mount the sandbox filesystem on the host machine via SSHFS for bidirectional file sharing. Files edited on the host appear instantly inside the sandbox, and vice versa. ```console -$ nemoclaw my-assistant share mount +$ $$nemoclaw my-assistant share mount ✓ Mounted /sandbox → ~/.nemoclaw/mounts/my-assistant ``` @@ -1298,33 +1298,33 @@ Prerequisites: - `sshfs` must be installed on the host (`sudo apt-get install sshfs` on Linux, `brew install macfuse && brew install sshfs` on macOS). - The sandbox must be running. - The remote sandbox path must exist. NemoClaw verifies it against the target sandbox before invoking `sshfs` and prints a `connect`, then `ls ` check when the probe fails. -- Sandboxes created before the `openssh-sftp-server` base image update must be rebuilt with `nemoclaw rebuild`. +- Sandboxes created before the `openssh-sftp-server` base image update must be rebuilt with `$$nemoclaw rebuild`. - The local mount path must be on a writable filesystem; FUSE creates the mount on the host side. If the default `~/.nemoclaw/mounts/` lives on a read-only filesystem, pass an explicit writable path as the second positional argument. ```bash # mount a specific path to a custom local directory -nemoclaw my-assistant share mount /sandbox/workspace ~/my-workspace +$$nemoclaw my-assistant share mount /sandbox/workspace ~/my-workspace ``` -### `nemoclaw share unmount` +### `$$nemoclaw share unmount` Unmount a previously mounted sandbox filesystem. ```bash -nemoclaw my-assistant share unmount +$$nemoclaw my-assistant share unmount ``` | Argument | Default | Description | |----------|---------|-------------| | `local-mount-point` | `~/.nemoclaw/mounts/` | Local directory to unmount | -### `nemoclaw share status` +### `$$nemoclaw share status` Check whether the sandbox filesystem is currently mounted. ```console -$ nemoclaw my-assistant share status +$ $$nemoclaw my-assistant share status ● Mounted at ~/.nemoclaw/mounts/my-assistant ``` @@ -1343,14 +1343,14 @@ openshell term For a remote Brev instance, SSH to the instance and run `openshell term` there, or use a port-forward to the gateway. -### `nemoclaw tunnel start` +### `$$nemoclaw tunnel start` Start optional host auxiliary services. This is the cloudflared tunnel when `cloudflared` is installed, which exposes the dashboard with a public URL. -Channel messaging (Telegram, Discord, Slack) is not started here; it is configured during `nemoclaw onboard` and runs through OpenShell-managed constructs. +Channel messaging (Telegram, Discord, Slack) is not started here; it is configured during `$$nemoclaw onboard` and runs through OpenShell-managed constructs. ```bash -nemoclaw tunnel start +$$nemoclaw tunnel start ``` By default, NemoClaw starts a Cloudflare quick tunnel and prints the generated `*.trycloudflare.com` URL when `cloudflared` reports it. @@ -1360,14 +1360,14 @@ NemoClaw passes the token to `cloudflared` through the `TUNNEL_TOKEN` environmen ```bash export CLOUDFLARE_TUNNEL_TOKEN= -nemoclaw tunnel start +$$nemoclaw tunnel start ``` -`nemoclaw start` remains as a deprecated alias that prints a warning and delegates to `tunnel start`. +`$$nemoclaw start` remains as a deprecated alias that prints a warning and delegates to `tunnel start`. -### `nemoclaw tunnel stop` +### `$$nemoclaw tunnel stop` -Stop host auxiliary services that `nemoclaw tunnel start` started (for example cloudflared). +Stop host auxiliary services that `$$nemoclaw tunnel start` started (for example cloudflared). @@ -1380,60 +1380,60 @@ For Hermes sandboxes, use channel lifecycle commands when you only want to pause -Use `nemoclaw channels stop ` when you only want to pause one bridge without stopping the gateway. +Use `$$nemoclaw channels stop ` when you only want to pause one bridge without stopping the gateway. ```bash -nemoclaw tunnel stop +$$nemoclaw tunnel stop ``` -`nemoclaw stop` remains as a deprecated alias that prints a warning and delegates to `tunnel stop`. +`$$nemoclaw stop` remains as a deprecated alias that prints a warning and delegates to `tunnel stop`. -### `nemoclaw start` +### `$$nemoclaw start` -Deprecated. Use `nemoclaw tunnel start` instead. +Deprecated. Use `$$nemoclaw tunnel start` instead. -This command remains as a compatibility alias to `nemoclaw tunnel start`. +This command remains as a compatibility alias to `$$nemoclaw tunnel start`. -### `nemoclaw stop` +### `$$nemoclaw stop` -Deprecated. Use `nemoclaw tunnel stop` instead. +Deprecated. Use `$$nemoclaw tunnel stop` instead. -This command remains as a compatibility alias to `nemoclaw tunnel stop`. +This command remains as a compatibility alias to `$$nemoclaw tunnel stop`. -### `nemoclaw status` +### `$$nemoclaw status` Show the sandbox list and the status of host auxiliary services (for example cloudflared). Pass `--json` for machine-readable output with registered sandboxes, service state, inference routes, and messaging health. For each listed sandbox, the text output includes the configured inference provider and model plus whether an active SSH session is connected. ```bash -nemoclaw status -nemoclaw status --json +$$nemoclaw status +$$nemoclaw status --json ``` When at least one sandbox is registered and the named NemoClaw gateway is unreachable, unhealthy, or attached to a different sandbox, the command prints a `gateway: down [state] (reason)` line between the sandbox list and the host-service list. The command classifies the failing layer when possible: the named gateway port is not accepting connections, the named gateway is running but not Connected, the active OpenShell gateway points at a different name, or the named gateway is not configured at all. -It then suggests `openshell gateway start --name nemoclaw` or `nemoclaw onboard --resume` to recover. +It then suggests `openshell gateway start --name nemoclaw` or `$$nemoclaw onboard --resume` to recover. It exits with code `1` so shell scripts and CI can detect the degraded state from `$?`. For `--json`, the structured output includes `gatewayHealth`, and the exit code is set after the report is generated. A clean machine with no registered sandboxes keeps the legacy `0` exit because no gateway is expected to be configured yet. -If cloudflared is installed but not running, the host-service section reports whether the PID file is missing, invalid, or points at a dead process, then suggests `nemoclaw tunnel start` as the recovery command. +If cloudflared is installed but not running, the host-service section reports whether the PID file is missing, invalid, or points at a dead process, then suggests `$$nemoclaw tunnel start` as the recovery command. -### `nemoclaw inference get` +### `$$nemoclaw inference get` Show the active live inference provider and model from the NemoClaw-managed OpenShell gateway. Use this command when you want the direct runtime route without the rest of the sandbox status output. ```bash -nemoclaw inference get -nemoclaw inference get --json +$$nemoclaw inference get +$$nemoclaw inference get --json ``` -### `nemoclaw inference set` +### `$$nemoclaw inference set` Switch the active inference provider or model for a NemoClaw-managed OpenClaw or Hermes sandbox. The command updates the OpenShell gateway route, patches the selected running agent config so it matches the route, recomputes the config hash, and updates the NemoClaw registry. @@ -1453,52 +1453,52 @@ Under the `nemohermes` alias, it uses the registered Hermes sandbox when exactly By default, the command syncs the default registered sandbox. ```bash -nemoclaw inference set --provider --model [--sandbox ] [--no-verify] +$$nemoclaw inference set --provider --model [--sandbox ] [--no-verify] ``` Pass both `--provider` and `--model` when you want NemoClaw to update the OpenShell inference route and sync the selected sandbox's agent config. If you only want the lower-level OpenShell route operation, run `openshell inference set -g nemoclaw --model --provider ` directly. -When either flag is missing, `nemoclaw inference set` prints that OpenShell command instead of an oclif flag-validation error. +When either flag is missing, `$$nemoclaw inference set` prints that OpenShell command instead of an oclif flag-validation error. The command updates the host registry immediately after the gateway route changes. -If the in-sandbox config sync fails, NemoClaw keeps the gateway and registry aligned, warns that the running image may still need a rebuild, and points you to `nemoclaw rebuild`. +If the in-sandbox config sync fails, NemoClaw keeps the gateway and registry aligned, warns that the running image may still need a rebuild, and points you to `$$nemoclaw rebuild`. Supported provider names are `nvidia-prod`, `nvidia-nim`, `nvidia-router`, `openai-api`, `anthropic-prod`, `compatible-anthropic-endpoint`, `gemini-api`, `compatible-endpoint`, `hermes-provider`, `ollama-local`, and `vllm-local`. Use `--no-verify` only when OpenShell cannot verify the provider at switch time but you have already confirmed the provider and credential. -### `nemoclaw setup` +### `$$nemoclaw setup` -The `nemoclaw setup` command is deprecated. -Use `nemoclaw onboard` instead. +The `$$nemoclaw setup` command is deprecated. +Use `$$nemoclaw onboard` instead. -This command remains as a compatibility alias to `nemoclaw onboard` and accepts the same flags: `--non-interactive`, `--resume`, `--fresh`, `--recreate-sandbox`, `--gpu` / `--no-gpu`, `--from`, `--name`, `--sandbox-gpu` / `--no-sandbox-gpu`, `--sandbox-gpu-device`, `--agent`, `--control-ui-port`, `--yes` / `-y`, `--no-ollama-autostart`, `--yes-i-accept-third-party-software`. +This command remains as a compatibility alias to `$$nemoclaw onboard` and accepts the same flags: `--non-interactive`, `--resume`, `--fresh`, `--recreate-sandbox`, `--gpu` / `--no-gpu`, `--from`, `--name`, `--sandbox-gpu` / `--no-sandbox-gpu`, `--sandbox-gpu-device`, `--agent`, `--control-ui-port`, `--yes` / `-y`, `--no-ollama-autostart`, `--yes-i-accept-third-party-software`. ```bash -nemoclaw setup +$$nemoclaw setup ``` -### `nemoclaw setup-spark` +### `$$nemoclaw setup-spark` -The `nemoclaw setup-spark` command is deprecated. -Use the standard installer and run `nemoclaw onboard` instead, because current OpenShell releases handle the older DGX Spark cgroup behavior. +The `$$nemoclaw setup-spark` command is deprecated. +Use the standard installer and run `$$nemoclaw onboard` instead, because current OpenShell releases handle the older DGX Spark cgroup behavior. -This command remains as a compatibility alias to `nemoclaw onboard` and accepts the same flags: `--non-interactive`, `--resume`, `--fresh`, `--recreate-sandbox`, `--gpu` / `--no-gpu`, `--from`, `--name`, `--sandbox-gpu` / `--no-sandbox-gpu`, `--sandbox-gpu-device`, `--agent`, `--control-ui-port`, `--yes` / `-y`, `--no-ollama-autostart`, `--yes-i-accept-third-party-software`. +This command remains as a compatibility alias to `$$nemoclaw onboard` and accepts the same flags: `--non-interactive`, `--resume`, `--fresh`, `--recreate-sandbox`, `--gpu` / `--no-gpu`, `--from`, `--name`, `--sandbox-gpu` / `--no-sandbox-gpu`, `--sandbox-gpu-device`, `--agent`, `--control-ui-port`, `--yes` / `-y`, `--no-ollama-autostart`, `--yes-i-accept-third-party-software`. ```bash -nemoclaw setup-spark +$$nemoclaw setup-spark ``` -### `nemoclaw debug` +### `$$nemoclaw debug` Collect diagnostics for bug reports. Gathers system info, Docker state, gateway logs, and sandbox status into a summary or tarball. Use `--sandbox ` to target a specific sandbox, `--quick` for a smaller snapshot, or `--output ` to save a tarball that you can attach to an issue. ```bash -nemoclaw debug [--quick|-q] [--sandbox NAME] [--output PATH|-o PATH] +$$nemoclaw debug [--quick|-q] [--sandbox NAME] [--output PATH|-o PATH] ``` | Flag | Description | @@ -1510,40 +1510,40 @@ nemoclaw debug [--quick|-q] [--sandbox NAME] [--output PATH|-o PATH] If `--output` is set and the tarball cannot be written (for example, the destination directory is missing or read-only), the command exits non-zero so scripts can detect the failure. The tarball is written to a temporary sibling and renamed on success, so a pre-existing file at `--output` is preserved when `tar` fails. -When `--sandbox` is supplied explicitly (via flag or one of `NEMOCLAW_SANDBOX_NAME`, `NEMOCLAW_SANDBOX`, `SANDBOX_NAME` — flag wins, then the env vars in that order), the name must match a registered sandbox; if `openshell sandbox list` succeeds it must also appear in the live gateway. An unknown or stale name exits non-zero with an actionable error that names the sandbox and reports the source env var when applicable, and no tarball is written. Without an explicit name, `nemoclaw debug` falls back to the registry's default sandbox (and warns if that default is stale). +When `--sandbox` is supplied explicitly (via flag or one of `NEMOCLAW_SANDBOX_NAME`, `NEMOCLAW_SANDBOX`, `SANDBOX_NAME` — flag wins, then the env vars in that order), the name must match a registered sandbox; if `openshell sandbox list` succeeds it must also appear in the live gateway. An unknown or stale name exits non-zero with an actionable error that names the sandbox and reports the source env var when applicable, and no tarball is written. Without an explicit name, `$$nemoclaw debug` falls back to the registry's default sandbox (and warns if that default is stale). -### `nemoclaw credentials list` +### `$$nemoclaw credentials list` List the provider credentials registered with the OpenShell gateway. Values are not printed. ```bash -nemoclaw credentials list +$$nemoclaw credentials list ``` -### `nemoclaw credentials reset ` +### `$$nemoclaw credentials reset ` Remove a provider credential from the OpenShell gateway by provider name. -After removal, re-running `nemoclaw onboard` re-prompts for that provider's credential. -Run `nemoclaw credentials list` first if you are not sure of the provider name. +After removal, re-running `$$nemoclaw onboard` re-prompts for that provider's credential. +Run `$$nemoclaw credentials list` first if you are not sure of the provider name. ```bash -nemoclaw credentials reset nvidia-prod +$$nemoclaw credentials reset nvidia-prod ``` | Flag | Description | |------|-------------| | `--yes`, `-y` | Skip the confirmation prompt | -### `nemoclaw gc` +### `$$nemoclaw gc` Remove orphaned sandbox Docker images from the host. -Each `nemoclaw onboard` builds an `openshell/sandbox-from:` image (~765 MB). +Each `$$nemoclaw onboard` builds an `openshell/sandbox-from:` image (~765 MB). The `destroy` and `rebuild` commands clean up the image automatically, but images from older NemoClaw versions or interrupted operations may remain. This command lists all `openshell/sandbox-from:*` images, cross-references the sandbox registry, and removes any that are no longer associated with a registered sandbox. ```bash -nemoclaw gc [--dry-run] [--yes|-y|--force] +$$nemoclaw gc [--dry-run] [--yes|-y|--force] ``` | Flag | Description | @@ -1551,7 +1551,7 @@ nemoclaw gc [--dry-run] [--yes|-y|--force] | `--dry-run` | List orphaned images without removing them | | `--yes`, `-y`, `--force` | Skip the confirmation prompt | -### `nemoclaw uninstall` +### `$$nemoclaw uninstall` Run `uninstall.sh` to remove NemoClaw sandboxes, gateway resources, related images and containers, and local state. The CLI runs the local `uninstall.sh` shipped with the installed npm package. @@ -1570,10 +1570,10 @@ On Linux, uninstall removes `~/.local/state/nemoclaw`, which contains Docker-dri | `--yes` | Skip the confirmation prompt | | `--keep-openshell` | Leave OpenShell binaries installed | | `--delete-models` | Also remove NemoClaw-pulled Ollama models | -| `--gateway ` | Override the gateway name to remove (default: `nemoclaw`) | +| `--gateway ` | Override the gateway name to remove (default: `$$nemoclaw`) | ```bash -nemoclaw uninstall [--yes] [--keep-openshell] [--delete-models] [--gateway ] +$$nemoclaw uninstall [--yes] [--keep-openshell] [--delete-models] [--gateway ] ``` ##### User-data preservation under `~/.nemoclaw/` @@ -1582,7 +1582,7 @@ To avoid uninstall destroying host-side user data, uninstall preserves the follo | Entry | What it holds | |---|---| -| `rebuild-backups/` | Host-side snapshots that `nemoclaw snapshot create` and `nemoclaw backup-all` write. `nemoclaw snapshot restore` reads them back after you reinstall. | +| `rebuild-backups/` | Host-side snapshots that `$$nemoclaw snapshot create` and `$$nemoclaw backup-all` write. `$$nemoclaw snapshot restore` reads them back after you reinstall. | | `backups/` | Host-side workspace backups that `scripts/backup-workspace.sh` writes (see [Backup and Restore](../manage-sandboxes/backup-restore)). | | `sandboxes.json` | Host-side sandbox registry. NemoClaw uses it to map sandbox names back to their persistence directories when you reinstall. | @@ -1598,20 +1598,20 @@ Decision matrix: | Any context with `NEMOCLAW_UNINSTALL_DESTROY_USER_DATA=1` | Skips the prompt and removes everything under `~/.nemoclaw/`. | The preserved entries survive uninstall as inert files on disk. -Reinstall NemoClaw and re-onboard the sandbox before `nemoclaw snapshot restore` can use them. +Reinstall NemoClaw and re-onboard the sandbox before `$$nemoclaw snapshot restore` can use them. -#### `nemoclaw uninstall` vs. the hosted `uninstall.sh` +#### `$$nemoclaw uninstall` vs. the hosted `uninstall.sh` Both forms execute the same `uninstall.sh` with the same flags, but differ in where the script comes from and how much they trust the network. -Use `nemoclaw uninstall` by default. +Use `$$nemoclaw uninstall` by default. Use the hosted `curl … | bash` form only when the CLI is broken or already partially removed. -| | `nemoclaw uninstall` | `curl … \| bash` (Quickstart) | +| | `$$nemoclaw uninstall` | `curl … \| bash` (Quickstart) | |---|---|---| | **Source of the script** | Local `uninstall.sh` shipped with the installed npm package. | Pulled live from `refs/heads/main` on GitHub. | | **Version pinning** | Pinned to the version of NemoClaw you installed. | Whatever is on `main` right now; may be newer than your installed CLI. | | **Network trust** | No network fetch at uninstall time; runs a vetted local file via `bash`. | Pipes a remote script straight to `bash` with no review step. | -| **Robustness** | Requires the npm package to be discoverable so the CLI can find the local script. | Works even if the `nemoclaw` CLI is missing, broken, or partially uninstalled. | +| **Robustness** | Requires the npm package to be discoverable so the CLI can find the local script. | Works even if the `$$nemoclaw` CLI is missing, broken, or partially uninstalled. | | **Recommended for** | Routine uninstalls. | Recovery when the CLI is unavailable. | ## Internal Commands @@ -1622,7 +1622,7 @@ uninstaller, DNS setup, and developer tooling. They are not part of the supported public CLI surface. Each command class sets `hidden = true`, so the commands stay out of -`nemoclaw --help`. They remain registered and routable, which is why they are +`$$nemoclaw --help`. They remain registered and routable, which is why they are listed here for reference. Treat their names, flags, and output as implementation details. They exist to back `install.sh`, `uninstall.sh`, and related automation, and they may change or be removed without notice. Most run @@ -1633,25 +1633,25 @@ For contributor guidance on how these command files are structured, see | Command | Owning script context | Purpose | |---------|-----------------------|---------| -| `nemoclaw internal installer plan` | `install.sh` | Build a deterministic installer plan from environment and probe inputs without applying it. | -| `nemoclaw internal installer normalize-env` | `install.sh` | Normalize installer ref and provider environment values without applying installation changes. | -| `nemoclaw internal installer resolve-release-tag` | `install.sh` | Resolve the installer ref using the same precedence as `install.sh`. | -| `nemoclaw internal uninstall plan` | `uninstall.sh` / `nemoclaw uninstall` | Build a deterministic uninstall plan without applying it. | -| `nemoclaw internal uninstall run-plan` | `uninstall.sh` / `nemoclaw uninstall` | Remove host-side NemoClaw resources from a previously built plan. | -| `nemoclaw internal uninstall classify-shim` | `uninstall.sh` / `nemoclaw uninstall` | Classify whether a shim path is safe for the uninstaller to remove. | -| `nemoclaw internal dns setup-proxy` | onboarding / sandbox setup | Configure the DNS forwarder bridge inside a sandbox pod. | -| `nemoclaw internal dns fix-coredns` | onboarding / sandbox setup | Patch CoreDNS to use a non-loopback upstream resolver. | -| `nemoclaw internal dev npm-link-or-shim` | `scripts/npm-link-or-shim.sh` (development) | Run `npm link`, falling back to a user-local NemoClaw development shim. | +| `$$nemoclaw internal installer plan` | `install.sh` | Build a deterministic installer plan from environment and probe inputs without applying it. | +| `$$nemoclaw internal installer normalize-env` | `install.sh` | Normalize installer ref and provider environment values without applying installation changes. | +| `$$nemoclaw internal installer resolve-release-tag` | `install.sh` | Resolve the installer ref using the same precedence as `install.sh`. | +| `$$nemoclaw internal uninstall plan` | `uninstall.sh` / `$$nemoclaw uninstall` | Build a deterministic uninstall plan without applying it. | +| `$$nemoclaw internal uninstall run-plan` | `uninstall.sh` / `$$nemoclaw uninstall` | Remove host-side NemoClaw resources from a previously built plan. | +| `$$nemoclaw internal uninstall classify-shim` | `uninstall.sh` / `$$nemoclaw uninstall` | Classify whether a shim path is safe for the uninstaller to remove. | +| `$$nemoclaw internal dns setup-proxy` | onboarding / sandbox setup | Configure the DNS forwarder bridge inside a sandbox pod. | +| `$$nemoclaw internal dns fix-coredns` | onboarding / sandbox setup | Patch CoreDNS to use a non-loopback upstream resolver. | +| `$$nemoclaw internal dev npm-link-or-shim` | `scripts/npm-link-or-shim.sh` (development) | Run `npm link`, falling back to a user-local NemoClaw development shim. | These commands do not appear in the command-level parity check, which compares -`nemoclaw --help` against the public command headings in this reference; hidden +`$$nemoclaw --help` against the public command headings in this reference; hidden commands are excluded from both. The table above is the canonical reference for the family. ## Environment Variables NemoClaw reads the following environment variables to configure service ports, onboarding behavior, and lifecycle defaults. -Set them before running `nemoclaw onboard` or any command that starts services. +Set them before running `$$nemoclaw onboard` or any command that starts services. All ports must be non-privileged integers between 1024 and 65535. | Variable | Default | Service | @@ -1675,7 +1675,7 @@ Binding the OpenShell gateway to `0.0.0.0` may make it reachable from other host `NEMOCLAW_DASHBOARD_BIND` controls the dashboard or API port forward bind address. By default the forward stays on `127.0.0.1` (loopback only). -Set `NEMOCLAW_DASHBOARD_BIND=0.0.0.0` before `nemoclaw onboard` (or `nemoclaw connect`) to bind the forward on all interfaces, which is useful when the host is reached over SSH or a cloud workstation. +Set `NEMOCLAW_DASHBOARD_BIND=0.0.0.0` before `$$nemoclaw onboard` (or `$$nemoclaw connect`) to bind the forward on all interfaces, which is useful when the host is reached over SSH or a cloud workstation. Only `0.0.0.0` enables the remote bind; other values are ignored. @@ -1686,11 +1686,11 @@ When the remote bind is opted in, the dashboard auth flow accepts non-loopback o ```bash export NEMOCLAW_DASHBOARD_PORT=19000 -nemoclaw onboard +$$nemoclaw onboard ``` ```bash -NEMOCLAW_GATEWAY_BIND_ADDRESS=0.0.0.0 NEMOCLAW_GATEWAY_PORT=8990 nemoclaw onboard +NEMOCLAW_GATEWAY_BIND_ADDRESS=0.0.0.0 NEMOCLAW_GATEWAY_PORT=8990 $$nemoclaw onboard ``` These overrides apply to onboarding, status checks, health probes, and the uninstaller. @@ -1720,7 +1720,7 @@ The Hermes API remains on port `8642`; the optional browser dashboard uses `NEMO ### Onboarding Configuration These variables let you tune onboarding without editing the Dockerfile or passing repeated flags. -Set them before running `nemoclaw onboard`. +Set them before running `$$nemoclaw onboard`. | Variable | Format | Effect | |----------|--------|--------| @@ -1824,12 +1824,12 @@ The run exits with an actionable diagnostic instead. ### Onboarding Behavior Flags -These flags toggle optional behaviors during onboarding; set them before running `nemoclaw onboard`. +These flags toggle optional behaviors during onboarding; set them before running `$$nemoclaw onboard`. | Variable | Format | Effect | |----------|--------|--------| | `NEMOCLAW_YES` | `1` to enable | Auto-accepts confirmation prompts (`--yes` equivalent) including in helpers like the Ollama proxy auth setup. | -| `NEMOCLAW_OLLAMA_NO_AUTOSTART` | `1` to enable | Skips the wizard's eager Ollama auto-start during inference-provider selection (equivalent to passing `--no-ollama-autostart`). When set and Ollama is not running on `localhost:11434`, the `nemoclaw onboard` Local Ollama path prints a warning and selects the default fallback model instead of spawning `ollama serve`. The flag covers only the provider-selection step; later setup steps (auth proxy, validation, model warm) still expect a reachable Ollama. On Linux hosts with a systemd Ollama unit, the loopback-override path may still restart the daemon before this gate runs. | +| `NEMOCLAW_OLLAMA_NO_AUTOSTART` | `1` to enable | Skips the wizard's eager Ollama auto-start during inference-provider selection (equivalent to passing `--no-ollama-autostart`). When set and Ollama is not running on `localhost:11434`, the `$$nemoclaw onboard` Local Ollama path prints a warning and selects the default fallback model instead of spawning `ollama serve`. The flag covers only the provider-selection step; later setup steps (auth proxy, validation, model warm) still expect a reachable Ollama. On Linux hosts with a systemd Ollama unit, the loopback-override path may still restart the daemon before this gate runs. | | `NEMOCLAW_NON_INTERACTIVE_SUDO_MODE` | `prompt` or empty/unset | When set to `prompt`, allows non-interactive onboarding to use prompt-capable `sudo` for host setup steps that require elevation, which can ask for a password. Empty/unset is the default and uses `sudo -n`, which fails instead of asking for a password. Any other value is rejected. | | `NEMOCLAW_NO_EXPRESS` | `1` to enable | Installer-only. Skips the DGX Spark, DGX Station, and Windows WSL express install prompt and continues with the normal interactive onboarding flow. | | `NEMOCLAW_EXPERIMENTAL` | `1` to enable | Surfaces experimental providers and flows in onboarding. | @@ -1853,14 +1853,14 @@ These flags toggle optional behaviors during onboarding; set them before running ### Onboard Profiling Traces -Set `NEMOCLAW_TRACE=1` before `nemoclaw onboard` to write an OpenTelemetry-style JSON trace for the run. +Set `NEMOCLAW_TRACE=1` before `$$nemoclaw onboard` to write an OpenTelemetry-style JSON trace for the run. When no explicit path is provided, NemoClaw writes a timestamped file under `.e2e/traces/` in the current working directory. Use `NEMOCLAW_TRACE_DIR` to choose the output directory, or `NEMOCLAW_TRACE_FILE` to choose the exact output file. ```bash -NEMOCLAW_TRACE=1 nemoclaw onboard -NEMOCLAW_TRACE_DIR=/tmp/nemoclaw-traces nemoclaw onboard -NEMOCLAW_TRACE_FILE=/tmp/nemoclaw-onboard-trace.json nemoclaw onboard +NEMOCLAW_TRACE=1 $$nemoclaw onboard +NEMOCLAW_TRACE_DIR=/tmp/nemoclaw-traces $$nemoclaw onboard +NEMOCLAW_TRACE_FILE=/tmp/nemoclaw-onboard-trace.json $$nemoclaw onboard ``` Trace artifacts include onboard phase timing, sandbox and dashboard readiness waits, policy application, inference validation probes, curl probe results, and sandbox build progress events. @@ -1880,10 +1880,10 @@ docker run --rm --name nemoclaw-jaeger \ -p 16686:16686 \ -p 4318:4318 \ jaegertracing/all-in-one:1.57 -NEMOCLAW_OPENCLAW_OTEL=1 nemoclaw onboard +NEMOCLAW_OPENCLAW_OTEL=1 $$nemoclaw onboard ``` -Onboarding automatically applies the `openclaw-diagnostics-otel-local` preset at sandbox create and again during the policy step when `NEMOCLAW_OPENCLAW_OTEL=1`, so OTLP export is allowed before the gateway's first trace flush. If you enabled OTEL after an existing sandbox was created, run `nemoclaw policy-add openclaw-diagnostics-otel-local --yes` or recreate the sandbox with OTEL enabled at build time. +Onboarding automatically applies the `openclaw-diagnostics-otel-local` preset at sandbox create and again during the policy step when `NEMOCLAW_OPENCLAW_OTEL=1`, so OTLP export is allowed before the gateway's first trace flush. If you enabled OTEL after an existing sandbox was created, run `$$nemoclaw policy-add openclaw-diagnostics-otel-local --yes` or recreate the sandbox with OTEL enabled at build time. Then open `http://localhost:16686` and select the `openclaw-gateway` service. The built-in `openclaw-diagnostics-otel-local` preset allows only `POST /v1/traces` (and subpaths) to `host.openshell.internal:4318` from `openclaw` and `node`. @@ -1897,12 +1897,12 @@ Defaults are sized for typical hardware; override only if you see false-positive | Variable | Default | Effect | |----------|---------|--------| | `NEMOCLAW_SANDBOX_EXEC_TIMEOUT_MS` | per call site (typically `15000`) | Overrides the default timeout for `openshell sandbox exec` calls issued by recovery and lifecycle helpers. Integer milliseconds; non-positive or non-numeric values fall back to the per-call-site default. | -| `NEMOCLAW_STATUS_PROBE_TIMEOUT_MS` | built-in default | Overrides the timeout for the OpenShell status probe used by `nemoclaw status`. Integer milliseconds; non-positive or non-numeric values fall back to the default. | +| `NEMOCLAW_STATUS_PROBE_TIMEOUT_MS` | built-in default | Overrides the timeout for the OpenShell status probe used by `$$nemoclaw status`. Integer milliseconds; non-positive or non-numeric values fall back to the default. | ### Onboard Timeouts The following environment variables tune onboard-time wall-clock limits. -Set them before running `nemoclaw onboard` if a slow connection or large model pull risks tripping the default. +Set them before running `$$nemoclaw onboard` if a slow connection or large model pull risks tripping the default. | Variable | Default | Purpose | |----------|---------|---------| @@ -1913,12 +1913,12 @@ Set them before running `nemoclaw onboard` if a slow connection or large model p ```bash export NEMOCLAW_OLLAMA_PULL_TIMEOUT=3600 export NEMOCLAW_SANDBOX_READY_TIMEOUT=600 -nemoclaw onboard +$$nemoclaw onboard ``` If a timeout fires, onboarding emits the elapsed budget plus a hint to raise the relevant variable. The Ollama pull preserves its partial download for the next attempt. -The readiness wait deletes the orphaned sandbox first so the next `nemoclaw onboard` starts clean. +The readiness wait deletes the orphaned sandbox first so the next `$$nemoclaw onboard` starts clean. ### Lifecycle Behavior Flags @@ -1926,15 +1926,15 @@ These flags change defaults for commands that manage existing sandboxes. | Variable | Format | Effect | |----------|--------|--------| -| `NEMOCLAW_CLEANUP_GATEWAY` | `1`, `true`, or `yes` to enable; `0`, `false`, or `no` to disable | Sets the default for whether `nemoclaw destroy` removes the shared gateway when destroying the last sandbox. Command-line `--cleanup-gateway` and `--no-cleanup-gateway` still take precedence. | -| `NEMOCLAW_DISABLE_INFERENCE_ROUTE_REPAIR` | `1` to enable | Skips the automatic DNS-proxy repair for stale `inference.local` routes during `nemoclaw connect` and `nemoclaw connect --probe-only`. Use only as a troubleshooting escape hatch. | +| `NEMOCLAW_CLEANUP_GATEWAY` | `1`, `true`, or `yes` to enable; `0`, `false`, or `no` to disable | Sets the default for whether `$$nemoclaw destroy` removes the shared gateway when destroying the last sandbox. Command-line `--cleanup-gateway` and `--no-cleanup-gateway` still take precedence. | +| `NEMOCLAW_DISABLE_INFERENCE_ROUTE_REPAIR` | `1` to enable | Skips the automatic DNS-proxy repair for stale `inference.local` routes during `$$nemoclaw connect` and `$$nemoclaw connect --probe-only`. Use only as a troubleshooting escape hatch. | | `NEMOCLAW_SHIELDS_ACCEPT_LEGACY_BASELINE` | `1` to opt in | Allows advanced immutable-config verification to trust the current on-disk bytes for older or partial content baselines. Use only after you have rebuilt or manually inspected the sandbox state and accepted that the baseline is operator-approved. | ### Remote Deployment -These variables seed defaults for `nemoclaw deploy` and `nemoclaw onboard --remote`, which provision a sandbox on a Brev instance. +These variables seed defaults for `$$nemoclaw deploy` and `$$nemoclaw onboard --remote`, which provision a sandbox on a Brev instance. Each has a flag equivalent on `deploy`; the env var lets non-interactive runs skip the prompt. -For narrative how-to coverage of `NEMOCLAW_BREV_PROVIDER` and `NEMOCLAW_GPU`, see [Deploy to Remote GPU](../deployment/deploy-to-remote-gpu.md). +For narrative how-to coverage of `NEMOCLAW_BREV_PROVIDER` and `NEMOCLAW_GPU`, see [Deploy to Remote GPU](../deployment/deploy-to-remote-gpu.mdx). | Variable | Default | Effect | |----------|---------|--------| @@ -1943,11 +1943,11 @@ For narrative how-to coverage of `NEMOCLAW_BREV_PROVIDER` and `NEMOCLAW_GPU`, se | `NEMOCLAW_DEPLOY_NO_CONNECT` | unset | When set to `1`, skips the automatic `connect` step after the remote deploy completes. | | `NEMOCLAW_DEPLOY_NO_START_SERVICES` | unset | When set to `1`, skips starting services automatically after the remote deploy. | -### Legacy `nemoclaw setup` +### Legacy `$$nemoclaw setup` -Deprecated. Use `nemoclaw onboard` instead. -Running `nemoclaw setup` now delegates directly to `nemoclaw onboard`. +Deprecated. Use `$$nemoclaw onboard` instead. +Running `$$nemoclaw setup` now delegates directly to `$$nemoclaw onboard`. ```bash -nemoclaw setup +$$nemoclaw setup ``` diff --git a/docs/reference/network-policies.mdx b/docs/reference/network-policies.mdx index d5060f8078..c89a752fee 100644 --- a/docs/reference/network-policies.mdx +++ b/docs/reference/network-policies.mdx @@ -81,7 +81,7 @@ Tier definitions are stored in `nemoclaw-blueprint/policies/tiers.yaml`. In non-interactive mode, set the tier with `NEMOCLAW_POLICY_TIER`: ```bash -NEMOCLAW_POLICY_TIER=open nemoclaw onboard --non-interactive --yes-i-accept-third-party-software +NEMOCLAW_POLICY_TIER=open $$nemoclaw onboard --non-interactive --yes-i-accept-third-party-software ``` If the value does not match a known tier, onboarding exits with an error listing the valid options. @@ -116,7 +116,7 @@ This opens a split tmux session with the TUI on the left and the agent on the ri Edit `nemoclaw-blueprint/policies/openclaw-sandbox.yaml` and re-run the onboard wizard: ```bash -nemoclaw onboard +$$nemoclaw onboard ``` ### Dynamic Changes diff --git a/docs/reference/troubleshooting.mdx b/docs/reference/troubleshooting.mdx index 9b63c34c3a..6d73904183 100644 --- a/docs/reference/troubleshooting.mdx +++ b/docs/reference/troubleshooting.mdx @@ -22,10 +22,10 @@ If your issue is not listed here, join the [NemoClaw Discord channel](https://di ## Installation -### `nemoclaw` not found after install +### `$$nemoclaw` not found after install If you use nvm or fnm to manage Node.js, the installer may not update your current shell's PATH. -The `nemoclaw` binary is installed but the shell session does not know where to find it. +The `$$nemoclaw` binary is installed but the shell session does not know where to find it. Run `source ~/.bashrc` (or `source ~/.zshrc` for zsh), or open a new terminal window. @@ -94,7 +94,7 @@ sudo usermod -aG docker $USER newgrp docker ``` -Then retry `nemoclaw onboard`. +Then retry `$$nemoclaw onboard`. If the installer stopped after printing `newgrp docker`, run that command and then re-run the installer: ```bash @@ -150,7 +150,7 @@ Some corporate networks block outbound UDP port 53 to public DNS servers and for NemoClaw's preflight runs a short `docker run --rm busybox nslookup nemoclaw-dns-probe-.invalid` probe before starting the sandbox build. The fresh `.invalid` name should return NXDOMAIN through a working resolver, so cached answers cannot hide blocked DNS egress. When the probe confirms a DNS failure, onboarding stops with platform-specific remediation instead of hanging for ~15 minutes and printing a cryptic `Exit handler never called`. -The fix depends on your platform and runtime. Pick the matching path from the preflight output, apply it, then re-run `nemoclaw onboard`. +The fix depends on your platform and runtime. Pick the matching path from the preflight output, apply it, then re-run `$$nemoclaw onboard`. - **Linux with systemd-resolved.** Add a `DNSStubListenerExtra` drop-in pointing at the docker bridge gateway IP (the preflight prints the detected IP), then add the same IP to `/etc/docker/daemon.json` under `dns`. Restart `systemd-resolved` and `docker`. - **macOS with Colima.** Restart Colima with the corporate DNS address, for example `colima stop && colima start --dns `. @@ -174,7 +174,7 @@ If all ports in that range are occupied, the error lists the owner for each port On macOS, the port check also tries a privileged `lsof` probe without prompting for a password so root-owned listeners are detected before the sandbox build starts. If a port becomes occupied after preflight but before `openshell forward start` runs, onboarding deletes the just-created sandbox and exits with a retry message instead of leaving a sandbox with an unreachable dashboard URL. -When a previous onboard, upgrade, or sandbox crash leaves a stale `openclaw-gateway` host process holding the dashboard port, `nemoclaw onboard --fresh`, `nemoclaw destroy` (when destroying the last sandbox), and `nemoclaw uninstall` automatically sweep the dashboard port range and signal `SIGTERM` then `SIGKILL` to recover. +When a previous onboard, upgrade, or sandbox crash leaves a stale `openclaw-gateway` host process holding the dashboard port, `$$nemoclaw onboard --fresh`, `$$nemoclaw destroy` (when destroying the last sandbox), and `$$nemoclaw uninstall` automatically sweep the dashboard port range and signal `SIGTERM` then `SIGKILL` to recover. The sweep only targets processes owned by the current user whose command line matches `openclaw-gateway` or `openshell forward` markers, and skips dashboard ports owned by other live sandboxes. If a non-NemoClaw process is already bound to the dashboard port or the gateway port, identify the conflicting process, verify it is safe to stop, and terminate it: @@ -191,19 +191,19 @@ Alternatively, override the conflicting port instead of stopping the other proce Pass `--control-ui-port` with the desired dashboard port: ```bash -nemoclaw onboard --control-ui-port 19000 +$$nemoclaw onboard --control-ui-port 19000 ``` You can also set `CHAT_UI_URL` with the desired port: ```bash -CHAT_UI_URL=http://127.0.0.1:19000 nemoclaw onboard +CHAT_UI_URL=http://127.0.0.1:19000 $$nemoclaw onboard ``` Or set the port directly: ```bash -NEMOCLAW_DASHBOARD_PORT=19000 nemoclaw onboard +NEMOCLAW_DASHBOARD_PORT=19000 $$nemoclaw onboard ``` For an OpenShell gateway port conflict, set `NEMOCLAW_GATEWAY_PORT` to a free @@ -211,13 +211,13 @@ non-privileged port that does not overlap NemoClaw's dashboard, vLLM, Ollama, or Ollama proxy ports: ```bash -NEMOCLAW_GATEWAY_PORT=8990 nemoclaw onboard +NEMOCLAW_GATEWAY_PORT=8990 $$nemoclaw onboard ``` Remote/headless hosts can bind the OpenShell gateway to all IPv4 interfaces: ```bash -NEMOCLAW_GATEWAY_BIND_ADDRESS=0.0.0.0 NEMOCLAW_GATEWAY_PORT=8990 nemoclaw onboard +NEMOCLAW_GATEWAY_BIND_ADDRESS=0.0.0.0 NEMOCLAW_GATEWAY_PORT=8990 $$nemoclaw onboard ``` Use `NEMOCLAW_GATEWAY_BIND_ADDRESS=0.0.0.0` only when other hosts on the @@ -234,9 +234,9 @@ If you onboard a second sandbox without overriding the port, onboarding uses the Assign a distinct port only when you want a specific value: ```bash -nemoclaw onboard # first sandbox uses default 18789 -nemoclaw onboard # second sandbox uses the next free port -nemoclaw onboard --control-ui-port 19000 # explicit port override +$$nemoclaw onboard # first sandbox uses default 18789 +$$nemoclaw onboard # second sandbox uses the next free port +$$nemoclaw onboard --control-ui-port 19000 # explicit port override ``` Each sandbox then has its own SSH tunnel and its own dashboard URL: @@ -250,10 +250,10 @@ You can verify which tunnel belongs to which sandbox with: ```bash openshell forward list -nemoclaw list +$$nemoclaw list ``` -`nemoclaw list` prints the recorded dashboard URL for each sandbox. +`$$nemoclaw list` prints the recorded dashboard URL for each sandbox. ## Onboarding @@ -265,7 +265,7 @@ Current OpenShell releases handle that behavior themselves, so NemoClaw no longe If onboarding reports that Docker is missing or unreachable, fix Docker first and retry onboarding: ```bash -nemoclaw onboard +$$nemoclaw onboard ``` Podman is not a tested runtime. @@ -311,14 +311,14 @@ If you prefer to disable the new Docker storage driver instead of running the pa } ``` -Then restart Docker (`sudo systemctl restart docker`) and re-run `nemoclaw onboard`. +Then restart Docker (`sudo systemctl restart docker`) and re-run `$$nemoclaw onboard`. This restores the legacy `overlay2` driver host-wide, which kills any other running containers — prefer the auto-fix unless you need the change for unrelated reasons. Switching storage drivers also rebuilds the entire local image graph: previously-pulled images become unusable and Docker re-pulls them on first reference, so expect a cold cache and additional disk usage right after the restart. ### OpenShell version above maximum Each NemoClaw release validates against a range of tested OpenShell versions. -If the installed OpenShell version exceeds the configured maximum, `nemoclaw onboard` exits with an error: +If the installed OpenShell version exceeds the configured maximum, `$$nemoclaw onboard` exits with an error: ```text ✗ openshell is above the maximum supported by this NemoClaw release. @@ -332,7 +332,7 @@ If GitHub release metadata is unavailable, the script uses its bundled fallback ### Sandbox containers cannot reach the gateway -On native Linux Docker-driver hosts, `nemoclaw onboard` verifies the route that sandbox containers use to reach the OpenShell gateway. +On native Linux Docker-driver hosts, `$$nemoclaw onboard` verifies the route that sandbox containers use to reach the OpenShell gateway. If a host firewall blocks that path, onboarding exits with output like: ```text @@ -346,23 +346,23 @@ If the message does not include a subnet, derive it from the OpenShell Docker ne ```bash SUBNET=$(docker network inspect openshell-docker --format '{{(index .IPAM.Config 0).Subnet}}') sudo ufw allow from "$SUBNET" to any port 8080 proto tcp -nemoclaw onboard +$$nemoclaw onboard ``` ### `connect` exits because the gateway is down -`nemoclaw connect` checks the OpenShell gateway before it tries dashboard forwarding, SSH, or inference repair. +`$$nemoclaw connect` checks the OpenShell gateway before it tries dashboard forwarding, SSH, or inference repair. If the gateway is not reachable, the command exits early and prints recovery guidance. Start the gateway or resume onboarding, then retry: ```bash openshell gateway start --name nemoclaw -nemoclaw onboard --resume -nemoclaw connect +$$nemoclaw onboard --resume +$$nemoclaw connect ``` -Run `nemoclaw status` for a broader gateway health report. +Run `$$nemoclaw status` for a broader gateway health report. ### Invalid sandbox name @@ -381,7 +381,7 @@ Choose a name such as `my-assistant` or `dev1`. On DGX machines, sandbox creation can fail if the gateway's DNS has not finished propagating or if a stale port forward from a previous onboard run is still active. -Run `nemoclaw onboard` to retry. +Run `$$nemoclaw onboard` to retry. The wizard cleans up stale port forwards and waits for gateway readiness automatically. ### GPU setup fails with a placeholder GPU name @@ -422,7 +422,7 @@ colima start --cpu 6 --memory 12 --disk 100 On Docker Desktop, raise CPU and memory limits in *Settings → Resources*, then apply and restart. -To silence the warning when the host is intentionally small, set `NEMOCLAW_IGNORE_RUNTIME_RESOURCES=1` before running `nemoclaw onboard`. +To silence the warning when the host is intentionally small, set `NEMOCLAW_IGNORE_RUNTIME_RESOURCES=1` before running `$$nemoclaw onboard`. ### Re-onboard fails because port 18789 is held by SSH @@ -441,11 +441,11 @@ sudo lsof -i :18789 kill ``` -Then re-run `nemoclaw onboard`. +Then re-run `$$nemoclaw onboard`. ### Updated messaging token is not picked up -Re-running `nemoclaw onboard --non-interactive` with a new +Re-running `$$nemoclaw onboard --non-interactive` with a new `TELEGRAM_BOT_TOKEN`, `DISCORD_BOT_TOKEN`, or `SLACK_BOT_TOKEN` previously reported success while the sandbox kept polling with the old credential. Current NemoClaw stores SHA-256 hashes of messaging credentials in the @@ -458,7 +458,7 @@ If you suspect a sandbox is still using a stale token, re-run onboarding so the credential check runs: ```bash -nemoclaw onboard --non-interactive +$$nemoclaw onboard --non-interactive ``` ### Sandbox creation killed by OOM (exit 137) @@ -466,7 +466,7 @@ nemoclaw onboard --non-interactive On systems with 8 GB RAM or less and no swap configured, the sandbox image push can exhaust available memory and get killed by the Linux OOM killer (exit code 137). NemoClaw automatically detects low memory during onboarding and prompts to create a 4 GB swap file. -If this automatic step fails or you are using a custom setup flow, create swap manually before running `nemoclaw onboard`: +If this automatic step fails or you are using a custom setup flow, create swap manually before running `$$nemoclaw onboard`: ```bash sudo dd if=/dev/zero of=/swapfile bs=1M count=4096 status=none @@ -474,12 +474,12 @@ sudo chmod 600 /swapfile sudo mkswap /swapfile sudo swapon /swapfile echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab -nemoclaw onboard +$$nemoclaw onboard ``` ### Previous onboarding session failed -If a previous `nemoclaw onboard` attempt fails partway through (for example, a provider or inference-setup step reporting an error), NemoClaw records the failure in `~/.nemoclaw/onboard-session.json`. +If a previous `$$nemoclaw onboard` attempt fails partway through (for example, a provider or inference-setup step reporting an error), NemoClaw records the failure in `~/.nemoclaw/onboard-session.json`. When you re-run the installer, it detects the failed session and does not silently retry it. Silent retry would loop on the same failure if your original choice, such as an unreachable provider, was the cause. @@ -506,7 +506,7 @@ Silent retry would loop on the same failure if your original choice, such as an This is only useful if the original failure was transient, for example a network blip or a stopped Docker daemon, and not a wrong provider choice: ```bash - nemoclaw onboard --resume + $$nemoclaw onboard --resume ``` As a last resort, you can also delete the session file directly and re-run the installer: @@ -548,60 +548,60 @@ Follow these steps to reconnect. 1. Reconnect. ```bash - nemoclaw connect + $$nemoclaw connect ``` The gateway usually rotates its SSH host keys across a reboot. `connect` detects the resulting identity drift, prunes the stale `openshell-*` entries from `~/.ssh/known_hosts`, and retries automatically. - You do not need to edit `known_hosts` by hand or re-run `nemoclaw onboard` in this case. + You do not need to edit `known_hosts` by hand or re-run `$$nemoclaw onboard` in this case. 1. Start host auxiliary services (if needed). - If you use the cloudflared tunnel started by `nemoclaw tunnel start`, start it again: + If you use the cloudflared tunnel started by `$$nemoclaw tunnel start`, start it again: ```bash - nemoclaw tunnel start + $$nemoclaw tunnel start ``` - OpenShell-managed channel messaging handles Telegram, Discord, Slack, WeChat, and WhatsApp at onboarding, not through a separate bridge process from `nemoclaw tunnel start`. + OpenShell-managed channel messaging handles Telegram, Discord, Slack, WeChat, and WhatsApp at onboarding, not through a separate bridge process from `$$nemoclaw tunnel start`. WeChat and WhatsApp are experimental. - To pause a single bridge without destroying the sandbox, use `nemoclaw channels stop `. + To pause a single bridge without destroying the sandbox, use `$$nemoclaw channels stop `. -If the sandbox remains missing after restarting the gateway, run `nemoclaw onboard` to recreate it. +If the sandbox remains missing after restarting the gateway, run `$$nemoclaw onboard` to recreate it. The wizard prompts for confirmation before destroying an existing sandbox. If you confirm, it **destroys and recreates** the sandbox. Workspace files (SOUL.md, USER.md, IDENTITY.md, AGENTS.md, MEMORY.md, and daily memory notes) are lost. Back up your workspace first by following the instructions at [Back Up and Restore](../manage-sandboxes/backup-restore). ### Sandbox is running an outdated agent version -After upgrading NemoClaw, `nemoclaw connect` and `nemoclaw status` warn if the sandbox is running an older agent version than the current image. +After upgrading NemoClaw, `$$nemoclaw connect` and `$$nemoclaw status` warn if the sandbox is running an older agent version than the current image. To upgrade the sandbox while preserving workspace state, run: ```bash -nemoclaw rebuild +$$nemoclaw rebuild ``` The rebuild command backs up state, destroys the old sandbox, recreates it with the current image, and restores state. Create a snapshot before rebuilding if you want an additional safety net: ```bash -nemoclaw snapshot create -nemoclaw rebuild +$$nemoclaw snapshot create +$$nemoclaw rebuild ``` ### Sandbox shows as stopped The sandbox may have been stopped or deleted. -Run `nemoclaw onboard` to recreate the sandbox from the same blueprint and policy definitions. +Run `$$nemoclaw onboard` to recreate the sandbox from the same blueprint and policy definitions. ### Sandbox is registered locally but missing from the gateway After a gateway restart, host reboot, or manual OpenShell cleanup, NemoClaw may still have a local registry entry for a sandbox that the live gateway no longer lists. -`nemoclaw status` and `nemoclaw connect` preserve that local registry entry and print recovery guidance instead of deleting it automatically. -Run `nemoclaw rebuild --yes` when you want NemoClaw to recreate the sandbox from the recorded metadata, or run `nemoclaw destroy` when you intentionally want to remove the stale entry. +`$$nemoclaw status` and `$$nemoclaw connect` preserve that local registry entry and print recovery guidance instead of deleting it automatically. +Run `$$nemoclaw rebuild --yes` when you want NemoClaw to recreate the sandbox from the recorded metadata, or run `$$nemoclaw destroy` when you intentionally want to remove the stale entry. ### Status shows "not running" inside the sandbox @@ -614,7 +614,7 @@ Run `openshell sandbox list` on the host to check the underlying sandbox state. ### Git clone fails with a certificate verification error In networks that inspect TLS, OpenShell injects a proxy CA bundle into the sandbox. -Current NemoClaw exports that bundle as `GIT_SSL_CAINFO` during sandbox startup and persists it for `nemoclaw connect` sessions, so Git can trust the proxy CA. +Current NemoClaw exports that bundle as `GIT_SSL_CAINFO` during sandbox startup and persists it for `$$nemoclaw connect` sessions, so Git can trust the proxy CA. It also forwards standard CA bundle variables for subprocesses, including `GIT_SSL_CAPATH`, `CURL_CA_BUNDLE`, and `REQUESTS_CA_BUNDLE`. If Git still reports `server certificate verification failed`, reconnect to the sandbox and check that the CA variables are present: @@ -626,7 +626,7 @@ env | grep -E 'SSL_CERT_FILE|GIT_SSL_CAINFO|CURL_CA_BUNDLE|REQUESTS_CA_BUNDLE' If they are missing on an older sandbox, upgrade NemoClaw and run: ```bash -nemoclaw rebuild +$$nemoclaw rebuild ``` ### Sandbox creation reports a TLS certificate mismatch @@ -636,7 +636,7 @@ Refresh the gateway trust and then resume onboarding: ```bash openshell gateway trust -g nemoclaw -nemoclaw onboard --resume +$$nemoclaw onboard --resume ``` ### `openclaw update` hangs or times out inside the sandbox @@ -649,7 +649,7 @@ Instead: 1. Upgrade to a NemoClaw release that includes the newer `openclaw` version. 2. If you build NemoClaw from source, bump the pinned `openclaw` version in `Dockerfile.base` and rebuild the sandbox base image. -3. Run `nemoclaw rebuild` to recreate the sandbox with the updated image. The rebuild command automatically backs up workspace state before destroying the old sandbox and restores it afterward. +3. Run `$$nemoclaw rebuild` to recreate the sandbox with the updated image. The rebuild command automatically backs up workspace state before destroying the old sandbox and restores it afterward. ### Inference requests time out @@ -657,10 +657,10 @@ Verify that the inference provider endpoint is reachable from the host. Check the active provider and endpoint: ```bash -nemoclaw status +$$nemoclaw status ``` -For local Ollama and local vLLM, `nemoclaw status` also prints an `Inference` line that probes the host-side health endpoint directly. +For local Ollama and local vLLM, `$$nemoclaw status` also prints an `Inference` line that probes the host-side health endpoint directly. If that line shows `unreachable`, start the local backend first and then retry the request. For Local Ollama, current releases also print `Inference (auth proxy)` when a proxy token is available. If the backend is healthy but the auth proxy is `unauthorized` or `unreachable`, re-run onboarding so NemoClaw can recreate the proxy token, restart the proxy, and refresh the route. @@ -678,7 +678,7 @@ If large prompts still cause timeouts, increase it with `NEMOCLAW_LOCAL_INFERENC ```bash export NEMOCLAW_LOCAL_INFERENCE_TIMEOUT=300 -nemoclaw onboard +$$nemoclaw onboard ``` For local Ollama and vLLM, onboarding retries the container reachability check and can fall back to the host-side health check when the local backend is healthy. @@ -707,16 +707,16 @@ Raise the budget before re-running onboard: ```bash export NEMOCLAW_SANDBOX_READY_TIMEOUT=600 -nemoclaw onboard +$$nemoclaw onboard ``` The variable accepts seconds and applies to the readiness wait only. -When the deadline expires, NemoClaw deletes the partially-created sandbox before printing the retry hint, so the next `nemoclaw onboard` starts from a clean state. +When the deadline expires, NemoClaw deletes the partially-created sandbox before printing the retry hint, so the next `$$nemoclaw onboard` starts from a clean state. If readiness still fails after the extended budget, inspect the gateway and sandbox status: ```bash openshell sandbox list -nemoclaw status +$$nemoclaw status ``` ### Agent fails at runtime after onboarding succeeds with a compatible endpoint @@ -733,7 +733,7 @@ If you onboarded an older release that selected `/v1/responses`, re-run onboarding so the wizard rebuilds the image with chat completions: ```bash -nemoclaw onboard +$$nemoclaw onboard ``` If you previously set `NEMOCLAW_PREFERRED_API=openai-responses` to force the @@ -745,7 +745,7 @@ If that smoke check fails, fix the compatible-endpoint base URL, credentials, mo Do not rely on `NEMOCLAW_INFERENCE_API_OVERRIDE` alone — it patches the config at container startup but does not update the Dockerfile ARG baked into the image. -A fresh `nemoclaw onboard` is the reliable fix. +A fresh `$$nemoclaw onboard` is the reliable fix. ### `NEMOCLAW_DISABLE_DEVICE_AUTH=1` does not change an existing sandbox @@ -766,31 +766,31 @@ On the next sandbox startup, NemoClaw restores `openclaw.json` from OpenClaw's l If the sandbox still cannot start or reports that no baseline is available, rebuild it from the host: ```bash -nemoclaw rebuild +$$nemoclaw rebuild ``` ### `openclaw channels add` or `remove` is blocked inside the sandbox This is expected. -The messaging channel list is frozen into the sandbox's container image when the image is built during `nemoclaw onboard` or `nemoclaw rebuild` (the selected channel names are passed to the `docker build` as `NEMOCLAW_MESSAGING_CHANNELS_B64` and written into agent config such as `/sandbox/.openclaw/openclaw.json` for OpenClaw or `/sandbox/.hermes/.env` for Hermes). +The messaging channel list is frozen into the sandbox's container image when the image is built during `$$nemoclaw onboard` or `$$nemoclaw rebuild` (the selected channel names are passed to the `docker build` as `NEMOCLAW_MESSAGING_CHANNELS_B64` and written into agent config such as `/sandbox/.openclaw/openclaw.json` for OpenClaw or `/sandbox/.hermes/.env` for Hermes). Changes made inside the running sandbox do not persist across rebuilds, so `openclaw channels` commands that mutate the config are intercepted. NemoClaw's sandbox entrypoint installs a guard that intercepts `openclaw channels ` and prints an actionable error pointing at the host-side commands below, instead of letting the call fail deep in the binary with a raw `EACCES` trace. Run the equivalent host-side command instead: ```bash -nemoclaw channels list -nemoclaw channels add -nemoclaw channels remove +$$nemoclaw channels list +$$nemoclaw channels add +$$nemoclaw channels remove ``` `channels add` registers credentials with the OpenShell gateway and `channels remove` clears them. Both offer to rebuild the sandbox so the image reflects the new channel set. -In non-interactive mode (`NEMOCLAW_NON_INTERACTIVE=1`), the commands stage the change and leave the rebuild to a follow-up `nemoclaw rebuild`. +In non-interactive mode (`NEMOCLAW_NON_INTERACTIVE=1`), the commands stage the change and leave the rebuild to a follow-up `$$nemoclaw rebuild`. WeChat and WhatsApp are experimental. Review [Messaging Channels](../manage-sandboxes/messaging-channels) before enabling them. -WeChat captures its bot token through a host-side QR scan during `nemoclaw onboard` or `channels add wechat`. +WeChat captures its bot token through a host-side QR scan during `$$nemoclaw onboard` or `channels add wechat`. You scan the iLink QR from WeChat on your phone and NemoClaw registers the captured token with the OpenShell gateway. WhatsApp pairs entirely inside the sandbox. @@ -824,16 +824,16 @@ NemoClaw's sandbox entrypoint installs a guard that intercepts `openclaw config For most configuration changes, exit the sandbox and rerun onboarding: ```bash -nemoclaw onboard +$$nemoclaw onboard ``` -If NemoClaw reports a resumable failed onboarding session, run `nemoclaw onboard --resume` instead. +If NemoClaw reports a resumable failed onboarding session, run `$$nemoclaw onboard --resume` instead. This rebuilds the sandbox with your updated settings. For advanced live edits, use the host-side config command instead of running `openclaw config set` inside the sandbox: ```bash -nemoclaw config set --key --value '' --restart +$$nemoclaw config set --key --value '' --restart ``` Host-side `config set` validates any HTTP or HTTPS URLs in the new value, including URLs nested inside JSON objects or arrays. NemoClaw rejects loopback, private, reserved, and internal hosts; DNS names must resolve successfully and must not resolve to private/internal addresses. HTTP URLs are written with the validated IP address pinned to reduce DNS-rebinding risk. Avoid putting credentials in config values; rotate provider credentials with the credential-management commands instead. @@ -930,7 +930,7 @@ Check the gateway logs and blocked-request output with `openshell term`, and loo ### Messaging bridge appears running but no messages arrive -Bot tokens for Telegram (`getUpdates`), Discord (gateway), and Slack (Socket Mode) only allow one active consumer per token. If two NemoClaw sandboxes are configured with the same bot token, each one kicks the other off its polling connection and neither delivers messages. `nemoclaw status` still reports the bridge as running because the gateway process itself is alive. +Bot tokens for Telegram (`getUpdates`), Discord (gateway), and Slack (Socket Mode) only allow one active consumer per token. If two NemoClaw sandboxes are configured with the same bot token, each one kicks the other off its polling connection and neither delivers messages. `$$nemoclaw status` still reports the bridge as running because the gateway process itself is alive. For Telegram group chats, first check BotFather privacy mode. New Telegram bots default to privacy mode enabled, which prevents group messages from reaching `getUpdates` even when the user mentions the bot. @@ -948,7 +948,7 @@ The check waits for `[telegram] [default] inbound update received` and `[telegra To diagnose, open a shell in the sandbox and inspect the gateway log: ```bash -nemoclaw connect +$$nemoclaw connect tail -f /tmp/gateway.log ``` @@ -958,7 +958,7 @@ A repeating line like the following confirms the conflict: [telegram] getUpdates conflict: 409: Conflict: terminated by other getUpdates request; retrying in 30s. ``` -To fix, run `nemoclaw destroy` on whichever sandbox should stop polling, or rerun onboarding on it with the channel disabled. Current NemoClaw warns at `nemoclaw onboard` time when another sandbox already has the same channel enabled, but sandboxes created before that check was added may still be in a conflict loop. +To fix, run `$$nemoclaw destroy` on whichever sandbox should stop polling, or rerun onboarding on it with the channel disabled. Current NemoClaw warns at `$$nemoclaw onboard` time when another sandbox already has the same channel enabled, but sandboxes created before that check was added may still be in a conflict loop. ### Landlock filesystem restrictions silently degraded @@ -977,8 +977,8 @@ For full filesystem enforcement, run on a Linux kernel 5.13 or later (Ubuntu 22. ### Sandbox lost after gateway restart Sandboxes created with OpenShell versions older than 0.0.24 can become unreachable after a gateway restart because SSH secrets were not persisted. -Running `nemoclaw onboard` automatically upgrades OpenShell to 0.0.24 or later during the preflight check. -After the upgrade, recreate the sandbox with `nemoclaw onboard`. +Running `$$nemoclaw onboard` automatically upgrades OpenShell to 0.0.24 or later during the preflight check. +After the upgrade, recreate the sandbox with `$$nemoclaw onboard`. ### Agent cannot reach external hosts through a proxy @@ -988,11 +988,11 @@ If your environment uses a different proxy, set `NEMOCLAW_PROXY_HOST` and `NEMOC ```bash export NEMOCLAW_PROXY_HOST=proxy.example.com export NEMOCLAW_PROXY_PORT=8080 -nemoclaw onboard +$$nemoclaw onboard ``` These are build-time settings baked into the sandbox image. -Changing them after onboarding requires re-running `nemoclaw onboard` to rebuild the image. +Changing them after onboarding requires re-running `$$nemoclaw onboard` to rebuild the image. When `HTTP_PROXY` or `HTTPS_PROXY` is set on the host, NemoClaw adds `localhost` and `127.0.0.1` to `NO_PROXY` for managed subprocesses. This keeps local Ollama health checks and model pulls from being routed through a corporate or desktop proxy while preserving the proxy for external hosts. @@ -1000,7 +1000,7 @@ This keeps local Ollama health checks and model pulls from being routed through ### Agent cannot reach a host-side HTTP service When a sandbox needs to call an HTTP service running on the host, use the normal OpenShell network policy path. -Expose the service on a host IP address that the OpenShell gateway can reach, create a custom NemoClaw policy preset for that IP and port, and apply it with `nemoclaw policy-add --from-file`. +Expose the service on a host IP address that the OpenShell gateway can reach, create a custom NemoClaw policy preset for that IP and port, and apply it with `$$nemoclaw policy-add --from-file`. The sandbox request then flows through the OpenShell proxy while NemoClaw preserves the existing live policy entries. Do not rely on `host.docker.internal` or `host.openshell.internal` as a general-purpose host-service path. @@ -1039,7 +1039,7 @@ network_policies: Apply the preset to the running sandbox with the NemoClaw CLI: ```bash -nemoclaw my-assistant policy-add --from-file ./host-memory-api.yaml +$$nemoclaw my-assistant policy-add --from-file ./host-memory-api.yaml ``` After you apply the policy, retry the request from inside the sandbox without disabling the proxy: @@ -1067,7 +1067,7 @@ Refer to [Customize the Network Policy](../network-policy/customize-network-poli ### Dashboard not reachable after setting a custom port -If you ran `nemoclaw onboard` with a custom dashboard port and onboarding completed +If you ran `$$nemoclaw onboard` with a custom dashboard port and onboarding completed but the dashboard URL is unreachable (browser shows connection refused or the page fails to load), the sandbox was most likely created with an older NemoClaw version that did not pass the dashboard port into the sandbox at startup. The gateway inside the sandbox @@ -1078,7 +1078,7 @@ Re-run onboarding on the current NemoClaw release with the desired port. Current derive the dashboard port from `CHAT_UI_URL` automatically and inject it into the sandbox: ```bash -CHAT_UI_URL=http://127.0.0.1:19000 nemoclaw onboard +CHAT_UI_URL=http://127.0.0.1:19000 $$nemoclaw onboard ``` If you need to run multiple sandboxes at different ports at the same time, see @@ -1097,14 +1097,14 @@ Check whether the proxy port is occupied by another process: sudo lsof -i :11435 ``` -Stop the conflicting process and re-run `nemoclaw onboard`. +Stop the conflicting process and re-run `$$nemoclaw onboard`. The wizard cleans up stale proxy processes from previous runs automatically, so most failures resolve by retrying. The proxy token is persisted to `~/.nemoclaw/ollama-proxy-token` with `0600` permissions. If the file is missing or unreadable after a host reboot, re-running -`nemoclaw onboard` regenerates it. +`$$nemoclaw onboard` regenerates it. ### Ollama auth proxy is unreachable from the sandbox @@ -1122,7 +1122,7 @@ If the message does not include a subnet, derive it from the OpenShell Docker ne ```bash SUBNET=$(docker network inspect openshell-docker --format '{{(index .IPAM.Config 0).Subnet}}') sudo ufw allow from "$SUBNET" to any port 11435 proto tcp -nemoclaw onboard +$$nemoclaw onboard ``` Docker Desktop, WSL, and hosts without the OpenShell Docker network use different routing models. @@ -1170,7 +1170,7 @@ binds an IPv4 address and not only `::1`. View the error output for the failed blueprint run: ```bash -nemoclaw logs +$$nemoclaw logs ``` Use `--follow` to stream logs in real time while debugging. @@ -1193,7 +1193,7 @@ Remove the gateway registration, stop any leftover host gateway process, then re ```bash openshell gateway remove nemoclaw sudo pkill -f openshell-gateway -nemoclaw onboard --resume +$$nemoclaw onboard --resume ``` ### GPU passthrough on Spark @@ -1210,7 +1210,7 @@ When shared gateway cleanup would be unsafe, follow the targeted destroy or gate Recent NVIDIA Container Toolkit installs configure the Docker daemon for Container Device Interface (CDI) device injection, which OpenShell's `gateway start --gpu` then auto-selects. If no `nvidia.com/gpu` CDI spec has been generated on the host yet, gateway start fails with `Docker responded with status code 500: CDI device injection failed: unresolvable CDI devices nvidia.com/gpu=all`. The standard NemoClaw installer detects this gap before onboarding, first tries to enable the NVIDIA CDI refresh systemd units, and falls back to generating the spec directly with `nvidia-ctk`. -If you run `nemoclaw onboard` directly, preflight prints the manual remediation instead. +If you run `$$nemoclaw onboard` directly, preflight prints the manual remediation instead. The native Linux fix is the same on Docker hosts whose `docker info` advertises a non-empty `CDISpecDirs`. On WSL with Docker Desktop, Docker may advertise CDI directories even though `--device nvidia.com/gpu=all` is not usable from the WSL distro. For that runtime, NemoClaw skips Linux CDI repair and uses Docker's `--gpus` compatibility path for sandbox GPU access. @@ -1221,7 +1221,7 @@ Enable the refresh units, verify they list `nvidia.com/gpu` entries, then rerun ```bash sudo systemctl enable --now nvidia-cdi-refresh.path nvidia-cdi-refresh.service nvidia-ctk cdi list -nemoclaw onboard +$$nemoclaw onboard ``` If the refresh units are unavailable or do not generate CDI devices, generate the spec directly: @@ -1285,7 +1285,7 @@ If you run other services on Spark that expect port 3000, bind them to a differe ## Windows Subsystem for Linux -For environment setup steps, see [Windows Prerequisites](../get-started/prerequisites/windows-preparation). +For environment setup steps, see [Windows Prerequisites](../get-started/windows-preparation.mdx). ### `wsl --install --no-distribution` returns Forbidden (403) @@ -1359,7 +1359,7 @@ sudo systemctl stop ollama OLLAMA_CONTEXT_LENGTH=16384 ollama serve ``` -For additional troubleshooting, see the [Quickstart](../get-started/quickstart) and [Windows Setup](../get-started/prerequisites/windows-preparation) pages. +For additional troubleshooting, see the [Quickstart](../get-started/quickstart.mdx) and [Windows Setup](../get-started/windows-preparation.mdx) pages. ## Podman @@ -1386,11 +1386,11 @@ Skills that require macOS-only binaries cannot be enabled on Brev. Skills that require additional CLI binaries require a custom sandbox image rebuild. For credentials, use the supported host-side setup flow. -Re-run onboarding for inference or Brave Search credentials, or use `nemoclaw channels add ` for messaging channels. +Re-run onboarding for inference or Brave Search credentials, or use `$$nemoclaw channels add ` for messaging channels. To add a binary to the sandbox image, update the sandbox `Dockerfile.base` to install the required package, then rebuild: ```bash -nemoclaw rebuild +$$nemoclaw rebuild ``` After the rebuild completes, return to the Skills page to confirm the skill status has changed from `blocked` to `ready`. @@ -1408,7 +1408,7 @@ In the default sandbox state, `openclaw.json` is writable by the sandbox user. If you see this error, use the host-side config command instead: ```bash -nemoclaw config set --key --value '' --restart +$$nemoclaw config set --key --value '' --restart ``` Refer to [Commands](commands) for the full list of supported configuration keys. @@ -1423,7 +1423,7 @@ The agent may still respond on messaging channels such as Telegram or Slack whil Take a snapshot before running onboard to protect your workspace files. ```bash -nemoclaw snapshot create +$$nemoclaw snapshot create ``` @@ -1431,7 +1431,7 @@ nemoclaw snapshot create Re-run onboarding to restore dashboard connectivity: ```bash -nemoclaw onboard +$$nemoclaw onboard ``` Depending on current sandbox state, onboarding may prompt before recreating resources. @@ -1445,7 +1445,7 @@ Installing packages on the Brev host does not make them available inside the san To install a skill dependency, add it to the sandbox image and rebuild: ```bash -nemoclaw rebuild +$$nemoclaw rebuild ``` After the rebuild completes, return to the Skills page to confirm the skill is ready. @@ -1453,7 +1453,7 @@ After the rebuild completes, return to the Skills page to confirm the skill is r ## Hermes The issues below are common problems you may encounter when running Hermes through `nemohermes`. -For setup, refer to [Quickstart with Hermes](../../hermes/get-started/quickstart-hermes). +For setup, refer to [Quickstart with Hermes](../get-started/quickstart-hermes.mdx). ### Port 8642 in a browser shows a blank page or `Cannot GET /` @@ -1485,14 +1485,14 @@ Pick a distinct sandbox name (the Hermes default is `hermes`; a common pattern i To convert an existing sandbox to Hermes instead, destroy and re-onboard: ```console -$ nemoclaw destroy +$ $$nemoclaw destroy $ NEMOCLAW_AGENT=hermes nemohermes onboard ``` ### `nemohermes: command not found` immediately after install -`nemohermes` is a thin shim installed alongside `nemoclaw` that pre-selects the Hermes agent. -The installer drops the shim in the same directory as `nemoclaw`; if `nemoclaw` is on `PATH` but `nemohermes` is not, the shim symlink was skipped. +`nemohermes` is a thin shim installed alongside `$$nemoclaw` that pre-selects the Hermes agent. +The installer drops the shim in the same directory as `$$nemoclaw`; if `$$nemoclaw` is on `PATH` but `nemohermes` is not, the shim symlink was skipped. Verify the install: @@ -1501,7 +1501,7 @@ $ command -v nemoclaw $ command -v nemohermes ``` -If only `nemoclaw` resolves, re-run the installer with `NEMOCLAW_AGENT=hermes` set so the shim is published: +If only `$$nemoclaw` resolves, re-run the installer with `NEMOCLAW_AGENT=hermes` set so the shim is published: ```console $ export NEMOCLAW_AGENT=hermes @@ -1550,7 +1550,7 @@ Reset a specific provider's credentials with `nemohermes credentials reset -When you provide a provider credential, either interactively during `nemoclaw onboard` or through an environment variable, NemoClaw holds the value in memory only long enough to register it with the OpenShell gateway through `openshell provider create` or `openshell provider update`. - - -When you provide a provider credential, either interactively during `nemohermes onboard` or through an environment variable, NemoClaw holds the value in memory only long enough to register it with the OpenShell gateway through `openshell provider create` or `openshell provider update`. - +When you provide a provider credential, either interactively during `$$nemoclaw onboard` or through an environment variable, NemoClaw holds the value in memory only long enough to register it with the OpenShell gateway through `openshell provider create` or `openshell provider update`. The gateway stores the credential and the OpenShell L7 proxy substitutes it into outbound requests at egress, so sandboxed agents see placeholders instead of the raw secret. @@ -40,16 +35,9 @@ openshell provider list Or, equivalently, through NemoClaw: - ```bash -nemoclaw credentials list +$$nemoclaw credentials list ``` - - -```bash -nemohermes credentials list -``` - Both commands show the provider names registered with the gateway. The values themselves cannot be read back from the CLI; this is a deliberate property of OpenShell. @@ -62,34 +50,23 @@ That directory is created with mode `0700` and contains no credential material. When a NemoClaw command needs a credential value during a single run (for example to forward it to an `openshell provider` registration), it reads from `process.env` first. This means you can: - - -- Prefix any command with the credential to override the gateway-stored value: `NVIDIA_API_KEY=nvapi-... nemoclaw onboard` +- Prefix any command with the credential to override the gateway-stored value: `NVIDIA_API_KEY=nvapi-... $$nemoclaw onboard` - Use short-lived or rotated credentials in CI by exporting them once per pipeline run - Avoid registering credentials in the gateway entirely if your environment supplies them - - - -- Prefix any command with the credential to override the gateway-stored value: `NVIDIA_API_KEY=nvapi-... nemohermes onboard` -- Use short-lived or rotated credentials in CI by exporting them once per pipeline run -- Avoid registering credentials in the gateway entirely if your environment supplies them - - - ## Deploy Reads from Environment Only -`nemoclaw deploy` (which provisions a remote Brev box) cannot read secrets back from the gateway, so it requires every credential to be present in the host environment at invocation time. +`$$nemoclaw deploy` (which provisions a remote Brev box) cannot read secrets back from the gateway, so it requires every credential to be present in the host environment at invocation time. A typical deploy invocation looks like: ```bash NVIDIA_API_KEY=nvapi-... \ HF_TOKEN=hf_... \ TELEGRAM_BOT_TOKEN=... \ - nemoclaw deploy my-instance + $$nemoclaw deploy my-instance ``` -For remote vLLM or Hugging Face workflows that need gated model access, `nemoclaw deploy` also forwards `HF_TOKEN` and `HUGGING_FACE_HUB_TOKEN` to the VM when either variable is present. +For remote vLLM or Hugging Face workflows that need gated model access, `$$nemoclaw deploy` also forwards `HF_TOKEN` and `HUGGING_FACE_HUB_TOKEN` to the VM when either variable is present. If a required credential is missing the deploy aborts before any remote work begins. ## GitHub Tokens @@ -108,12 +85,7 @@ Run `gh auth login` if you want a persistent backing store (whichever one applie ## Migration From Earlier Releases Earlier NemoClaw releases stored credentials as plaintext JSON in `~/.nemoclaw/credentials.json` with mode `0600`. - -On first `nemoclaw onboard` after upgrading, NemoClaw automatically: - - -On first `nemohermes onboard` after upgrading, NemoClaw automatically: - +On first `$$nemoclaw onboard` after upgrading, NemoClaw automatically: 1. Reads the legacy file. 2. Stages allowlisted credential values into `process.env` for the rest of the run. @@ -122,47 +94,23 @@ On first `nemohermes onboard` after upgrading, NemoClaw automatically: You will see a one-line stderr notice the first time this happens. Credential lookup paths such as rebuild also stage allowlisted legacy values so interrupted upgrades can keep working, but those staging-only paths do not delete the plaintext file because they cannot prove every legacy value was registered with the gateway. - -If `~/.nemoclaw/credentials.json` remains after a rebuild or other credential lookup, run `nemoclaw onboard` to complete the verified gateway migration and cleanup. - - -If `~/.nemoclaw/credentials.json` remains after a rebuild or other credential lookup, run `nemohermes onboard` to complete the verified gateway migration and cleanup. - +If `~/.nemoclaw/credentials.json` remains after a rebuild or other credential lookup, run `$$nemoclaw onboard` to complete the verified gateway migration and cleanup. ## Rotate or Remove a Stored Credential The simplest way to replace a stored value is to rerun onboarding with the new value in your environment: - -```bash -NVIDIA_API_KEY=nvapi-new-value nemoclaw onboard -``` - - ```bash -NVIDIA_API_KEY=nvapi-new-value nemohermes onboard +NVIDIA_API_KEY=nvapi-new-value $$nemoclaw onboard ``` - To remove a credential from the gateway entirely: - -```bash -nemoclaw credentials reset -``` - - ```bash -nemohermes credentials reset +$$nemoclaw credentials reset ``` - - -`` is the OpenShell provider name (run `nemoclaw credentials list` first if you are not sure). - - -`` is the OpenShell provider name (run `nemohermes credentials list` first if you are not sure). - +`` is the OpenShell provider name (run `$$nemoclaw credentials list` first if you are not sure). On the next run NemoClaw prompts again unless the credential is supplied through the environment. ## Security Recommendations diff --git a/scripts/sync-agent-variant-docs.ts b/scripts/sync-agent-variant-docs.ts index 0bd2ec3d98..e5054d8f1c 100644 --- a/scripts/sync-agent-variant-docs.ts +++ b/scripts/sync-agent-variant-docs.ts @@ -1,14 +1,15 @@ // SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. // SPDX-License-Identifier: Apache-2.0 -import { mkdirSync, readFileSync, writeFileSync } from "node:fs"; +import { mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs"; import path from "node:path"; import { fileURLToPath, pathToFileURL } from "node:url"; +import { parse } from "yaml"; const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), ".."); +const docsRoot = path.join(repoRoot, "docs"); const sourcePath = path.join(repoRoot, "docs/reference/commands.mdx"); const targetPath = path.join(repoRoot, "docs/reference/commands-nemohermes.mdx"); -const lifecyclePath = path.join(repoRoot, "docs/manage-sandboxes/lifecycle.mdx"); const generatedDocsRoot = path.join(repoRoot, "docs/_build/agent-variants"); const agentVariants = ["openclaw", "hermes"] as const; @@ -21,6 +22,24 @@ type RenderAgentVariantOptions = { outputPath?: string; sourcePath?: string; }; +type DocsIndex = { + navigation?: NavigationItem[]; +}; +type NavigationItem = { + variants?: NavigationVariant[]; + layout?: NavigationNode[]; + contents?: NavigationNode[]; + path?: string; + slug?: string; +}; +type NavigationVariant = { + slug?: string; + layout?: NavigationNode[]; +}; +type NavigationNode = { + contents?: NavigationNode[]; + path?: string; +}; const GENERATED_NOTICE = "{/* 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. */}"; @@ -65,6 +84,7 @@ export function renderHermesCommandsReference(source: string): string { "", ), ) + .replaceAll(CLI_SENTINEL, "nemohermes") .replace(/\n{3,}/g, "\n\n") .trimStart(); @@ -129,6 +149,10 @@ export function renderAgentVariantPage( options: RenderAgentVariantOptions = {}, ): string { const { frontmatter, body } = splitFrontmatter(source); + const renderedFrontmatter = frontmatter.replaceAll( + CLI_SENTINEL, + variant === "hermes" ? "nemohermes" : "nemoclaw", + ); let renderedBody = stripAgentOnlyBlocksForVariant( body.replace(/^import \{ AgentOnly \} from "\.\.\/_components\/AgentGuide";\n\n?/m, ""), variant, @@ -138,37 +162,135 @@ export function renderAgentVariantPage( .trimStart(); if (options.sourcePath && options.outputPath) { - renderedBody = rewriteRelativeMarkdownLinks( - renderedBody, - path.dirname(options.sourcePath), - path.dirname(options.outputPath), - ); + renderedBody = rewriteRelativePaths(renderedBody, options.sourcePath, options.outputPath); } - return `${frontmatter}${GENERATED_VARIANT_NOTICE}\n\n${renderedBody}`.replace(/\s*$/, "\n"); + return `${renderedFrontmatter}${GENERATED_VARIANT_NOTICE}\n\n${renderedBody}`.replace( + /\s*$/, + "\n", + ); } function renderGeneratedAgentVariantPages(): RenderedFile[] { - const source = readFileSync(lifecyclePath, "utf8"); - const basename = path.basename(lifecyclePath, ".mdx"); - const relativeSourceDirectory = path.relative( - path.join(repoRoot, "docs"), - path.dirname(lifecyclePath), + return findAgentVariantSourcePaths().flatMap((sourceFilePath) => { + const source = readFileSync(sourceFilePath, "utf8"); + const basename = path.basename(sourceFilePath, ".mdx"); + const relativeSourceDirectory = path.relative(docsRoot, path.dirname(sourceFilePath)); + return agentVariants.map((variant) => { + const outputPath = path.join( + generatedDocsRoot, + relativeSourceDirectory, + `${basename}.${variant}.generated.mdx`, + ); + return { + path: outputPath, + contents: renderAgentVariantPage(source, variant, { + outputPath, + sourcePath: sourceFilePath, + }), + }; + }); + }); +} + +function findAgentVariantSourcePaths(): string[] { + const sharedSources = findSharedNavigationSourcePaths(); + assertNoUnsharedPlaceholders(sharedSources); + return [...sharedSources].sort().map((sourcePath) => path.join(docsRoot, sourcePath)); +} + +function findSharedNavigationSourcePaths(): Set { + const docsIndex = parse(readFileSync(path.join(docsRoot, "index.yml"), "utf8")) as DocsIndex; + const userGuide = docsIndex.navigation?.find((item) => Array.isArray(item.variants)); + const openclaw = userGuide?.variants?.find((variant) => variant.slug === "openclaw"); + const hermes = userGuide?.variants?.find((variant) => variant.slug === "hermes"); + if (!openclaw?.layout || !hermes?.layout) { + throw new Error("docs/index.yml must define openclaw and hermes navigation variants"); + } + + const openclawPaths = collectSourcePaths(openclaw.layout); + const hermesPaths = collectSourcePaths(hermes.layout); + return new Set([...openclawPaths].filter((sourcePath) => hermesPaths.has(sourcePath))); +} + +function collectSourcePaths(nodes: NavigationNode[]): Set { + const paths = new Set(); + for (const node of nodes) { + const sourcePath = normalizeNavigationSourcePath(node.path); + if (sourcePath) paths.add(sourcePath); + if (node.contents) { + for (const childPath of collectSourcePaths(node.contents)) { + paths.add(childPath); + } + } + } + return paths; +} + +function normalizeNavigationSourcePath(navPath: string | undefined): string | null { + if (!navPath) return null; + const generatedMatch = navPath.match( + /^_build\/agent-variants\/(.+)\.(?:openclaw|hermes)\.generated\.mdx$/, ); - return agentVariants.map((variant) => { - const outputPath = path.join( - generatedDocsRoot, - relativeSourceDirectory, - `${basename}.${variant}.generated.mdx`, + const sourcePath = + generatedMatch?.[1] ? `${generatedMatch[1]}.mdx` : normalizeLegacyVariantSource(navPath); + if (!sourcePath.endsWith(".mdx") || sourcePath === "index.mdx") return null; + return sourcePath; +} + +function normalizeLegacyVariantSource(navPath: string): string { + if (navPath === "reference/commands-nemohermes.mdx") return "reference/commands.mdx"; + return navPath; +} + +function assertNoUnsharedPlaceholders(sharedSources: Set): void { + const offenderPaths: string[] = []; + for (const sourcePath of findPlaceholderSourcePaths()) { + if (!sharedSources.has(sourcePath)) offenderPaths.push(sourcePath); + } + if (offenderPaths.length > 0) { + throw new Error( + [ + "The following non-shared nav pages contain $$nemoclaw and would render it literally:", + ...offenderPaths.map((offenderPath) => ` - docs/${offenderPath}`), + "Use a literal CLI name on single-variant pages, or add the page to both nav variants.", + ].join("\n"), ); - return { - path: outputPath, - contents: renderAgentVariantPage(source, variant, { - outputPath, - sourcePath: lifecyclePath, - }), - }; - }); + } +} + +function findPlaceholderSourcePaths(): string[] { + const files: string[] = []; + walkDocs(docsRoot, files); + return files.sort(); +} + +function walkDocs(directory: string, files: string[]): void { + for (const entry of readdirSync(directory, { withFileTypes: true })) { + const entryPath = path.join(directory, entry.name); + if (entry.isDirectory()) { + if (entry.name.startsWith("_")) continue; + walkDocs(entryPath, files); + continue; + } + if (!entry.isFile() || !entry.name.endsWith(".mdx")) continue; + if (entry.name.endsWith(".generated.mdx") || entry.name === "commands-nemohermes.mdx") { + continue; + } + if (readFileSync(entryPath, "utf8").includes(CLI_SENTINEL)) { + files.push(path.relative(docsRoot, entryPath).replaceAll(path.sep, "/")); + } + } +} + +function rewriteRelativePaths(body: string, sourcePath: string, outputPath: string): string { + const sourceDirectory = path.dirname(sourcePath); + const outputDirectory = path.dirname(outputPath); + return rewriteRelativeImports( + rewriteRelativeMarkdownLinks(body, sourceDirectory, outputDirectory), + sourceDirectory, + outputDirectory, + ); } function rewriteRelativeMarkdownLinks( @@ -182,6 +304,20 @@ function rewriteRelativeMarkdownLinks( }); } +function rewriteRelativeImports( + body: string, + sourceDirectory: string, + outputDirectory: string, +): string { + return body.replace( + /^(import\s+[^'"]+\s+from\s+["'])([^"']+)(["'];?)$/gm, + (_match, prefix, target, suffix) => { + if (shouldKeepLinkTarget(target)) return `${prefix}${target}${suffix}`; + return `${prefix}${rewriteRelativeLinkTarget(target, sourceDirectory, outputDirectory)}${suffix}`; + }, + ); +} + function shouldKeepLinkTarget(target: string): boolean { return target.startsWith("#") || target.startsWith("/") || /^[a-z][a-z0-9+.-]*:/i.test(target); } diff --git a/test/agent-variant-docs.test.ts b/test/agent-variant-docs.test.ts index 1afdbab1fa..900763709f 100644 --- a/test/agent-variant-docs.test.ts +++ b/test/agent-variant-docs.test.ts @@ -7,8 +7,9 @@ import { renderAgentVariantPage } from "../scripts/sync-agent-variant-docs"; const source = `--- title: "Example" +description-agent: "Use when looking up $$nemoclaw commands." --- -import { AgentOnly } from "../_components/AgentGuide"; +import { AgentCli, AgentOnly } from "../_components/AgentGuide"; OpenClaw only. @@ -20,6 +21,8 @@ Hermes only. \`\`\`bash $$nemoclaw list \`\`\` + +Use for the current variant. `; describe("agent variant docs", () => { @@ -27,10 +30,11 @@ describe("agent variant docs", () => { const rendered = renderAgentVariantPage(source, "openclaw"); expect(rendered).toContain("OpenClaw only."); + expect(rendered).toContain('description-agent: "Use when looking up nemoclaw commands."'); expect(rendered).not.toContain("Hermes only."); expect(rendered).toContain("nemoclaw list"); expect(rendered).not.toContain("$$nemoclaw"); - expect(rendered).not.toContain("AgentOnly"); + expect(rendered).not.toContain(" { @@ -38,12 +42,13 @@ describe("agent variant docs", () => { expect(rendered).not.toContain("OpenClaw only."); expect(rendered).toContain("Hermes only."); + expect(rendered).toContain('description-agent: "Use when looking up nemohermes commands."'); expect(rendered).toContain("nemohermes list"); expect(rendered).not.toContain("$$nemoclaw"); - expect(rendered).not.toContain("AgentOnly"); + expect(rendered).not.toContain(" { + it("rewrites relative imports for generated build output", () => { const rendered = renderAgentVariantPage( `${source}\nSee [Commands](../reference/commands#$$nemoclaw-list).\nSee [Backup](backup-restore).\n`, "hermes", @@ -54,6 +59,9 @@ describe("agent variant docs", () => { }, ); + expect(rendered).toContain( + 'import { AgentCli, AgentOnly } from "../../../_components/AgentGuide";', + ); expect(rendered).toContain("[Commands](../../../reference/commands#nemohermes-list)"); expect(rendered).toContain("[Backup](../../../manage-sandboxes/backup-restore)"); }); From bacd89a66a8e5a6b01d70442c63ecbdb8ab8aa10 Mon Sep 17 00:00:00 2001 From: Miyoung Choi Date: Wed, 3 Jun 2026 15:36:37 -0700 Subject: [PATCH 2/5] docs: preserve route-style links in variants --- docs/CONTRIBUTING.md | 12 ++++++++++++ docs/about/release-notes.mdx | 4 ++-- docs/get-started/prerequisites.mdx | 2 +- docs/get-started/windows-preparation.mdx | 14 +++++++------- docs/reference/commands-nemohermes.mdx | 2 +- docs/reference/commands.mdx | 4 ++-- docs/reference/troubleshooting.mdx | 8 ++++---- docs/security/best-practices.mdx | 4 ++-- scripts/sync-agent-variant-docs.ts | 6 +++--- test/agent-variant-docs.test.ts | 9 +++++---- test/e2e/e2e-cloud-experimental/check-docs.sh | 11 +++++++++++ 11 files changed, 50 insertions(+), 26 deletions(-) diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index 8b6e4f90c8..71c4a1acd1 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -158,6 +158,18 @@ Run `npm run docs:sync-agent-variants` after editing shared variant source pages Run `npm run docs` before opening a PR to verify the generated pages, rewritten relative links, and Fern navigation. If content differs by behavior, setup flow, state layout, or agent-specific wording, keep using `` blocks for that content. +## Route-Style Links + +Fern links between docs pages should use route-style paths, not filesystem paths. +Route-style paths omit the `.mdx` extension and follow the page slugs declared in `docs/index.yml`. +For example, a source page under `docs/get-started/` should link to the OpenClaw quickstart as `../quickstart`, not `quickstart.mdx`. +The published route comes from the navigation hierarchy and page `slug`, not directly from the file path. + +This matters for generated agent variants because shared source pages may not appear directly in `docs/index.yml`. +The navigation can point Fern at generated pages under `docs/_build/agent-variants/`, while the source MDX remains in its normal folder. +The link checker maps those generated nav entries back to their source paths when validating route-style links. +Do not convert route-style links to `.mdx` file links just to satisfy a local filesystem check. + ## Doc-Only PR Verification Doc-only pull requests do not need the full test suite by default. diff --git a/docs/about/release-notes.mdx b/docs/about/release-notes.mdx index d061ea0358..d4217cc0cc 100644 --- a/docs/about/release-notes.mdx +++ b/docs/about/release-notes.mdx @@ -49,9 +49,9 @@ NemoClaw v0.0.55 improves local Ollama onboarding reliability, plugin secret-sca NemoClaw v0.0.54 updates messaging activation, Windows WSL onboarding, NemoHermes dashboard access, and sandbox repair paths: - Generated OpenClaw config now marks Telegram, Discord, Slack, and WhatsApp as enabled at the channel level. Selected messaging plugins are pinned during the image build, and `channels add` verifies Telegram, Discord, and Slack bridge startup after the rebuild instead of leaving silent channel failures for later debugging. For more information, refer to [Messaging Channels](../manage-sandboxes/messaging-channels). -- The Windows bootstrap flow waits for Ubuntu account creation before touching Docker settings, enables Docker Desktop WSL integration for the target distro, avoids changing the global WSL default distro, and adds WSL-specific Docker reachability hints during onboarding. For more information, refer to [Prepare Windows for NemoClaw](../get-started/windows-preparation.mdx). +- The Windows bootstrap flow waits for Ubuntu account creation before touching Docker settings, enables Docker Desktop WSL integration for the target distro, avoids changing the global WSL default distro, and adds WSL-specific Docker reachability hints during onboarding. For more information, refer to [Prepare Windows for NemoClaw](../get-started/prerequisites/windows-preparation). - Windows-host Ollama setup inside WSL now requires the Docker Desktop WSL integration path. NemoClaw still shows Windows-host Ollama options when it detects them, but labels the Docker Desktop requirement and blocks unsupported native Docker-in-WSL selections before it tries to start or install Ollama. For more information, refer to [Use a Local Inference Server](../inference/use-local-inference). -- NemoHermes can expose the optional native Hermes web dashboard separately from the OpenAI-compatible API. Set `NEMOCLAW_HERMES_DASHBOARD=1` before onboarding to start and forward the dashboard on port `9119`, with `NEMOCLAW_HERMES_DASHBOARD_PORT` and `NEMOCLAW_HERMES_DASHBOARD_TUI` available for port and TUI tab control. For more information, refer to [NemoClaw Quickstart with Hermes](../get-started/quickstart-hermes.mdx). +- NemoHermes can expose the optional native Hermes web dashboard separately from the OpenAI-compatible API. Set `NEMOCLAW_HERMES_DASHBOARD=1` before onboarding to start and forward the dashboard on port `9119`, with `NEMOCLAW_HERMES_DASHBOARD_PORT` and `NEMOCLAW_HERMES_DASHBOARD_TUI` available for port and TUI tab control. For more information, refer to [NemoClaw Quickstart with Hermes](../../hermes/get-started/quickstart-hermes). - Onboarding diagnostics include more copy-paste-ready recovery hints. Invalid sandbox names now include a `Try: ` line when NemoClaw can derive a valid name, and non-interactive NVIDIA Endpoints setup prints the exact `export NVIDIA_API_KEY=nvapi-...` shape when the key is missing. For more information, refer to [NemoClaw CLI Commands Reference](../reference/commands). - Homebrew stays on the Linuxbrew prefix while exposing installed formula commands in sandbox shell sessions, the `/nemoclaw` slash command activates at OpenClaw startup again, Hermes rebuilds tolerate older release tarballs that lack optional UI package lockfiles, and device scope-upgrade approvals recover without being pinned to the old gateway-scoped request. For more information, refer to [Common NemoClaw Integration Policy Examples](../network-policy/integration-policy-examples). - The host-gateway allowance for OpenClaw `web_fetch` is confined to the trusted proxy path, while strict and direct paths continue to block host-gateway names. Hermes Provider onboarding skips the host-side smoke probe only for OAuth-backed setup and keeps direct validation for Nous API key setup. For more information, refer to [NemoClaw Inference Options](../inference/inference-options). diff --git a/docs/get-started/prerequisites.mdx b/docs/get-started/prerequisites.mdx index 8688d5c015..a02008b529 100644 --- a/docs/get-started/prerequisites.mdx +++ b/docs/get-started/prerequisites.mdx @@ -78,6 +78,6 @@ The table comes from [`ci/platform-matrix.json`](https://github.com/NVIDIA/NemoC ## Next Steps -- [Prepare Windows for NemoClaw](windows-preparation.mdx) if you are using Windows. +- [Prepare Windows for NemoClaw](prerequisites/windows-preparation) if you are using Windows. - [Quickstart](quickstart) to install NemoClaw and launch your first sandbox. - [Agent Skills](../resources/agent-skills) to load NemoClaw guidance into an AI coding assistant before setup. diff --git a/docs/get-started/windows-preparation.mdx b/docs/get-started/windows-preparation.mdx index 44ad2b8e97..3e3012795b 100644 --- a/docs/get-started/windows-preparation.mdx +++ b/docs/get-started/windows-preparation.mdx @@ -13,10 +13,10 @@ import { AgentOnly } from "../_components/AgentGuide"; You can run NemoClaw inside Windows Subsystem for Linux (WSL 2) on Windows. -Complete these steps before following the [Quickstart](quickstart.mdx). +Complete these steps before following the [Quickstart](../quickstart). -Complete these steps before following [Quickstart with Hermes](quickstart-hermes.mdx). +Complete these steps before following [Quickstart with Hermes](../quickstart-hermes). Linux and macOS users do not need this page and can go directly to the Quickstart. @@ -31,12 +31,12 @@ Verify the following before you begin: - Windows 10 (build 19041 or later) or Windows 11. -- Hardware requirements are the same as the [Quickstart](quickstart.mdx). +- Hardware requirements are the same as the [Quickstart](../quickstart). -- Hardware requirements are the same as [Quickstart with Hermes](quickstart-hermes.mdx). +- Hardware requirements are the same as [Quickstart with Hermes](../quickstart-hermes). @@ -164,14 +164,14 @@ Use one instance, or move one of them to a different port before running `$$nemo Your Windows environment is ready. If you used the bootstrap script, follow the installer command it printed inside Ubuntu. -If you prepared Windows manually, open a WSL terminal (type `wsl` in PowerShell, or open Ubuntu from Windows Terminal) and continue with the [Quickstart](quickstart.mdx) to install NemoClaw and launch your first sandbox. +If you prepared Windows manually, open a WSL terminal (type `wsl` in PowerShell, or open Ubuntu from Windows Terminal) and continue with the [Quickstart](../quickstart) to install NemoClaw and launch your first sandbox. -If you prepared Windows manually, open a WSL terminal (type `wsl` in PowerShell, or open Ubuntu from Windows Terminal) and continue with [Quickstart with Hermes](quickstart-hermes.mdx) to install NemoClaw and launch your first Hermes sandbox. +If you prepared Windows manually, open a WSL terminal (type `wsl` in PowerShell, or open Ubuntu from Windows Terminal) and continue with [Quickstart with Hermes](../quickstart-hermes) to install NemoClaw and launch your first Hermes sandbox. All NemoClaw commands run inside WSL, not in PowerShell. ## Troubleshooting -For Windows-specific troubleshooting, refer to the [Windows Subsystem for Linux section](../reference/troubleshooting.mdx#windows-subsystem-for-linux) in the Troubleshooting guide. +For Windows-specific troubleshooting, refer to the [Windows Subsystem for Linux section](../../reference/troubleshooting#windows-subsystem-for-linux) in the Troubleshooting guide. diff --git a/docs/reference/commands-nemohermes.mdx b/docs/reference/commands-nemohermes.mdx index 7cbc697cc4..5edaae4958 100644 --- a/docs/reference/commands-nemohermes.mdx +++ b/docs/reference/commands-nemohermes.mdx @@ -1665,7 +1665,7 @@ These flags change defaults for commands that manage existing sandboxes. These variables seed defaults for `nemohermes deploy` and `nemohermes onboard --remote`, which provision a sandbox on a Brev instance. Each has a flag equivalent on `deploy`; the env var lets non-interactive runs skip the prompt. -For narrative how-to coverage of `NEMOCLAW_BREV_PROVIDER` and `NEMOCLAW_GPU`, see [Deploy to Remote GPU](../deployment/deploy-to-remote-gpu.mdx). +For narrative how-to coverage of `NEMOCLAW_BREV_PROVIDER` and `NEMOCLAW_GPU`, see [Deploy to Remote GPU](../deployment/deploy-to-remote-gpu.md). | Variable | Default | Effect | |----------|---------|--------| diff --git a/docs/reference/commands.mdx b/docs/reference/commands.mdx index 55e57147c1..7ef3287540 100644 --- a/docs/reference/commands.mdx +++ b/docs/reference/commands.mdx @@ -989,7 +989,7 @@ Skill names must contain only alphanumeric characters, dots, hyphens, and unders -OpenClaw plugins are a different kind of extension. To install an OpenClaw plugin, see [Install OpenClaw Plugins](../deployment/install-openclaw-plugins.mdx). +OpenClaw plugins are a different kind of extension. To install an OpenClaw plugin, see [Install OpenClaw Plugins](../manage-sandboxes/install-openclaw-plugins). @@ -1934,7 +1934,7 @@ These flags change defaults for commands that manage existing sandboxes. These variables seed defaults for `$$nemoclaw deploy` and `$$nemoclaw onboard --remote`, which provision a sandbox on a Brev instance. Each has a flag equivalent on `deploy`; the env var lets non-interactive runs skip the prompt. -For narrative how-to coverage of `NEMOCLAW_BREV_PROVIDER` and `NEMOCLAW_GPU`, see [Deploy to Remote GPU](../deployment/deploy-to-remote-gpu.mdx). +For narrative how-to coverage of `NEMOCLAW_BREV_PROVIDER` and `NEMOCLAW_GPU`, see [Deploy to Remote GPU](../deployment/deploy-to-remote-gpu.md). | Variable | Default | Effect | |----------|---------|--------| diff --git a/docs/reference/troubleshooting.mdx b/docs/reference/troubleshooting.mdx index 6d73904183..51dc311151 100644 --- a/docs/reference/troubleshooting.mdx +++ b/docs/reference/troubleshooting.mdx @@ -1285,7 +1285,7 @@ If you run other services on Spark that expect port 3000, bind them to a differe ## Windows Subsystem for Linux -For environment setup steps, see [Windows Prerequisites](../get-started/windows-preparation.mdx). +For environment setup steps, see [Windows Prerequisites](../get-started/prerequisites/windows-preparation). ### `wsl --install --no-distribution` returns Forbidden (403) @@ -1359,7 +1359,7 @@ sudo systemctl stop ollama OLLAMA_CONTEXT_LENGTH=16384 ollama serve ``` -For additional troubleshooting, see the [Quickstart](../get-started/quickstart.mdx) and [Windows Setup](../get-started/windows-preparation.mdx) pages. +For additional troubleshooting, see the [Quickstart](../get-started/quickstart) and [Windows Setup](../get-started/prerequisites/windows-preparation) pages. ## Podman @@ -1453,7 +1453,7 @@ After the rebuild completes, return to the Skills page to confirm the skill is r ## Hermes The issues below are common problems you may encounter when running Hermes through `nemohermes`. -For setup, refer to [Quickstart with Hermes](../get-started/quickstart-hermes.mdx). +For setup, refer to [Quickstart with Hermes](../../hermes/get-started/quickstart-hermes). ### Port 8642 in a browser shows a blank page or `Cannot GET /` @@ -1550,7 +1550,7 @@ Reset a specific provider's credentials with `nemohermes credentials reset { + return body.replace(/(!\[[^\]]*\]\()([^)]+)(\))/g, (_match, prefix, target, suffix) => { if (shouldKeepLinkTarget(target)) return `${prefix}${target}${suffix}`; return `${prefix}${rewriteRelativeLinkTarget(target, sourceDirectory, outputDirectory)}${suffix}`; }); diff --git a/test/agent-variant-docs.test.ts b/test/agent-variant-docs.test.ts index 900763709f..83ed5242aa 100644 --- a/test/agent-variant-docs.test.ts +++ b/test/agent-variant-docs.test.ts @@ -48,9 +48,9 @@ describe("agent variant docs", () => { expect(rendered).not.toContain(" { + it("rewrites relative imports but preserves Fern route links for generated build output", () => { const rendered = renderAgentVariantPage( - `${source}\nSee [Commands](../reference/commands#$$nemoclaw-list).\nSee [Backup](backup-restore).\n`, + `${source}\nSee [Commands](../reference/commands#$$nemoclaw-list).\nSee [Backup](backup-restore).\n![Diagram](images/diagram.png)\n`, "hermes", { outputPath: @@ -62,7 +62,8 @@ describe("agent variant docs", () => { expect(rendered).toContain( 'import { AgentCli, AgentOnly } from "../../../_components/AgentGuide";', ); - expect(rendered).toContain("[Commands](../../../reference/commands#nemohermes-list)"); - expect(rendered).toContain("[Backup](../../../manage-sandboxes/backup-restore)"); + expect(rendered).toContain("[Commands](../reference/commands#nemohermes-list)"); + expect(rendered).toContain("[Backup](backup-restore)"); + expect(rendered).toContain("![Diagram](../../../manage-sandboxes/images/diagram.png)"); }); }); diff --git a/test/e2e/e2e-cloud-experimental/check-docs.sh b/test/e2e/e2e-cloud-experimental/check-docs.sh index a67319ebdf..824961ec29 100755 --- a/test/e2e/e2e-cloud-experimental/check-docs.sh +++ b/test/e2e/e2e-cloud-experimental/check-docs.sh @@ -742,9 +742,18 @@ function maybeEmit(item) { if (!item || item.emitted || !variant || !item.path || !item.slug || item.indent <= 6) return; const route = ["user-guide", variant, ...item.parent, item.slug].join("/"); rows.push(`${item.path}\t${route}`); + const sourcePath = agentVariantSourcePath(item.path); + if (sourcePath && sourcePath !== item.path) { + rows.push(`${sourcePath}\t${route}`); + } item.emitted = true; } +function agentVariantSourcePath(navPath) { + const match = navPath.match(/^_build\/agent-variants\/(.+)\.(?:openclaw|hermes)\.generated\.mdx$/); + return match ? `${match[1]}.mdx` : null; +} + function maybePushSection(item) { if (!item || item.pushed || item.type !== "section" || !item.slug || item.indent <= 6) return; stack.push({ indent: item.indent, slug: item.slug }); @@ -812,6 +821,8 @@ normalize_fern_route_path() { nemoclaw/*) input="${input#nemoclaw/}" ;; latest/*) input="${input#latest/}" ;; esac + input="${input%.mdx}" + input="${input%.md}" local -a parts=() out=() local IFS='/' From 5b08220c8e2d0a84c81470775bd898a936e7222c Mon Sep 17 00:00:00 2001 From: Miyoung Choi Date: Wed, 3 Jun 2026 15:47:37 -0700 Subject: [PATCH 3/5] test: normalize CLI placeholder in docs parity --- test/e2e/e2e-cloud-experimental/check-docs.sh | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/test/e2e/e2e-cloud-experimental/check-docs.sh b/test/e2e/e2e-cloud-experimental/check-docs.sh index 824961ec29..bfd52daaae 100755 --- a/test/e2e/e2e-cloud-experimental/check-docs.sh +++ b/test/e2e/e2e-cloud-experimental/check-docs.sh @@ -156,7 +156,7 @@ JSON log "[cli] comparing: $NODE bin/nemoclaw.js --dump-commands" # shellcheck disable=SC2016 # log text: backticks are documentation markers, not command substitution - log '[cli] vs: docs/reference/commands.mdx (### `nemoclaw …` headings only)' + log '[cli] vs: docs/reference/commands.mdx (### `nemoclaw …` or `$$nemoclaw …` headings)' log "[cli] phase 1/2: dump canonical command list from registry" if ! HOME="$_cli_home" "$NODE" "$CLI_JS" --dump-commands >"$_tmp/help.txt" 2>"$_tmp/help.err"; then @@ -172,11 +172,11 @@ JSON # shellcheck disable=SC2016 # log text: backticks are documentation markers, not command substitution - log '[cli] phase 2/2: extract ### `nemoclaw …` headings from commands reference' + log '[cli] phase 2/2: extract ### `nemoclaw …` / `$$nemoclaw …` headings from commands reference' # Allow optional MyST suffix on the same line, e.g. ### `nemoclaw onboard` {#anchor}. # Preserve placeholders that are part of the canonical help signature, but # keep accepting docs-only suffixes such as `snapshot restore [selector]`. - grep -E '^### `nemoclaw ' "$COMMANDS_MD" | LC_ALL=C perl -CS -ne ' + grep -E '^### `(\$\$)?nemoclaw ' "$COMMANDS_MD" | LC_ALL=C perl -CS -ne ' BEGIN { my $help_path = shift @ARGV; open my $help_fh, "<", $help_path or die "open help list: $!"; @@ -188,6 +188,7 @@ JSON } if (/^### `([^`]+)`\s*(?:\{[^}]+\})?\s*$/) { my $c = $1; + $c =~ s/^\$\$nemoclaw\b/nemoclaw/; $c =~ s/\s+$//; while (!$help{$c}) { my $changed = 0; @@ -254,6 +255,7 @@ JSON bt = index(line, "`") if (bt > 0) { cand = substr(line, 1, bt - 1) + sub(/^\$\$nemoclaw/, "nemoclaw", cand) sub(/[[:space:]]+$/, "", cand) if (cand == target) { in_sec = 1 From d18f8247128345a63b033c5691f89d60e9538928 Mon Sep 17 00:00:00 2001 From: Miyoung Choi Date: Wed, 3 Jun 2026 15:51:39 -0700 Subject: [PATCH 4/5] Update docs/about/release-notes.mdx Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> --- docs/about/release-notes.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/about/release-notes.mdx b/docs/about/release-notes.mdx index d4217cc0cc..edeeae011a 100644 --- a/docs/about/release-notes.mdx +++ b/docs/about/release-notes.mdx @@ -32,7 +32,7 @@ NemoClaw v0.0.56 improves install safety, local-inference validation, messaging - `$$nemoclaw status`, `$$nemoclaw connect`, and `$$nemoclaw upgrade-sandboxes` now probe the live sandbox agent version before deciding whether a rebuild is needed, instead of trusting stale host metadata. Status output reports when the version cannot be verified and points at rebuild when the running agent may predate the current install. For more information, refer to [NemoClaw CLI Commands Reference](../reference/commands). - GPU Docker-driver local-inference onboarding now verifies that host-network sandboxes can reach the selected Ollama or vLLM health endpoint before onboarding reports success. Failures now include the provider endpoint, container network mode, and recovery guidance, which avoids discovering the broken route only after the first agent prompt. For more information, refer to [Use a Local Inference Server](../inference/use-local-inference). - Messaging setup is more diagnosable. Slack setup validates both required Slack credentials before enabling the channel, WhatsApp pairing renders a compact scan-friendly QR for OpenClaw sandboxes and separates gateway close errors from QR rendering, and Telegram DM allowlist aliases continue to work for existing automation. For more information, refer to [Messaging Channels](../manage-sandboxes/messaging-channels). -- Command ergonomics are clearer for common day-two paths. `$$nemoclaw inference set` without both `--provider` and `--model` now points users to the underlying `openshell inference set` command, `nemoclaw skill remove ` removes uploaded skills by `SKILL.md` name, `$$nemoclaw status --json` supports per-sandbox automation, and `$$nemoclaw debug --sandbox` validates explicit sandbox names before writing diagnostics. For more information, refer to [NemoClaw CLI Commands Reference](../reference/commands). +- Command ergonomics are clearer for common day-two paths. `$$nemoclaw inference set` without both `--provider` and `--model` now points users to the underlying `openshell inference set` command, `$$nemoclaw skill remove ` removes uploaded skills by `SKILL.md` name, `$$nemoclaw status --json` supports per-sandbox automation, and `$$nemoclaw debug --sandbox` validates explicit sandbox names before writing diagnostics. For more information, refer to [NemoClaw CLI Commands Reference](../reference/commands). - Policy and sandbox base-image compatibility improved. The `pypi` preset allows the `uv` package manager binary, the sandbox base image includes `tmux` for OpenClaw's bundled tmux-session flow, and Jira preset validation docs now use observable status probes. For more information, refer to [Common NemoClaw Integration Policy Examples](../network-policy/integration-policy-examples). - Uninstall, rebuild, and snapshot flows protect user state more consistently. `$$nemoclaw uninstall` preserves host-side backups and the sandbox registry by default, rebuilds preserve explicit CPU-only sandbox intent, and snapshot restore blocks ambiguous existing-destination rollbacks unless you opt in with `--force`. For more information, refer to [Manage Sandbox Lifecycle](../manage-sandboxes/lifecycle). From 39f7ea251ccab90e8c14f6e7275a6e0a745d727c Mon Sep 17 00:00:00 2001 From: Miyoung Choi Date: Wed, 3 Jun 2026 16:17:02 -0700 Subject: [PATCH 5/5] test: keep generated docs placeholders in sync --- ci/platform-matrix.json | 2 +- scripts/sync-agent-variant-docs.ts | 5 +++-- 2 files changed, 4 insertions(+), 3 deletions(-) diff --git a/ci/platform-matrix.json b/ci/platform-matrix.json index 6d9c78e577..887ee0bd5f 100644 --- a/ci/platform-matrix.json +++ b/ci/platform-matrix.json @@ -33,7 +33,7 @@ "status": "tested", "prd_priority": "P1", "ci_tested": true, - "notes": "Use the standard installer and `nemoclaw onboard`. For an end-to-end walkthrough with local Ollama inference, see the [NVIDIA Spark playbook](https://build.nvidia.com/spark/nemoclaw)." + "notes": "Use the standard installer and `$$nemoclaw onboard`. For an end-to-end walkthrough with local Ollama inference, see the [NVIDIA Spark playbook](https://build.nvidia.com/spark/nemoclaw)." }, { "name": "Windows WSL2", diff --git a/scripts/sync-agent-variant-docs.ts b/scripts/sync-agent-variant-docs.ts index aa76781acc..9d5182502b 100644 --- a/scripts/sync-agent-variant-docs.ts +++ b/scripts/sync-agent-variant-docs.ts @@ -232,8 +232,9 @@ function normalizeNavigationSourcePath(navPath: string | undefined): string | nu const generatedMatch = navPath.match( /^_build\/agent-variants\/(.+)\.(?:openclaw|hermes)\.generated\.mdx$/, ); - const sourcePath = - generatedMatch?.[1] ? `${generatedMatch[1]}.mdx` : normalizeLegacyVariantSource(navPath); + const sourcePath = generatedMatch?.[1] + ? `${generatedMatch[1]}.mdx` + : normalizeLegacyVariantSource(navPath); if (!sourcePath.endsWith(".mdx") || sourcePath === "index.mdx") return null; return sourcePath; }