diff --git a/.agents/skills/nemoclaw-user-agent-skills/SKILL.md b/.agents/skills/nemoclaw-user-agent-skills/SKILL.md index fca8d94d8c7..de9e10cd98c 100644 --- a/.agents/skills/nemoclaw-user-agent-skills/SKILL.md +++ b/.agents/skills/nemoclaw-user-agent-skills/SKILL.md @@ -48,6 +48,7 @@ The following user skills ship with NemoClaw. | Skill | Summary | |-------|---------| | `nemoclaw-user-overview` | What NemoClaw is, ecosystem placement (OpenClaw + OpenShell + NemoClaw), how it works internally, and release notes. | +| `nemoclaw-user-agent-skills` | Clone, update, and use NemoClaw's agent skills, including this page and the skills directory layout. | | `nemoclaw-user-get-started` | Install NemoClaw, launch a sandbox, and run the first agent prompt. | | `nemoclaw-user-configure-inference` | Choose inference providers during onboarding, switch models without restarting, and set up local inference servers (Ollama, vLLM, TensorRT-LLM, NIM). | | `nemoclaw-user-manage-policy` | Approve or deny blocked egress requests in the TUI and customize the sandbox network policy (add, remove, or modify allowed endpoints). | @@ -74,6 +75,7 @@ Examples of questions your assistant can answer with these skills: | "What security controls can I configure?" | `nemoclaw-user-configure-security` | | "Back up my agent workspace files." | `nemoclaw-user-manage-sandboxes` | | "What CLI commands are available?" | `nemoclaw-user-reference` | +| "What NemoClaw skills are available for my coding assistant?" | `nemoclaw-user-agent-skills` | You can also reference a skill directly by name if you know which one you need. diff --git a/.agents/skills/nemoclaw-user-configure-inference/SKILL.md b/.agents/skills/nemoclaw-user-configure-inference/SKILL.md index f943d1af667..0c243cafd9d 100644 --- a/.agents/skills/nemoclaw-user-configure-inference/SKILL.md +++ b/.agents/skills/nemoclaw-user-configure-inference/SKILL.md @@ -245,6 +245,7 @@ If the provider itself needs to change (for example, switching from vLLM to a cl ## References - **Load [references/switch-inference-providers.md](references/switch-inference-providers.md)** when switching inference providers, changing the model runtime, or reconfiguring inference routing. Changes the active inference model without restarting the sandbox. +- **Load [references/declarative-agents-manifest.md](references/declarative-agents-manifest.md)** when users ask how to declare a manager-worker layout, how to give a secondary agent its own model, or how to express OpenClaw's `subagents.allowAgents` from NemoClaw. Documents the `nemoclaw onboard --agents ` flag and the YAML schema it consumes. - **Load [references/set-up-sub-agent.md](references/set-up-sub-agent.md)** when users ask how to add a second model, configure a sub-agent model, use Omni for vision tasks, configure agents.list, or use sessions_spawn in NemoClaw. Shows the NemoClaw-specific file paths and update flow for adding an auxiliary OpenClaw sub-agent model. - **Load [references/inference-options.md](references/inference-options.md)** when explaining which providers are available, what the onboard wizard presents, or how inference routing works. Lists all inference providers offered during NemoClaw onboarding. - **[references/tool-calling-reliability.md](references/tool-calling-reliability.md)** — Explains Ollama tool-call leak symptoms, when to use vLLM with a tool-call parser, and how to repoint NemoClaw to a parser-aware local endpoint. diff --git a/.agents/skills/nemoclaw-user-configure-inference/references/declarative-agents-manifest.md b/.agents/skills/nemoclaw-user-configure-inference/references/declarative-agents-manifest.md new file mode 100644 index 00000000000..88f45788b83 --- /dev/null +++ b/.agents/skills/nemoclaw-user-configure-inference/references/declarative-agents-manifest.md @@ -0,0 +1,160 @@ +# Declarative Multi-Agent Manifest + +NemoClaw can bake a multi-agent OpenClaw layout into a sandbox image from a single checked-in manifest. +Supply the manifest at onboard time with `--agents ` and NemoClaw embeds the resulting `agents.list` entries, agent-specific overrides, and `agents.defaults.subagents` block into `openclaw.json` during the image build. + +The schema mirrors OpenClaw's own `agents.list[]` field names, so the same keys you read in [OpenClaw's sub-agents reference](https://docs.openclaw.ai/tools/subagents) appear verbatim in the manifest. + +## When To Use This + +Use `--agents` when: + +- You want a repeatable, GitOps-friendly multi-agent sandbox (manager + workers, or a research / writing split). +- A secondary agent needs its own model (different size, different capability profile). +- You want OpenClaw's `sessions_spawn` validator to enforce a fixed spawn allowlist, not the broad default. + +For a single primary agent on the configured inference route, no manifest is required. +The canonical `main` agent is always baked in as the default. + +## Invocation + +```bash +nemoclaw onboard --agents ./agents.yaml --name my-assistant +``` + +NemoClaw reads the manifest on the host, sets `NEMOCLAW_EXTRA_AGENTS_JSON` for the Dockerfile patcher, and the build-time validator in `scripts/generate-openclaw-config.mts` is the single source of truth for structured errors. +A malformed manifest fails the image build with a clear error message. + +## Manifest Shape + +```yaml +defaults: + subagents: + maxSpawnDepth: 2 # optional; OpenClaw allows 1..5 + +main: # optional augments to the canonical "main" agent + tools: + profile: minimal + allow: [read] + subagents: + allowAgents: [logs-reader, writer] + delegationMode: prefer + requireAgentId: true + +agents: # required when secondary agents are needed + - id: logs-reader + description: "Reads sandbox logs" + model: nvidia/nemotron-3-nano-30b + tools: + allow: [read, exec] + subagents: + requireAgentId: true + + - id: writer + model: nvidia/nemotron-3-super-120b-a12b + tools: + allow: [read, write] +``` + +### Top-Level Fields + +| Field | Purpose | Bakes Into | +|---|---|---| +| `defaults.subagents.maxSpawnDepth` | Maximum nesting depth for sub-agent spawning. Integer 1..5. | `agents.defaults.subagents.maxSpawnDepth` | +| `main.tools` | Agent-specific tool policy for the canonical `main` agent. | `agents.list[id=main].tools` | +| `main.subagents` | Sub-agent delegation policy for `main`. Same shape as a secondary agent's `subagents` block. | `agents.list[id=main].subagents` | +| `agents[]` | Secondary agents to append after `main` in `agents.list`. | `agents.list[]` | + +The `main` agent is always written first into `agents.list` with `default: true`. +Operators cannot set `default: true` on a secondary agent and cannot rename the primary slot. + +### Agent Fields + +| Field | Required | Purpose | +|---|---|---| +| `id` | yes | Lowercase alphanumeric + `_`/`-`, 1-32 chars, must start with a letter, and cannot be `main`. | +| `workspace` | auto-filled | Defaults to `/sandbox/.openclaw/workspace-`. Must match the canonical sandbox layout if supplied. | +| `agentDir` | auto-filled | Defaults to `/sandbox/.openclaw/agents/`. Must match the canonical sandbox layout if supplied. | +| `tools` | yes | `{profile?, allow?, deny?}`. Must declare a non-empty `allow[]` or `deny[]`. Secondary agents inherit no tools by default. | +| `description` | no | Human-readable. Baked verbatim. | +| `model` | no | `provider/model` reference. The provider must match the onboard provider; cross-provider manifests are not supported. | +| `subagents` | no | OpenClaw-native sub-agent delegation policy. See below. | + +### Sub-Agent Delegation Block + +Both `main.subagents` and `agents[].subagents` use the same shape, which mirrors OpenClaw's [`agents.list[].subagents`](https://docs.openclaw.ai/gateway/config-agents). + +| Field | Type | Purpose | +|---|---|---| +| `delegationMode` | `"suggest"` or `"prefer"` | Prompt-only steering for how strongly this agent should delegate. No enforcement. | +| `allowAgents` | `string[]` | Allowlist of agent ids this agent may target through `sessions_spawn`. `["*"]` allows any configured target; omit for self-only. | +| `model` | `provider/model` | Default model for spawned sub-agents. Provider must match the onboard provider. | +| `thinking` | string | Default thinking level for spawned sub-agents. | +| `requireAgentId` | boolean | Force the model to pass `agentId` explicitly to `sessions_spawn` rather than defaulting to self. | + +`maxSpawnDepth` is not accepted for individual agents. +OpenClaw only honors it on `agents.defaults.subagents`, so the manifest exposes it only under the top-level `defaults` block. + +### Multi-Model Sandboxes + +When a secondary agent declares its own `model` (or `subagents.model`), NemoClaw widens the baked `models.providers[].models[]` array with one entry for each unique `provider/model` reference. +The base `contextWindow`, `maxTokens`, `reasoning`, and `input` settings from the onboard route apply to each appended entry. +Model-specific overrides beyond these defaults are out of scope for v1. +Edit the generated `openclaw.json` in place if you need finer control. + +## Manager-Worker Example + +```yaml +defaults: + subagents: + maxSpawnDepth: 2 + +main: + subagents: + allowAgents: [logs-reader] + delegationMode: prefer + requireAgentId: true + +agents: + - id: logs-reader + description: "Reads /var/log and surfaces error lines" + tools: + allow: [read] +``` + +What this produces in the baked `openclaw.json`: + +- `agents.list[0]` is `main` with `default: true`, the operator-supplied `tools`/`subagents` merged in. +- `agents.list[1]` is `logs-reader` at the canonical workspace/agentDir paths. +- The primary model stays whatever was selected at onboard. +- `agents.defaults.subagents.maxSpawnDepth` is `2`. +- `sessions_spawn` from `main` resolves to `logs-reader` only. + +## Iterating + +Edit `agents.yaml`, re-run `nemoclaw onboard --agents ./agents.yaml --recreate-sandbox`. +Workspaces under `/sandbox/.openclaw/workspace-` are preserved across rebuilds because the runtime startup script provisions them on first boot rather than baking their contents. + +For interactive agent-specific edits inside an existing sandbox with no rebuild, use the in-sandbox CLI, `nemoclaw agents add|delete|list`. +The manifest path is for fixed, checked-in layouts; the CLI passthrough is for interactive work. + +## Apply To An Existing Sandbox + +`nemoclaw agents apply -f ` reconciles the live sandbox roster against the manifest **without a rebuild**. +The verb lists current agents with `openclaw agents list --json`, diffs them against the manifest, and drives `openclaw agents add|delete` for each item. +Agent-specific `model`, `subagents.*`, top-level `defaults`, and `main` overrides require a sandbox rebuild and are reported as warnings the verb prints before exit; rerun `nemoclaw onboard --agents --recreate-sandbox` to bake those. + +```bash +nemoclaw my-assistant agents apply -f ./agents.yaml --yes +``` + +The flag pair `--yes / --non-interactive` is required for scripted use: `--yes` confirms the printed roster diff, and `--non-interactive` makes the verb fail fast when `--yes` is absent rather than waiting for an interactive prompt that scripted callers cannot deliver. + +## Next Steps + +Use the following resources for more information: + +- Use [OpenClaw Sub-Agents](https://docs.openclaw.ai/tools/subagents) for runtime semantics of `sessions_spawn`, `subagents.allowAgents`, and nesting depth. +- Use [Set Up Task-Specific Sub-Agents](set-up-sub-agent.md) for the in-sandbox path that edits `agents.list` directly without a rebuild. +- Use [Switch Inference Providers](switch-inference-providers.md) before changing agent-specific `model` refs, since refs must share the primary onboard provider. +- Use Workspace Files (use the `nemoclaw-user-manage-sandboxes` skill) to learn how agent-specific `workspace-` directories are provisioned and persisted across rebuilds. diff --git a/.agents/skills/nemoclaw-user-configure-inference/references/inference-options.md b/.agents/skills/nemoclaw-user-configure-inference/references/inference-options.md index 634b4c6c43e..aedd5a8f27c 100644 --- a/.agents/skills/nemoclaw-user-configure-inference/references/inference-options.md +++ b/.agents/skills/nemoclaw-user-configure-inference/references/inference-options.md @@ -33,15 +33,15 @@ NemoClaw uses provider-specific local tokens for those routes, and rebuilds of l |----------|--------|---------------|-------| | NVIDIA Endpoints | Tested | OpenAI-compatible | Hosted models on integrate.api.nvidia.com | | OpenAI | Tested | Native OpenAI-compatible | Uses OpenAI model IDs | -| Other OpenAI-compatible endpoint | Tested | Custom OpenAI-compatible | For compatible proxies and gateways | +| Other OpenAI-compatible endpoint | Tested with limitations | Custom OpenAI-compatible | Adapter path validated with OpenRouter (`https://openrouter.ai`, see `src/lib/onboard.ts:3673`). Behavior on other OpenAI-compatible proxies, gateways, and self-hosted implementations may vary; this row claims the adapter, not the universe of compatible endpoints. | | Anthropic | Tested | Native Anthropic | Uses anthropic-messages | -| Other Anthropic-compatible endpoint | Tested | Custom Anthropic-compatible | For Claude proxies and compatible gateways | +| Other Anthropic-compatible endpoint | Tested with limitations | Custom Anthropic-compatible | Adapter path validated with AWS Bedrock (`src/lib/onboard/bedrock-runtime.ts`). Behavior on other Anthropic-compatible proxies and gateways may vary; this row claims the adapter, not the universe of compatible endpoints. | | Google Gemini | Tested | OpenAI-compatible | Uses Google's OpenAI-compatible endpoint | | Hermes Provider | Hermes only | OpenAI-compatible route | Available when onboarding Hermes Agent through `nemohermes` | -| Local Ollama | Caveated | Local Ollama API | Available when Ollama is installed or running on the host | -| Local NVIDIA NIM | Experimental | Local OpenAI-compatible | Requires `NEMOCLAW_EXPERIMENTAL=1` and a NIM-capable GPU | -| Local vLLM (already running) | Caveated | Local OpenAI-compatible | Appears in the onboarding menu when NemoClaw detects a server already on `localhost:8000`. No flag required. | -| Local vLLM (managed install/start) | Caveated | Local OpenAI-compatible | Appears by default on DGX Spark and DGX Station. Generic Linux NVIDIA GPU hosts require `NEMOCLAW_EXPERIMENTAL=1` or `NEMOCLAW_PROVIDER=install-vllm`. NemoClaw pulls/starts a vLLM container on a supported NVIDIA GPU host. | +| Local Ollama | Tested with limitations | Local Ollama API | Available when Ollama is installed or running on the host. Validated default models: `qwen3.6:35b` (high VRAM), `nemotron-3-nano:30b` (medium VRAM), `qwen3.5:9b` (low VRAM fallback). | +| Local NVIDIA NIM | Experimental | Local OpenAI-compatible | Requires `NEMOCLAW_EXPERIMENTAL=1` and a NIM-capable NVIDIA GPU. Host must have the NVIDIA Container Toolkit installed and a CDI spec present (`onboard` asserts CDI presence with `assertCdiNvidiaGpuSpecPresent`, `src/lib/onboard.ts:1581`). NIM images pull from `nvcr.io` and require NGC registry login. NemoClaw gates this path behind the experimental flag because it does not auto-select a NIM image for the host today. You must explicitly pick from the validated image list. Managed vLLM has host-specific default models and is not gated on the same boxes. Validated images referenced in `src/lib/inference/config.ts` and `nemoclaw/src/index.ts`: `nvidia/nemotron-3-super-120b-a12b` (default cloud model), `nvidia/nemotron-3-nano-30b-a3b`, `nvidia/llama-3.3-nemotron-super-49b-v1.5`. | +| Local vLLM (already running) | Tested with limitations | Local OpenAI-compatible | Appears in the onboarding menu when NemoClaw detects a server already on `localhost:8000`. No flag required. Model is whatever the existing server serves. | +| Local vLLM (managed install/start) | Tested with limitations | Local OpenAI-compatible | Appears by default on DGX Spark and DGX Station. Generic Linux NVIDIA GPU hosts require `NEMOCLAW_EXPERIMENTAL=1` or `NEMOCLAW_PROVIDER=install-vllm`. Host must have the NVIDIA Container Toolkit installed and a CDI spec present (`onboard` asserts CDI presence). NemoClaw pulls or starts the stable NGC vLLM container for each host profile. See `src/lib/inference/vllm.ts:55,177` for the pins. DGX Spark and DGX Station use `nvcr.io/nvidia/vllm:26.05.post1-py3`; generic Linux NVIDIA GPU hosts use `nvcr.io/nvidia/vllm:26.03.post1-py3`. Validated defaults are listed in `src/lib/inference/vllm-models.ts`: DGX Spark uses `nvidia/Qwen3.6-35B-A3B-NVFP4`, DGX Station uses `Qwen/Qwen3.6-27B-FP8`, and Linux NVIDIA GPU uses `nvidia/NVIDIA-Nemotron-3-Nano-4B-FP8`. Image pulls require NGC registry login (`docker login nvcr.io`); onboard prompts for the NGC API key when authentication is missing. | ## Provider Options diff --git a/.agents/skills/nemoclaw-user-configure-inference/references/set-up-sub-agent.md b/.agents/skills/nemoclaw-user-configure-inference/references/set-up-sub-agent.md index a6e1133cabf..fe610b6a0ee 100644 --- a/.agents/skills/nemoclaw-user-configure-inference/references/set-up-sub-agent.md +++ b/.agents/skills/nemoclaw-user-configure-inference/references/set-up-sub-agent.md @@ -40,6 +40,12 @@ The primary orchestration model remains responsible for conversation, planning, ## Update the Sandbox Config +**Note:** + +Finish the Quickstart (use the `nemoclaw-user-get-started` skill) and start the target sandbox before you run the `docker exec` commands in this section. +These commands run on the host that owns the sandbox containers and discover the running sandbox container from the `openshell.ai/sandbox-name` Docker label. +If you have not created a sandbox yet, onboard one first, such as `my-assistant`. + Fetch the current OpenClaw config from the sandbox, patch it with your auxiliary provider and `agents.list` changes, then upload it back. On Docker-driver sandboxes, run these commands from the host that owns the sandbox containers. The container name includes a runtime suffix, so discover it from the OpenShell sandbox label: @@ -47,11 +53,37 @@ The container name includes a runtime suffix, so discover it from the OpenShell ```bash export SANDBOX=my-assistant export SANDBOX_CTR=$(docker ps --filter "label=openshell.ai/sandbox-name=$SANDBOX" --format "{{.Names}}" | sed -n '1p') -docker exec --user root "$SANDBOX_CTR" cat /sandbox/.openclaw/openclaw.json > /tmp/openclaw.json +if [ -z "$SANDBOX_CTR" ]; then + echo "No running sandbox container found for $SANDBOX. Start the sandbox before editing its config." + exit 1 +fi +umask 077 +WORK_DIR=$(mktemp -d -t nemoclaw-subagent-XXXXXX) +trap 'rm -rf "$WORK_DIR"' EXIT +docker exec --user root "$SANDBOX_CTR" cat /sandbox/.openclaw/openclaw.json > "$WORK_DIR/openclaw.json" ``` -Create `/tmp/openclaw.updated.json` with the OpenClaw sub-agent config. +If `SANDBOX_CTR` is empty, the sandbox is not running on this host. +Start the sandbox, confirm that `docker ps` shows the matching `openshell.ai/sandbox-name` label, then rerun the export commands before continuing. + +Produce the patched OpenClaw sub-agent config in the same mode-0600 temp directory. For the Omni example, the demo provides `vlm-demo/vlm-subagent/openclaw-patch.py`. +Set `VLM_DEMO_DIR` to the local `vlm-demo` directory from the demo assets, then run the patch helper: + +```bash +export VLM_DEMO_DIR=/path/to/nemoclaw-demos/vlm-demo +NVIDIA_API_KEY="$NVIDIA_API_KEY" python3 "$VLM_DEMO_DIR/vlm-subagent/openclaw-patch.py" \ + < "$WORK_DIR/openclaw.json" > "$WORK_DIR/openclaw.updated.json" +``` + +The helper reads `NVIDIA_API_KEY` from the environment (so the key avoids argv and shell history), reads the unmodified config from `$WORK_DIR/openclaw.json`, adds the Omni provider and `vision-operator` entry, and writes the patched config to a mode-0600 temp file under `$WORK_DIR`. +The `trap` cleans up the temp directory on shell exit so the patched JSON does not linger on disk. +Do not commit the patched config or any other file that contains a real API key. + +**Warning:** + +The auxiliary sub-agent path writes a real provider key into sandbox state at `/sandbox/.openclaw/agents//agent/auth-profiles.json`. That file sits outside NemoClaw's normal host-side OpenShell credential-store boundary, so a snapshot, backup, or cloned sandbox image carries the key with it. Use this flow only when the normal host-side credential route cannot serve the auxiliary provider, and treat the affected sandbox as credential-bearing. +Environment-delivered keys also remain readable from `/proc` by same-user or root processes on most Linux configurations; this pattern avoids argv and shell history, not all process inspection. Prefer a stdin or mode-0600 input file when the demo helper supports it. Upload the patched config and refresh the hash. In the default mutable state, this keeps the local hash consistent but does not make it tamper-proof. @@ -60,14 +92,28 @@ Use NemoClaw runtime controls when the sandbox needs a hardened config posture a ```bash docker exec --user root "$SANDBOX_CTR" chmod 644 /sandbox/.openclaw/openclaw.json docker exec --user root "$SANDBOX_CTR" chmod 644 /sandbox/.openclaw/.config-hash -docker exec --user root -i "$SANDBOX_CTR" sh -c 'cat > /sandbox/.openclaw/openclaw.json' < /tmp/openclaw.updated.json +docker exec --user root -i "$SANDBOX_CTR" sh -c 'cat > /sandbox/.openclaw/openclaw.json' < "$WORK_DIR/openclaw.updated.json" docker exec --user root "$SANDBOX_CTR" /bin/bash -c "cd /sandbox/.openclaw && sha256sum openclaw.json > .config-hash" docker exec --user root "$SANDBOX_CTR" chown sandbox:sandbox /sandbox/.openclaw/openclaw.json /sandbox/.openclaw/.config-hash docker exec --user root "$SANDBOX_CTR" chmod 444 /sandbox/.openclaw/openclaw.json docker exec --user root "$SANDBOX_CTR" chmod 444 /sandbox/.openclaw/.config-hash ``` -Check `/tmp/gateway.log` after upload and confirm the gateway hot-reloaded the provider or `agents.list` change. +Check `/tmp/gateway.log` after upload and confirm the gateway hot-reloaded the provider or `agents.list` change: + +```bash +nemoclaw "$SANDBOX" logs --since 5m --tail 200 +nemoclaw "$SANDBOX" agents list --json +``` + +Expected output: + +```text +config change detected; evaluating reload (...) +config hot reload applied (...) +``` + +The `agents list` output should include `vision-operator`. ## Add Sub-Agent Credentials @@ -79,6 +125,19 @@ For the Omni example: ``` Use the same provider ID that appears in `models.providers`, such as `nvidia-omni`. +Create the auth profile in the same mode-0600 work directory used above (so the trap from the patch step also cleans this file up on exit), then upload it into the sandbox. +The example below pulls `$NVIDIA_API_KEY` from the environment and writes the auth profile through `envsubst` so the key never appears in argv or shell history: + +```bash +docker exec --user root "$SANDBOX_CTR" mkdir -p /sandbox/.openclaw/agents/vision-operator/agent +NVIDIA_API_KEY="$NVIDIA_API_KEY" envsubst '$NVIDIA_API_KEY' < "$VLM_DEMO_DIR/vlm-subagent/auth-profiles.template.json" \ + > "$WORK_DIR/auth-profiles.json" +docker exec --user root -i "$SANDBOX_CTR" sh -c 'cat > /sandbox/.openclaw/agents/vision-operator/agent/auth-profiles.json' < "$WORK_DIR/auth-profiles.json" +docker exec --user root "$SANDBOX_CTR" chmod 600 /sandbox/.openclaw/agents/vision-operator/agent/auth-profiles.json +``` + +The `'$NVIDIA_API_KEY'` argument to `envsubst` is an allowlist: only that one variable is expanded in the template. Any other `$VAR` references the demo template uses for unrelated text are left intact, so a stray placeholder cannot accidentally pull in another environment variable. + After uploading the auth profile, make sure the sandbox user owns the sub-agent directory: ```bash diff --git a/.agents/skills/nemoclaw-user-get-started/SKILL.md b/.agents/skills/nemoclaw-user-get-started/SKILL.md index 0447987d369..bcb3afb0003 100644 --- a/.agents/skills/nemoclaw-user-get-started/SKILL.md +++ b/.agents/skills/nemoclaw-user-get-started/SKILL.md @@ -1,6 +1,6 @@ --- name: "nemoclaw-user-get-started" -description: "Installs NemoClaw, launches a sandbox, and runs the first agent prompt. Use when onboarding, installing, or launching a NemoClaw sandbox for the first time. Trigger keywords - nemoclaw quickstart, install nemoclaw openclaw sandbox, nemohermes quickstart, hermes agent nemoclaw, run hermes openshell sandbox, nemoclaw prerequisites, nemoclaw supported platforms, nemoclaw hardware software, nemoclaw windows wsl2 setup, nemoclaw install windows docker desktop." +description: "Installs NemoClaw, launches a sandbox, and runs the first agent prompt. Use when onboarding, installing, or launching a NemoClaw sandbox for the first time. Trigger keywords - nemoclaw quickstart, install nemoclaw openclaw sandbox, nemohermes quickstart, hermes agent nemoclaw, run hermes openshell sandbox, nemoclaw prerequisites, nemoclaw supported platforms, nemoclaw hardware software, langchain deep agents code nemoclaw, dcode openshell sandbox, langchain coding agent, nemoclaw windows wsl2 setup, nemoclaw install windows docker desktop." license: "Apache-2.0" --- @@ -262,6 +262,7 @@ openclaw tui - **Load [references/quickstart-hermes.md](references/quickstart-hermes.md)** when users ask for Hermes setup, NemoHermes onboarding, or running Hermes inside OpenShell. Installs NemoClaw, selects the Hermes agent, and launches a sandboxed Hermes dashboard and API endpoint. - **Load [references/prerequisites.md](references/prerequisites.md)** when verifying prerequisites before installation. Lists the hardware, software, and container runtime requirements for running NemoClaw. +- **Load [references/quickstart-langchain-deepagents-code.md](references/quickstart-langchain-deepagents-code.md)** when testing dcode with NemoClaw-managed inference. Creates a NemoClaw sandbox that runs LangChain Deep Agents Code as a terminal harness. - **Load [references/windows-preparation.md](references/windows-preparation.md)** when preparing a Windows machine for NemoClaw, enabling WSL 2, configuring Docker Desktop for Windows, or troubleshooting a Windows-specific install error. Covers Windows-only preparation steps required before the Quickstart. ## Related Skills diff --git a/.agents/skills/nemoclaw-user-get-started/references/prerequisites.md b/.agents/skills/nemoclaw-user-get-started/references/prerequisites.md index 4e7b25437f9..8efdd86df34 100644 --- a/.agents/skills/nemoclaw-user-get-started/references/prerequisites.md +++ b/.agents/skills/nemoclaw-user-get-started/references/prerequisites.md @@ -62,12 +62,13 @@ Refer to the troubleshooting guide (use the `nemoclaw-user-reference` skill) for The following table lists tested platform and runtime combinations. Availability is not limited to these entries, but untested configurations can have issues. +For the full canonical matrix including deferred platforms, inference providers, agents, messaging integrations, and deployment paths, see Platform Support and Launch Claims (use the `nemoclaw-user-reference` skill). The table comes from [`ci/platform-matrix.json`](https://github.com/NVIDIA/NemoClaw/blob/main/ci/platform-matrix.json), the single source of truth kept in sync by CI and QA. | OS | Container runtime | Status | Notes | |----|-------------------|--------|-------| -| 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. | +| Linux | Docker | Tested | Primary tested path. Ubuntu 24.04 is the validated distro in production source (`DEFAULT_COMPAT_IMAGE` in `src/lib/onboard/docker-driver-gateway-launch.ts:10` and the preflight tests pin 24.04 only); the installer's package-manager probes assume apt-get. Other distros (Ubuntu 22.04, Fedora, Rocky, Alma, NixOS, Arch) may work but are not validated. | +| macOS (Apple Silicon) | Colima, Docker Desktop | Tested with limitations | Start the container runtime (Colima or Docker Desktop) before running the installer. Xcode Command Line Tools (`xcode-select --install`) are typically required for Node native modules during install. NemoClaw recommends them but does not enforce them during preflight. | | 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. | diff --git a/.agents/skills/nemoclaw-user-get-started/references/quickstart-langchain-deepagents-code.md b/.agents/skills/nemoclaw-user-get-started/references/quickstart-langchain-deepagents-code.md new file mode 100644 index 00000000000..8e32db52c92 --- /dev/null +++ b/.agents/skills/nemoclaw-user-get-started/references/quickstart-langchain-deepagents-code.md @@ -0,0 +1,65 @@ +# Quickstart with LangChain Deep Agents Code + +Use this guide when you want NemoClaw to build an OpenShell sandbox with the `dcode` terminal coding agent installed and configured for NemoClaw-managed inference. + +## Onboard + +Run onboarding with the canonical agent ID. + +```bash +nemoclaw onboard --agent langchain-deepagents-code +``` + +The image installs a hash-locked, pinned Deep Agents Code release with NVIDIA provider support. +NemoClaw writes `/sandbox/.deepagents/config.toml` with an OpenAI-compatible provider pointed at `https://inference.local/v1`, uses a scoped placeholder API key for that managed route, and sets `use_responses_api = false` for Chat Completions compatibility. +NemoClaw/OpenShell keeps real provider credentials in credential handling and does not write them into the Deep Agents config file. + +## Use the Harness + +Connect to the sandbox, then launch the terminal UI. + +```bash +nemoclaw connect +dcode +``` + +For a single headless task, run: + +```bash +dcode -n "Summarize this repository" +``` + +The managed wrapper launches Deep Agents Code with `HOME=/sandbox`, update checks disabled, remote Deep Agents sandbox providers disabled, MCP auto-loading disabled, and shell allow-list overrides blocked. + +## State and Backup + +Deep Agents Code state lives under `/sandbox/.deepagents`. +NemoClaw snapshot and rebuild flows preserve the app state directory, skills, generated config, and hooks config when those files exist. +NemoClaw intentionally does not preserve `.env` or `.mcp.json` because users may put Tavily, LangSmith, MCP service, or provider credentials there, and this managed harness disables MCP at runtime. + +## Optional Web Search + +Deep Agents Code can use Tavily web search when you provide a Tavily credential in the runtime environment. +NemoClaw does not enable Tavily or LangSmith by default for this harness. +Before you provide those credentials, add the required egress endpoints (use the `nemoclaw-user-manage-policy` skill) to the sandbox policy so optional integrations stay explicit. + +## Troubleshooting + +Use normal sandbox lifecycle commands: + +```bash +nemoclaw status +nemoclaw logs --follow +nemoclaw rebuild +nemoclaw snapshot create --name before-change +``` + +`status` reports the selected harness as a terminal runtime and prints the interactive/headless command shape. +There is no dashboard port or long-running gateway process for this harness. + +## Next Steps + +- Inference Options (use the `nemoclaw-user-configure-inference` skill) to choose a provider and model. +- Backup and Restore (use the `nemoclaw-user-manage-sandboxes` skill) for snapshot and rebuild preservation details. +- Runtime Controls (use the `nemoclaw-user-manage-sandboxes` skill) for sandbox mutability and host-side control boundaries. +- Troubleshooting (use the `nemoclaw-user-reference` skill) for common setup and runtime issues. diff --git a/.agents/skills/nemoclaw-user-manage-sandboxes/references/messaging-channels.md b/.agents/skills/nemoclaw-user-manage-sandboxes/references/messaging-channels.md index 89e87106d77..b8211b0406c 100644 --- a/.agents/skills/nemoclaw-user-manage-sandboxes/references/messaging-channels.md +++ b/.agents/skills/nemoclaw-user-manage-sandboxes/references/messaging-channels.md @@ -43,7 +43,7 @@ For details, refer to Commands (use the `nemoclaw-user-reference` skill). | Channel | Required tokens | Optional settings | |---------|-----------------|-------------------| -| Telegram | `TELEGRAM_BOT_TOKEN` | `TELEGRAM_ALLOWED_IDS` for DM allowlisting, `TELEGRAM_REQUIRE_MENTION` for group-chat replies | +| Telegram | `TELEGRAM_BOT_TOKEN` | `TELEGRAM_ALLOWED_IDS` for DM allowlisting, `TELEGRAM_REQUIRE_MENTION` for group-chat replies, `TELEGRAM_GROUP_POLICY` for OpenClaw group access | | 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 | @@ -57,12 +57,17 @@ After changing privacy mode, remove the bot from each Telegram group and add it For compatibility with older QA scripts, NemoClaw also treats `TELEGRAM_AUTHORIZED_CHAT_IDS` and `TELEGRAM_CHAT_ID` as aliases, but new automation should use `TELEGRAM_ALLOWED_IDS`. Keep these aliases until QA automation and public repro templates have stopped exporting them for at least one full release. Group chats stay open by default so rebuilt sandboxes do not silently drop Telegram group messages because of an empty group allowlist. -Set `TELEGRAM_REQUIRE_MENTION=1` to make the bot reply in Telegram groups only when users mention it. +NemoClaw defaults `TELEGRAM_GROUP_POLICY` to `open` for OpenClaw. +Set `TELEGRAM_GROUP_POLICY=allowlist` to block OpenClaw group chats until explicit group entries are configured, or `TELEGRAM_GROUP_POLICY=disabled` to disable OpenClaw Telegram group access. +Hermes does not have an equivalent disable-groups policy; `TELEGRAM_ALLOWED_IDS` maps to Hermes `TELEGRAM_ALLOWED_USERS`, which authorizes those users across DMs, groups, and forums. +NemoClaw defaults `TELEGRAM_REQUIRE_MENTION` to `1`, so the bot replies in Telegram groups only when users mention it. +Set `TELEGRAM_REQUIRE_MENTION=0` when you want the bot to reply to all group messages. Pairing and `TELEGRAM_ALLOWED_IDS` still govern direct messages. Discord uses a bot token from the Discord Developer Portal. For server channels, enable Developer Mode in Discord, right-click the server, and copy the Server ID into `DISCORD_SERVER_ID`. By default, NemoClaw configures the bot to reply only when mentioned. +If `DISCORD_SERVER_ID` is set and `DISCORD_REQUIRE_MENTION` is unset, NemoClaw defaults `DISCORD_REQUIRE_MENTION` to `1`. Set `DISCORD_REQUIRE_MENTION=0` if you want it to reply to all messages in the configured server. Set `DISCORD_USER_ID` to restrict access to one user; otherwise, any member of the configured server can message the bot. @@ -190,7 +195,9 @@ Verify the gateway bridge before relying on the channel. 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. +If you need optional channel settings such as `TELEGRAM_ALLOWED_IDS`, `TELEGRAM_REQUIRE_MENTION`, `TELEGRAM_GROUP_POLICY`, `DISCORD_SERVER_ID`, `DISCORD_USER_ID`, `DISCORD_REQUIRE_MENTION`, `SLACK_ALLOWED_USERS`, or `SLACK_ALLOWED_CHANNELS`, export them before the rebuild starts. +You can omit `TELEGRAM_REQUIRE_MENTION` and `DISCORD_REQUIRE_MENTION` when you want the default mention-only mode. +You can omit `TELEGRAM_GROUP_POLICY` when you want OpenClaw Telegram group access to stay open. Telegram Bot API `sendMessage` calls prove outbound delivery from the bot; to test inbound agent replies, send a message from the Telegram client as an allowed user. 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: @@ -200,6 +207,8 @@ nemoclaw my-assistant rebuild ``` In non-interactive mode, set the required environment variables before running `channels add`. +Optional mention-mode settings that declare defaults are still written when unset. +Telegram mention mode defaults to `1`; Discord mention mode defaults to `1` when `DISCORD_SERVER_ID` is set. Missing credentials fail fast, and the command queues the change for a manual rebuild: ```bash diff --git a/.agents/skills/nemoclaw-user-overview/references/overview.md b/.agents/skills/nemoclaw-user-overview/references/overview.md index 87d325c07ad..eeb96574cb7 100644 --- a/.agents/skills/nemoclaw-user-overview/references/overview.md +++ b/.agents/skills/nemoclaw-user-overview/references/overview.md @@ -11,6 +11,8 @@ NemoClaw pairs hosted models on inference providers or local endpoints with a ha The sandbox runtime comes from [NVIDIA OpenShell](https://github.com/NVIDIA/OpenShell). NemoClaw adds the blueprint, CLI, onboarding, and related tooling as the reference way to run supported agents there. +For the canonical list of what NemoClaw supports today across platforms, inference providers, agents, messaging integrations, and deployment paths, see Platform Support and Launch Claims (use the `nemoclaw-user-reference` skill). + | Capability | Description | |-------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------| | Sandbox supported agents | Creates an OpenShell sandbox pre-configured for your selected agent, with filesystem and network policies applied from the first boot. | diff --git a/.agents/skills/nemoclaw-user-overview/references/release-notes.md b/.agents/skills/nemoclaw-user-overview/references/release-notes.md index 990bc98b990..ad6644935c9 100644 --- a/.agents/skills/nemoclaw-user-overview/references/release-notes.md +++ b/.agents/skills/nemoclaw-user-overview/references/release-notes.md @@ -5,6 +5,7 @@ import { AgentOnly } from "../_components/AgentGuide"; NVIDIA NemoClaw is available in early preview starting March 16, 2026. Use this page to track the highlights of the latest release. For more detailed release notes, refer to the [NemoClaw GitHub announcements](https://github.com/NVIDIA/NemoClaw/discussions/categories/announcements?discussions_q=is%3Aopen+category%3AAnnouncements). +For the canonical list of supported platforms, providers, agents, integrations, and deployment paths with explicit status for each row, see Platform Support and Launch Claims (use the `nemoclaw-user-reference` skill). ## v0.0.65 @@ -12,7 +13,9 @@ NemoClaw v0.0.65 improves gateway recovery, sandbox state restore, local inferen - Gateway and sandbox recovery now wait for sustained serving state, recover sandboxes whose active gateway has lost its spec, preserve gateway routing state across more rebuilds, and allocate dashboard ports across multiple NemoClaw gateways. For more information, refer to Manage Sandbox Lifecycle (use the `nemoclaw-user-manage-sandboxes` skill) and Troubleshooting (use the `nemoclaw-user-reference` skill). - Rebuild and restore flows preserve more OpenClaw and registry state. Config restore fails closed when a merge cannot be applied safely, reporter-owned model metadata survives rebuild restore, Shields auto-restore locks are re-confirmed after settle, and persisted agents survive registry recovery. For more information, refer to Backup and Restore (use the `nemoclaw-user-manage-sandboxes` skill) and NemoClaw CLI Commands Reference (use the `nemoclaw-user-reference` skill). -- Onboarding and inference setup fail earlier with clearer diagnostics. NemoClaw now handles Docker Desktop WSL CDI injection failures, surfaces silent OpenClaw runtime fallback, preflights managed vLLM model selection before side effects, accepts managed vLLM extra serve arguments, bounds compatible-endpoint probes, summarizes inference validation failures, and recomputes context windows after runtime model switches. For more information, refer to Troubleshooting (use the `nemoclaw-user-reference` skill), NemoClaw Inference Options (use the `nemoclaw-user-configure-inference` skill), and Switch Inference Providers (use the `nemoclaw-user-configure-inference` skill). +- Onboarding and inference setup fail earlier with clearer diagnostics. + NemoClaw now handles Docker Desktop WSL CDI injection failures, surfaces silent OpenClaw runtime fallback, preflights managed vLLM model selection before side effects, accepts managed vLLM extra serve arguments, aligns the DGX Spark Qwen3.6 NVFP4 managed-vLLM recipe with NVIDIA's current model card (`qwen3_xml`, `--max-model-len 262144`, `--gpu-memory-utilization 0.4`, and no Spark-specific serve environment exports), bounds compatible-endpoint probes, summarizes inference validation failures, and recomputes context windows after runtime model switches. + For more information, refer to Troubleshooting (use the `nemoclaw-user-reference` skill), NemoClaw Inference Options (use the `nemoclaw-user-configure-inference` skill), and Switch Inference Providers (use the `nemoclaw-user-configure-inference` skill). - Day-two CLI operations gained safer file and session workflows. `nemoclaw download`, `nemoclaw upload`, and `nemoclaw sessions export` wrap the underlying sandbox file transfer and OpenClaw session export paths, while uninstall handles TTY confirmation and model-router teardown more predictably. For more information, refer to NemoClaw CLI Commands Reference (use the `nemoclaw-user-reference` skill) and Manage Sandbox Lifecycle (use the `nemoclaw-user-manage-sandboxes` skill). - Messaging activation stores and exposes less credential-adjacent state. NemoClaw avoids logging WeChat QR poll tokens, resolves Discord per-account proxy settings for gateway WebSocket connections, compacts persisted messaging plans, completes manifest-based channel migration, and removes provider credential hashes from sandbox registry entries. For more information, refer to Messaging Channels (use the `nemoclaw-user-manage-sandboxes` skill) and Credential Storage (use the `nemoclaw-user-configure-security` skill). - Hermes defaults and sandbox compatibility are narrower and easier to recover. The Hermes baseline policy no longer includes GitHub by default, NemoClaw reserves Hermes port `8642` across agent variants, and spawned OpenClaw sub-agents dial back through the sandbox interface instead of blocked loopback paths. For more information, refer to Network Policies (use the `nemoclaw-user-reference` skill), NemoClaw Quickstart with Hermes (use the `nemoclaw-user-get-started` skill), and Set Up Task-Specific Sub-Agents (use the `nemoclaw-user-configure-inference` skill). diff --git a/.agents/skills/nemoclaw-user-reference/SKILL.md b/.agents/skills/nemoclaw-user-reference/SKILL.md index 6d57867d78c..84920edbc89 100644 --- a/.agents/skills/nemoclaw-user-reference/SKILL.md +++ b/.agents/skills/nemoclaw-user-reference/SKILL.md @@ -1,6 +1,6 @@ --- name: "nemoclaw-user-reference" -description: "Describes the NemoClaw integration layer and blueprint architecture and how they orchestrate compatible agent sandboxes. Use when looking up architecture, agent integration, plugin structure, or blueprint design. Trigger keywords - nemoclaw architecture, nemoclaw agent architecture, nemoclaw plugin blueprint structure, nemoclaw vs openshell, which cli, nemoclaw cli, openshell cli, sandbox commands, nemoclaw cli commands, nemoclaw command reference, nemoclaw network policy, sandbox egress control operator approval, nemoclaw troubleshooting, nemoclaw debug sandbox issues." +description: "Describes the NemoClaw integration layer and blueprint architecture and how they orchestrate compatible agent sandboxes. Use when looking up architecture, agent integration, plugin structure, or blueprint design. Trigger keywords - nemoclaw architecture, nemoclaw agent architecture, nemoclaw plugin blueprint structure, nemoclaw vs openshell, which cli, nemoclaw cli, openshell cli, sandbox commands, nemoclaw cli commands, nemoclaw command reference, nemoclaw enterprise readiness, nemoclaw support boundaries, nemoclaw admin capabilities, nemoclaw control plane, nemoclaw network policy, sandbox egress control operator approval, nemoclaw platform support, nemoclaw launch claims, nemoclaw support matrix, nemoclaw what is supported, nemoclaw status, nemoclaw troubleshooting, nemoclaw debug sandbox issues." license: "Apache-2.0" --- @@ -11,5 +11,7 @@ license: "Apache-2.0" - **Load [references/architecture.md](references/architecture.md)** when looking up architecture, agent integration, plugin structure, or blueprint design. Describes the NemoClaw integration layer and blueprint architecture and how they orchestrate compatible agent sandboxes. - **Load [references/cli-selection-guide.md](references/cli-selection-guide.md)** when user asks to decide whether to use `$$nemoclaw` or `openshell`. Explains when to use `$$nemoclaw` versus `openshell` for NemoClaw-managed sandboxes, including lifecycle, inference, policy, monitoring, file transfer, and gateway operations. - **Load [references/commands.md](references/commands.md)** when looking up a specific `$$nemoclaw`, `nemohermes`, or `/nemoclaw` subcommand, flag, argument, or exit code. Includes the full CLI reference for standalone NemoClaw commands and agent-specific in-sandbox commands. +- **Load [references/enterprise-readiness.md](references/enterprise-readiness.md)** when answering enterprise evaluation, support-boundary, or admin-capability questions, or when preparing field and customer conversations about what NemoClaw supports today. Classifies NemoClaw enterprise readiness and admin/control-plane capabilities by current support state, with workarounds and tracked issues. - **Load [references/network-policies.md](references/network-policies.md)** when looking up a specific default endpoint, filesystem path, or the runtime approval sequence NemoClaw applies on blocked requests. Covers the baseline network policy, filesystem rules, and operator approval flow. +- **Load [references/platform-support.md](references/platform-support.md)** when verifying whether a platform, inference provider, agent, messaging integration, or deployment path is validated, partially validated, experimental, or out of scope before relying on it in docs, demos, sales material, or support conversations. Single source of truth for what NemoClaw supports today. - **Load [references/troubleshooting.md](references/troubleshooting.md)** when diagnosing a reported NemoClaw error, a failed onboard, or unexpected sandbox behavior. Lists fixes for common installation, onboarding, and runtime issues. diff --git a/.agents/skills/nemoclaw-user-reference/references/architecture.md b/.agents/skills/nemoclaw-user-reference/references/architecture.md index 0593eec89ca..cc2f544c05e 100644 --- a/.agents/skills/nemoclaw-user-reference/references/architecture.md +++ b/.agents/skills/nemoclaw-user-reference/references/architecture.md @@ -139,6 +139,9 @@ The concrete files differ by agent because each runtime has its own plugin syste | Hermes | `agents/hermes/manifest.yaml`, `agents/hermes/plugin/plugin.yaml`, `agents/hermes/generate-config.ts`, `agents/hermes/config/`, and `agents/hermes/start.sh` | Declares the Hermes agent contract, installs the NemoClaw Hermes plugin, writes `/sandbox/.hermes/config.yaml` and `/sandbox/.hermes/.env`, and launches `hermes gateway run` behind the OpenShell proxy. | The OpenClaw integration is a thin TypeScript plugin that runs in-process with the OpenClaw gateway inside the sandbox. +Its durable entry points are `nemoclaw/src/index.ts`, `nemoclaw/src/runtime-context.ts`, and `nemoclaw/openclaw.plugin.json`. +The `nemoclaw/src/commands/` directory contains in-sandbox `/nemoclaw` command handlers and migration helpers. +The `nemoclaw/src/blueprint/` directory contains runner, state, snapshot, SSRF, and private-network validation code. Before an OpenClaw turn starts, the plugin prepends a short system-context block with the active sandbox name, sandbox phase, network policy summary, and filesystem policy summary. This guidance stays out of the visible chat transcript. When the policy or phase changes during a session, the plugin sends a smaller update block instead of repeating the full context. @@ -172,6 +175,7 @@ The current blueprint runner implementation lives in the `nemoclaw/` TypeScript nemoclaw/src/blueprint/ ├── runner.ts CLI runner: plan / apply / status / rollback ├── ssrf.ts SSRF endpoint validation (IP + DNS checks) +├── private-networks.ts Shared private-network block list loader for SSRF checks ├── snapshot.ts Migration snapshot / restore lifecycle ├── state.ts Persistent run state management ``` @@ -246,6 +250,7 @@ The following environment variables configure optional services and local access |---|---| | `TELEGRAM_BOT_TOKEN` | Telegram bot token you provide before `nemoclaw onboard`. OpenShell stores it in a provider; the sandbox receives placeholders, not the raw secret. | | `TELEGRAM_ALLOWED_IDS` | Comma-separated Telegram user or chat IDs for allowlists when onboarding applies channel restrictions. | +| `TELEGRAM_GROUP_POLICY` | OpenClaw Telegram group access policy: `open` by default, `allowlist` to require explicit group entries, or `disabled` to turn off OpenClaw group access. Hermes ignores this value. | | `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. | diff --git a/.agents/skills/nemoclaw-user-reference/references/commands.md b/.agents/skills/nemoclaw-user-reference/references/commands.md index 338cbeb2dbf..b18a2622b4e 100644 --- a/.agents/skills/nemoclaw-user-reference/references/commands.md +++ b/.agents/skills/nemoclaw-user-reference/references/commands.md @@ -103,7 +103,7 @@ The wizard creates an OpenShell gateway, registers inference providers, builds t 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 ] [--agents ] [--control-ui-port ] [--yes | -y] [--no-ollama-autostart] [--yes-i-accept-third-party-software] ``` @@ -254,6 +254,13 @@ It also prints a `Try: ` recovery line whenever it can derive a Names that match global CLI commands (`status`, `list`, `debug`, etc.) are rejected to avoid routing conflicts. Use `--agent ` to target a specific installed agent profile during onboarding. + + +Use `--agents ` to declare secondary OpenClaw agents, `agents.defaults`, and main-agent overrides in a checked-in manifest that NemoClaw bakes into the sandbox image at build time. +See Declarative Multi-Agent Manifest (use the `nemoclaw-user-configure-inference` skill) for the schema and OpenClaw-native sub-agent field semantics. + + + Use `--control-ui-port ` to choose the host dashboard port for a sandbox. The value must be an integer from `1024` through `65535`. This flag takes precedence over `CHAT_UI_URL`, `NEMOCLAW_DASHBOARD_PORT`, the previous registry value, and the default port. @@ -273,9 +280,13 @@ If you enable Discord during onboarding, the wizard can also prompt for a Discor NemoClaw bakes those values into the sandbox image as Discord guild workspace config so the bot can respond in the selected server, not just in DMs. If you leave the Discord User ID blank, the guild config omits the user allowlist and any member of the configured server can message the bot. Guild responses remain mention-gated by default unless you opt into all-message replies. +If `DISCORD_SERVER_ID` is set and `DISCORD_REQUIRE_MENTION` is unset, NemoClaw records the existing mention-only default (`DISCORD_REQUIRE_MENTION=1`). If you enable Telegram during onboarding, the wizard can also prompt for whether group chats should reply only to `@mentions` or to all group messages. -Set `TELEGRAM_REQUIRE_MENTION=1` for non-interactive onboarding when you want mention-only group replies. +Mention-only group replies are the default. +Set `TELEGRAM_REQUIRE_MENTION=0` for non-interactive onboarding when you want all group messages to trigger replies. +For OpenClaw, Telegram group access defaults to `TELEGRAM_GROUP_POLICY=open`; set `TELEGRAM_GROUP_POLICY=allowlist` or `TELEGRAM_GROUP_POLICY=disabled` before non-interactive onboarding when you want stricter group access. +Hermes does not have an equivalent disable-groups policy; `TELEGRAM_ALLOWED_IDS` maps to Hermes `TELEGRAM_ALLOWED_USERS`, which authorizes those users across DMs, groups, and forums. Pairing and `TELEGRAM_ALLOWED_IDS` still govern direct messages. If you cancel a brand-new onboarding run at the policy preset step, NemoClaw rolls back the sandbox, registry entry, and onboarding session instead of leaving a default sandbox with unfinished policy state. @@ -517,18 +528,18 @@ The exit code is the remote command's exit code. | Flag | Description | |------|-------------| -| `--workdir ` | Working directory inside the sandbox | +| `--workdir ` | Working directory inside the sandbox. The directory is checked before the command runs; if it does not exist, NemoClaw reports `error: --workdir: does not exist inside the sandbox` and exits with status `1` without invoking the inner command. | | `--tty` / `--no-tty` | Allocate a pseudo-terminal; defaults to auto-detection (on when stdin and stdout are terminals) | | `--timeout ` | Timeout in seconds (`0` means no timeout) | ### `nemoclaw agent` + + Run one OpenClaw agent turn non-interactively in a running sandbox. This command forwards every argument verbatim to `openclaw agent ...` inside the sandbox via `openshell sandbox exec`, with `HOME=/sandbox` so the addressed agent profile resolves the same way as `connect`. Use this when driving the sandbox programmatically from another process (CI job, multi-agent platform, evaluation harness) rather than from an interactive terminal. - - All flags accepted by the in-sandbox OpenClaw CLI are forwarded verbatim, so the upstream surface stays the single source of truth. ```bash @@ -545,7 +556,8 @@ Common upstream flags include `-m `, `--session-id `, `--agent `, -Only OpenClaw sandboxes support the `agent` wrapper today; Hermes sandboxes already expose an OpenAI-compatible HTTP API on port `8642` inside the sandbox, so non-interactive use does not need a wrapper command. +The `agent` wrapper is an OpenClaw passthrough and rejects Hermes sandboxes with guidance for the Hermes HTTP API. +Hermes sandboxes expose an OpenAI-compatible API on port `8642` inside the sandbox, so non-interactive use does not need a wrapper command. Forward the port and POST chat completions directly: @@ -609,6 +621,15 @@ If the gateway is already running, the command exits zero with a probe message a nemoclaw my-assistant recover ``` + + +`recover` re-evaluates the documented Hermes secret boundary against `/sandbox/.hermes/.env` on every run, including when the gateway is already healthy. +If the file contains raw secret-shaped values (for example a pasted Telegram, Discord, or Slack bot token in place of the expected `openshell:resolve:env:` placeholder), the command stops the running gateway, exits non-zero, and prints the offending key. +Replace each flagged value with the `openshell:resolve:env:` placeholder and re-run. +Older Hermes sandbox images that predate the standalone validator are detected and left untouched: `recover` prints a `[boundary]` warning naming the sandbox and noting that `/sandbox/.hermes/.env` was not re-evaluated, then proceeds with the rest of the recovery path rather than blocking the gateway. Re-image the sandbox to a current Hermes build to enable the per-run boundary re-evaluation described above. + + + ### `nemoclaw status` Show sandbox status, health, and inference configuration. @@ -1093,6 +1114,8 @@ 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. +Telegram and Discord mention mode default to `1` when no environment, session, or saved state value exists for that setting. +Discord applies that default only when a server ID is configured. 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. @@ -1259,6 +1282,24 @@ nemoclaw my-assistant agents delete work nemoclaw my-assistant agents delete work --force --json ``` + + +### `nemoclaw agents apply` + +Reconcile the live sandbox roster against a declarative agents.yaml manifest (use the `nemoclaw-user-configure-inference` skill). +The verb lists current agents via `openclaw agents list --json`, diffs them against the manifest, and adds missing secondaries or deletes orphan ones through `openclaw agents add|delete`. +Per-agent `model`, `subagents.*`, `tools`, top-level `defaults`, and `main` overrides need a sandbox rebuild and are surfaced as warnings rather than silently dropped; rerun `nemoclaw onboard --agents --recreate-sandbox` to bake those fields. + +```bash +nemoclaw my-assistant agents apply -f ./agents.yaml +nemoclaw my-assistant agents apply -f ./agents.yaml --yes +nemoclaw my-assistant agents apply -f ./agents.yaml --yes --non-interactive +``` + +Pass `-f` / `--file ` to point at the manifest; `--yes` confirms the roster diff above; `--non-interactive` fails fast when `--yes` is absent so scripted callers cannot accidentally hang on a missing prompt. + + + ### `nemoclaw sessions` List OpenClaw conversation sessions in the sandbox. @@ -1353,7 +1394,8 @@ Session JSONL can contain pasted secrets (API keys, tokens), so exported files a ### `nemoclaw download [host-dest]` Host-side wrapper around `openshell sandbox download` that adds a live-sandbox readiness check. -The source path inside the sandbox and the host destination are forwarded to OpenShell verbatim, so the file-system semantics (single-file vs directory copy, trailing-slash handling, overwrite behaviour) follow the OpenShell transport. +The sandbox source path is forwarded to OpenShell verbatim; a relative host destination is resolved against the caller's working directory before it reaches OpenShell, so the downloaded file lands where the user invoked the CLI from rather than inside the install directory. +Absolute host destinations pass through unchanged, and the OpenShell transport keeps its file-system semantics (single-file vs directory copy, trailing-slash handling, overwrite behaviour). With no `host-dest` the destination defaults to the current directory. ```bash @@ -1754,7 +1796,7 @@ Use `--no-verify` only when OpenShell cannot verify the provider at switch time 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`, `--agents `, `--control-ui-port`, `--yes` / `-y`, `--no-ollama-autostart`, `--yes-i-accept-third-party-software`. ```bash nemoclaw setup @@ -1767,7 +1809,7 @@ nemoclaw setup 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`, `--agents `, `--control-ui-port`, `--yes` / `-y`, `--no-ollama-autostart`, `--yes-i-accept-third-party-software`. ```bash nemoclaw setup-spark diff --git a/.agents/skills/nemoclaw-user-reference/references/enterprise-readiness.md b/.agents/skills/nemoclaw-user-reference/references/enterprise-readiness.md new file mode 100644 index 00000000000..8ad54215c4a --- /dev/null +++ b/.agents/skills/nemoclaw-user-reference/references/enterprise-readiness.md @@ -0,0 +1,140 @@ +# NemoClaw Enterprise Readiness and Admin Capability Guidance + +import { AgentOnly } from "../_components/AgentGuide"; + +This page gives field teams and enterprise evaluators a single reference for what NemoClaw supports today, what an operator must handle manually, what the OpenShell platform or the inference provider owns, and what is roadmap-only. +Use it to answer enterprise readiness and support-boundary questions consistently instead of inferring an answer from individual bug fixes. + +NemoClaw is an open-source reference stack for running sandboxed agents more safely inside OpenShell. +It is in active development, and interfaces can change between releases. +NemoClaw is not a hardened, multi-tenant enterprise control plane, and several admin and control-plane expectations are platform-owned or roadmap-only. +This page states where each capability stands so evaluators do not treat roadmap items as current commitments. + +**Confirm before you commit:** + +Treat this page as a living reference for an active evaluation window, not a contractual support matrix. +Confirm the current state of any capability with the NemoClaw product and engineering owners before you repeat it in a customer commitment. +Statuses can change between releases, and the tracked issues linked here may resolve or change scope. + +## How to Use This Guidance + +Each capability below carries one status from the following vocabulary. + +| Status | Meaning | +|---|---| +| Supported | Works today through the standard NemoClaw CLI and is covered by the documentation. | +| Supported with caveats | Works today, but with manual steps, platform limits, or known rough edges. | +| Manual or admin-only | No turnkey command. An operator performs it by hand with host-side commands, file edits, or container flags. | +| Platform or partner-owned | Owned by OpenShell (the sandbox runtime) or the inference provider, not by NemoClaw. | +| Experimental | Behind a flag or not fully validated. Use for evaluation only. | +| Roadmap-only | Not available today. Tracked or planned. | +| Out of scope | NemoClaw is a reference stack and does not intend to provide this. | + +This page covers support boundaries and admin capability classification. +For validated platform, inference, and launch claims, pair it with the launch claims and platform support matrix tracked in [NVIDIA/NemoClaw#4630](https://github.com/NVIDIA/NemoClaw/issues/4630). + +## Support Boundaries + +NemoClaw orchestrates several components that it does not all own. +Knowing who enforces each boundary prevents misattributing a limitation to NemoClaw when the owner is OpenShell, the agent runtime, or the provider. + +| Component | Owner | Responsibility | +|---|---|---| +| Host CLI and onboarding | NemoClaw | Onboarding, provider validation, blueprint resolution, sandbox lifecycle commands, and credential handling on the host. | +| Blueprint and policy presets | NemoClaw | Versioned blueprint, baseline network policy, filesystem and process defaults, and integration presets. | +| Gateway, sandbox runtime, and egress enforcement | OpenShell | Network namespace isolation, the CONNECT proxy, policy enforcement, inference routing, TLS termination, and structured platform logging. | +| Agent behavior | OpenClaw or Hermes | The agent loop, tools, skills, and in-sandbox configuration. | +| Model inference and data handling | Inference provider | Model execution, per-token cost, rate limits, and provider-side data policies. | +| Operator decisions | You | Endpoint approvals, policy widening, posture choices, provider selection, and credential rotation. | + +For the architecture behind these boundaries, refer to How It Works (use the `nemoclaw-user-overview` skill) and [Architecture Details](architecture.md). + +## Enterprise Readiness by Capability Area + +The following matrix answers the most common enterprise evaluation questions. +Each row links to the deeper documentation and, where a concrete fix is in progress, to the tracked issue. + +| Capability area | Status | Notes, workaround, and tracked work | +|---|---|---| +| Deny-by-default egress and operator approval | Supported | The sandbox blocks all unlisted outbound traffic and surfaces blocked requests for approval in `openshell term`. Approvals persist within a sandbox instance and reset to the baseline when you destroy and recreate it. See Approve or Deny Network Requests (use the `nemoclaw-user-manage-policy` skill). | +| Network policy configuration | Supported | Edit baseline policy in the blueprint, apply presets, or add endpoints to a running sandbox with `nemoclaw policy-add --from-file`. See Customize the Network Policy (use the `nemoclaw-user-manage-policy` skill) and [Network Policies](network-policies.md). | +| Network policy and denial visibility | Supported with caveats | Live activity appears in `openshell term`; lifecycle and gateway output appear in `nemoclaw logs`. Denial log readability is being improved in [#4760](https://github.com/NVIDIA/NemoClaw/issues/4760). Default-policy gaps for plugin installs are tracked in [#4104](https://github.com/NVIDIA/NemoClaw/issues/4104) and [#4015](https://github.com/NVIDIA/NemoClaw/issues/4015), and a `policy-add` YAML defect in [#991](https://github.com/NVIDIA/NemoClaw/issues/991). | +| Model and provider switching | Supported | Switch the active provider or model with the NemoClaw inference commands. Some changes rebuild the sandbox image. See Switch Inference Providers (use the `nemoclaw-user-configure-inference` skill) and Inference Options (use the `nemoclaw-user-configure-inference` skill). | +| Multi-agent and multi-sandbox usage | Supported with caveats | Side-by-side sandboxes run on distinct names and dashboard ports, and each name maps to exactly one agent type. Known multi-instance issues include gateway-port collisions ([#5359](https://github.com/NVIDIA/NemoClaw/issues/5359)) and parallel inference routing fallback ([#5343](https://github.com/NVIDIA/NemoClaw/issues/5343)). A declarative multi-agent manifest is roadmap ([#2853](https://github.com/NVIDIA/NemoClaw/issues/2853)). | +| Monitoring and health | Supported | Use `nemoclaw status`, `nemoclaw logs --follow`, and `openshell term`. See Monitor Sandbox Activity (use the `nemoclaw-user-monitor-sandbox` skill). | +| External telemetry and observability export | Roadmap-only | NemoClaw has no built-in metrics or trace export to external observability backends. An observability adapter plugin is tracked in [#3915](https://github.com/NVIDIA/NemoClaw/issues/3915). OpenShell emits structured platform logs (platform-owned). | +| Audit and session records | Supported with caveats | OpenClaw stores per-session JSONL event logs you can export for audit or compliance review; Hermes stores its own runtime state. Export is manual per sandbox. See Inspect Agent Session State (use the `nemoclaw-user-monitor-sandbox` skill). | +| Resource quotas | Supported with caveats | The entrypoint applies best-effort process and file-descriptor limits (`ulimit -u 512`, `ulimit -n 65536`). Set hard limits through the container runtime for fail-closed enforcement. See Process Controls (use the `nemoclaw-user-configure-security` skill). | +| Cost and spend controls | Platform or partner-owned | Deny-by-default egress and routed inference reduce exfiltration and stray endpoints, but NemoClaw does not enforce per-token spend budgets. Set spend limits with your inference provider and monitor unattended agents. | +| Credential isolation | Supported | Inference credentials stay on the host and never enter the sandbox; the agent reaches models through `inference.local`. CLI output redaction adds defense in depth, and OpenClaw sandboxes also run a memory secret scanner. See Credential Storage (use the `nemoclaw-user-configure-security` skill) and Security Best Practices (use the `nemoclaw-user-configure-security` skill). | +| Upgrades and lifecycle | Supported with caveats | Upgrade NemoClaw, then run `nemoclaw rebuild` to recreate the sandbox with the current image while backing up and restoring state. Do not run `openclaw update` inside the sandbox; the agent is image-pinned. Known gaps include config restore after rebuild ([#5202](https://github.com/NVIDIA/NemoClaw/issues/5202)) and version attachment flexibility ([#2217](https://github.com/NVIDIA/NemoClaw/issues/2217)). | +| Backup and restore | Supported | Create snapshots and restore workspace and agent state with the snapshot and backup commands. See Back Up and Restore (use the `nemoclaw-user-manage-sandboxes` skill). | +| Remote and cloud deployment | Supported with caveats | Provision the host, run the installer, and run `nemoclaw onboard`; the `nemoclaw deploy` Brev wrapper is deprecated. Remote dashboard origins can disable device pairing, so avoid exposing them on shared networks. Brev rough edges are tracked in [#3959](https://github.com/NVIDIA/NemoClaw/issues/3959) and [#3365](https://github.com/NVIDIA/NemoClaw/issues/3365). | + + +For remote deployment specifics, refer to Deploy to Remote GPU Instances (use the `nemoclaw-user-deploy-remote` skill) and Brev Web UI (use the `nemoclaw-user-deploy-remote` skill). +For container-level hardening beyond the entrypoint defaults, refer to Sandbox Hardening (use the `nemoclaw-user-deploy-remote` skill). + + +For remote deployment and Brev specifics, refer to the Brev section of the [Troubleshooting](troubleshooting.md#brev) guide. + + +## Admin and Control-Plane Capabilities + +Enterprise admins often expect a control plane with centralized management, identity integration, and fleet-wide policy. +NemoClaw targets a single-operator, single-host reference workflow today. +The following table classifies each admin and control-plane expectation by current support state so you can set accurate expectations. + +| Capability | Status | Notes | +|---|---|---| +| Centralized fleet and sandbox management across hosts | Manual or admin-only | Each host is managed independently with the NemoClaw CLI. There is no cross-host management console. | +| Role-based access control for operators | Out of scope | NemoClaw assumes a single trusted operator per host. There is no operator RBAC layer. | +| Enterprise identity integration (SSO, OIDC, SAML) | Roadmap-only | Gateway access uses device pairing for the OpenClaw dashboard or bearer-token auth for the Hermes API, not enterprise identity providers. | +| Multi-tenant isolation | Out of scope | Isolation is per-sandbox at the container level. NemoClaw does not provide tenant separation for multiple untrusted users on one host. | +| Centralized audit export and SIEM integration | Manual or admin-only | Export per-session JSONL logs by hand for audit review. External telemetry forwarding is roadmap ([#3915](https://github.com/NVIDIA/NemoClaw/issues/3915)). | +| Usage quotas, cost budgets, and billing | Platform or partner-owned | Set token and rate limits with your inference provider. NemoClaw does not meter or cap spend. | +| Credential and secrets management | Supported with caveats | Provider credentials live on the host with restricted permissions and redaction. Integration with an external secrets manager is manual. See Credential Storage (use the `nemoclaw-user-configure-security` skill). | +| Policy as code distributed across a fleet | Manual or admin-only | Baseline policy and presets are versioned in the blueprint and applied per sandbox. There is no fleet-wide policy distribution service. | +| High availability and horizontal gateway scaling | Platform or partner-owned | The NemoClaw reference flow targets a single host. Gateway scaling and availability are OpenShell concerns. | +| Disaster recovery across a fleet | Manual or admin-only | Per-sandbox snapshot, backup, and restore are supported. Fleet-level disaster recovery is an operator responsibility. | + +## Known Limitations and Workarounds + +These limitations are most likely to surface during an enterprise evaluation. +Each one includes the current workaround or next step. + +| Limitation | Impact | Workaround or next step | +|---|---|---| +| Approved endpoints reset on sandbox recreation | One-off approvals do not survive a destroy and recreate. | Add durable endpoints to the baseline policy or a preset rather than relying on repeated approvals. See Customize the Network Policy (use the `nemoclaw-user-manage-policy` skill). | +| Controls bypassed outside the managed gateway path | Network policy and inference auth are not enforced if a runtime starts outside the NemoClaw-managed entrypoint. | Use NemoClaw-managed onboarding and sandbox entrypoints for production workflows. See Known Limitations (use the `nemoclaw-user-configure-security` skill). | +| One consumer per messaging bot token | Two sandboxes sharing a bot token disconnect each other and drop messages. | Use a distinct bot token per sandbox. See the messaging troubleshooting in [Troubleshooting](troubleshooting.md#messaging-bridge-appears-running-but-no-messages-arrive). | +| In-sandbox config edits do not persist | Direct edits to agent config inside the running sandbox do not survive rebuilds. | Make durable config changes from the host by re-running `nemoclaw onboard`, not inside the sandbox. See [Troubleshooting](troubleshooting.md). | +| Landlock filesystem enforcement degrades on old kernels | Filesystem restrictions fall back to container mounts below Linux kernel 5.13. | Run on kernel 5.13 or later for full enforcement. See Landlock LSM Enforcement (use the `nemoclaw-user-configure-security` skill). | +| Best-effort capability and resource limits | Capability drops and ulimits skip silently when the runtime blocks them. | Pass `--cap-drop=ALL` and `--ulimit` at the container runtime, or set `NEMOCLAW_REQUIRE_CAP_DROP=1` to fail closed. See Process Controls (use the `nemoclaw-user-configure-security` skill). | + +## Field Conversation Guidance + +Use the following phrasing to describe NemoClaw accurately in customer and field conversations. + +- Describe NemoClaw as an open-source reference stack for running agents more safely inside OpenShell, in active development, rather than a finished enterprise control plane. +- State that egress is deny-by-default and that an operator approves new endpoints, so the agent cannot reach arbitrary hosts. +- Explain that inference credentials stay on the host and the agent calls models through a routed `inference.local` endpoint, so the sandbox never holds provider keys. +- Frame centralized fleet management, operator RBAC, enterprise SSO, and multi-tenant isolation as roadmap-only or out of scope today, and avoid presenting them as current capabilities. +- Position cost controls and spend limits as provider-owned, and recommend setting provider-side limits for unattended agents. +- When a customer hits a known limitation, point to the workaround in this guide and the tracked issue rather than promising a fix date. + +## Ownership and Keeping This Current + +This guidance must stay accurate for the duration of the evaluation window. + +- The NemoClaw product and engineering owners review this page before it is reused in launch-facing or customer-facing material. +- Update the affected rows whenever a tracked issue resolves, a capability ships, or a status changes, and align the status vocabulary with the platform support matrix in [#4630](https://github.com/NVIDIA/NemoClaw/issues/4630). +- Treat each linked issue as the source of truth for in-progress work, and remove the link when the work lands and the row moves to a supported status. + +## Related Topics + +- Security Best Practices (use the `nemoclaw-user-configure-security` skill) for the full control-by-control risk framework. +- [Network Policies](network-policies.md) for the baseline egress policy reference. +- Monitor Sandbox Activity (use the `nemoclaw-user-monitor-sandbox` skill) for status, logs, audit records, and the TUI. +- [Troubleshooting](troubleshooting.md) for installation, onboarding, and runtime issue resolution. +- How It Works (use the `nemoclaw-user-overview` skill) for the protection-layer architecture. diff --git a/.agents/skills/nemoclaw-user-reference/references/platform-support.md b/.agents/skills/nemoclaw-user-reference/references/platform-support.md new file mode 100644 index 00000000000..b431483e184 --- /dev/null +++ b/.agents/skills/nemoclaw-user-reference/references/platform-support.md @@ -0,0 +1,160 @@ +# Platform Support and Launch Claims + +This page is the canonical reference for what NemoClaw supports today. Any documentation, demo, blog post, sales conversation, or support reply that describes NemoClaw capability should agree with the entries below. + +The tables on this page are generated from [`ci/platform-matrix.json`](https://github.com/NVIDIA/NemoClaw/blob/main/ci/platform-matrix.json). +Update the JSON; the tables and the partial views on other pages stay in sync with `scripts/generate-platform-docs.py`. + +## Status vocabulary + +| Status | Meaning | +|--------|---------| +| Tested | Validated by CI or QA. Safe to claim and to demo. | +| Tested with limitations | Works on the listed setup with documented caveats. Caveats must be cited whenever this row is claimed. | +| Experimental | Available behind `NEMOCLAW_EXPERIMENTAL=1` or an equivalent opt-in flag. Do not claim in launch-facing material without the opt-in mentioned. | +| Deferred | Planned but not yet validated. Roadmap-only. Do not claim as supported. | +| Unsupported | Explicitly out of scope. Not validated and not planned. Documented to set expectations and prevent drift. | +| Hermes only | Available only when onboarding the Hermes agent. | + +## Project status + +For version highlights, see Release Notes (use the `nemoclaw-user-overview` skill). + +- **Stage:** alpha +- **Label:** Early preview +- **Since:** 2026-03-16 +- **Notes:** Maintainers review issues, discussions, and PRs on a best-effort basis without guaranteed response timelines. + +## Owners + +- **Engineering owner:** @NVIDIA/nemoclaw-maintainer (reviews through CODEOWNERS and signs off on launch-facing claim changes before they reach demos or sales material). + +The engineering owner is the GitHub team auto-assigned to review changes to `ci/platform-matrix.json` through CODEOWNERS, and the same team signs off on launch-facing claim changes before they reach demos, blog posts, or sales material. + +### Review process + +1. A change to a status or note opens a PR that touches `ci/platform-matrix.json`. +2. CODEOWNERS auto-requests review from the engineering owner team. +3. If the change is launch-facing (any status promotion, demotion, or new public claim), the engineering owner team explicitly acknowledges the launch impact in the PR review before approval. +4. The pre-commit `python3 scripts/generate-platform-docs.py --check` hook fails CI if the rendered tables on this page have drifted from the JSON. +5. After merge, the next NemoClaw release picks up the updated matrix automatically through the docs build. + +## Agents + +NemoClaw supports the agent runtimes listed below. +Pick the matching onboarding entry point for each agent. + +| Agent | Status | Default | Notes | +|-------|--------|---------|-------| +| OpenClaw | Tested | Yes | Default agent runtime. Onboard with `nemoclaw onboard` (no `--agent` flag required). | +| Hermes | Tested with limitations | No | First-class agent with dedicated CLI (`nemohermes`), Dockerfile, manifest, docs, and nightly E2E job coverage (`hermes-e2e` job in `.github/workflows/nightly-e2e.yaml` plus the `hermes-*-vitest` jobs in `e2e-vitest-scenarios.yaml`). Onboard with `nemohermes onboard` or pass `--agent hermes` to `nemoclaw onboard`. Unlocks the Hermes Provider inference route. Known structural gaps: model-provider compatibility registry is empty (backfilled after failures, see `nemoclaw-blueprint/model-specific-setup/hermes/README.md`); no Hermes-specific unit tests in `nemoclaw/src/`; macOS and WSL CI suites do not differentiate agents. Suitable for evaluation and the documented onboarding paths; production parity with OpenClaw is not yet asserted. | +| LangChain Deep Agents Code | Experimental | No | Terminal-oriented coding harness (no in-sandbox gateway, no dashboard) built on the Deep Agents SDK; manifest at `agents/langchain-deepagents-code/manifest.yaml` with binary `dcode`. Onboard with `nemoclaw onboard --agent langchain-deepagents-code` and follow the quickstart (use the `nemoclaw-user-get-started` skill). NemoClaw runs it as a managed harness: unmanaged sandbox/MCP/shell overrides are rejected and credential-bearing proxy URLs are dropped from persisted shell env. Inference routes through OpenShell's `inference.local` endpoint via Deep Agents Code's OpenAI-compatible provider. Live runtime acceptance, broader launch material, and terminal-agent diagnostics are tracked at open issue #4861. | + +## Platforms + +The table below lists every platform tracked by NemoClaw, including deferred entries that are on the roadmap but not yet validated. +The `CI` column reports whether the platform has a dedicated GitHub Actions job. +A "Tested with limitations" row that is not in CI carries a stronger caveat than one that is. +For the onboarding-time supported set without deferred rows, see Prerequisites (use the `nemoclaw-user-get-started` skill). + +| OS | Container runtime | Status | PRD priority | CI | Notes | +|----|-------------------|--------|--------------|----|-------| +| Linux | Docker | Tested | P0 | Yes | Primary tested path. Ubuntu 24.04 is the validated distro in production source (`DEFAULT_COMPAT_IMAGE` in `src/lib/onboard/docker-driver-gateway-launch.ts:10` and the preflight tests pin 24.04 only); the installer's package-manager probes assume apt-get. Other distros (Ubuntu 22.04, Fedora, Rocky, Alma, NixOS, Arch) may work but are not validated. | +| macOS (Apple Silicon) | Colima, Docker Desktop | Tested with limitations | P0 | Yes | Start the container runtime (Colima or Docker Desktop) before running the installer. Xcode Command Line Tools (`xcode-select --install`) are typically required for Node native modules during install. NemoClaw recommends them but does not enforce them during preflight. | +| DGX Spark | Docker | Tested | P1 | Yes | 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 | P1 | No | Requires WSL2 with Docker Desktop backend. | +| DGX Station | Docker | Deferred | P1 | No | The PRD marks this platform as P1. Workstation form-factor with NVIDIA GPUs and the same Docker + NVIDIA Container Toolkit + CDI requirements as DGX Spark. Onboard path not yet validated end-to-end on the hardware; vLLM has a placeholder default model defined for this host class (`Qwen/Qwen3.6-27B-FP8`) that will move out of `deferred` once the hardware run is signed off. | +| NVIDIA RTX (consumer and Pro workstation GPUs) | Docker | Deferred | P1 | No | The PRD marks this platform as P1. Covers RTX consumer cards and RTX Pro workstation cards on Linux hosts that meet the generic-Linux-GPU requirements (NVIDIA Container Toolkit + CDI present). The provider menu emits managed vLLM behind `NEMOCLAW_EXPERIMENTAL=1` or `NEMOCLAW_PROVIDER=install-vllm` for this host class today; the end-to-end onboard path on this hardware is not yet validated in CI. | + +## Inference providers + +NemoClaw routes inference through the OpenShell gateway. Each row below is a provider the onboarding wizard can configure end-to-end. + +| Provider | Status | Endpoint type | Notes | +|----------|--------|---------------|-------| +| NVIDIA Endpoints | Tested | OpenAI-compatible | Hosted models on integrate.api.nvidia.com | +| OpenAI | Tested | Native OpenAI-compatible | Uses OpenAI model IDs | +| Other OpenAI-compatible endpoint | Tested with limitations | Custom OpenAI-compatible | Adapter path validated with OpenRouter (`https://openrouter.ai`, see `src/lib/onboard.ts:3673`). Behavior on other OpenAI-compatible proxies, gateways, and self-hosted implementations may vary; this row claims the adapter, not the universe of compatible endpoints. | +| Anthropic | Tested | Native Anthropic | Uses anthropic-messages | +| Other Anthropic-compatible endpoint | Tested with limitations | Custom Anthropic-compatible | Adapter path validated with AWS Bedrock (`src/lib/onboard/bedrock-runtime.ts`). Behavior on other Anthropic-compatible proxies and gateways may vary; this row claims the adapter, not the universe of compatible endpoints. | +| Google Gemini | Tested | OpenAI-compatible | Uses Google's OpenAI-compatible endpoint | +| Hermes Provider | Hermes only | OpenAI-compatible route | Available when onboarding Hermes Agent through `nemohermes` | +| Local Ollama | Tested with limitations | Local Ollama API | Available when Ollama is installed or running on the host. Validated default models: `qwen3.6:35b` (high VRAM), `nemotron-3-nano:30b` (medium VRAM), `qwen3.5:9b` (low VRAM fallback). | +| Local NVIDIA NIM | Experimental | Local OpenAI-compatible | Requires `NEMOCLAW_EXPERIMENTAL=1` and a NIM-capable NVIDIA GPU. Host must have the NVIDIA Container Toolkit installed and a CDI spec present (`onboard` asserts CDI presence with `assertCdiNvidiaGpuSpecPresent`, `src/lib/onboard.ts:1581`). NIM images pull from `nvcr.io` and require NGC registry login. NemoClaw gates this path behind the experimental flag because it does not auto-select a NIM image for the host today. You must explicitly pick from the validated image list. Managed vLLM has host-specific default models and is not gated on the same boxes. Validated images referenced in `src/lib/inference/config.ts` and `nemoclaw/src/index.ts`: `nvidia/nemotron-3-super-120b-a12b` (default cloud model), `nvidia/nemotron-3-nano-30b-a3b`, `nvidia/llama-3.3-nemotron-super-49b-v1.5`. | +| Local vLLM (already running) | Tested with limitations | Local OpenAI-compatible | Appears in the onboarding menu when NemoClaw detects a server already on `localhost:8000`. No flag required. Model is whatever the existing server serves. | +| Local vLLM (managed install/start) | Tested with limitations | Local OpenAI-compatible | Appears by default on DGX Spark and DGX Station. Generic Linux NVIDIA GPU hosts require `NEMOCLAW_EXPERIMENTAL=1` or `NEMOCLAW_PROVIDER=install-vllm`. Host must have the NVIDIA Container Toolkit installed and a CDI spec present (`onboard` asserts CDI presence). NemoClaw pulls or starts the stable NGC vLLM container for each host profile. See `src/lib/inference/vllm.ts:55,177` for the pins. DGX Spark and DGX Station use `nvcr.io/nvidia/vllm:26.05.post1-py3`; generic Linux NVIDIA GPU hosts use `nvcr.io/nvidia/vllm:26.03.post1-py3`. Validated defaults are listed in `src/lib/inference/vllm-models.ts`: DGX Spark uses `nvidia/Qwen3.6-35B-A3B-NVFP4`, DGX Station uses `Qwen/Qwen3.6-27B-FP8`, and Linux NVIDIA GPU uses `nvidia/NVIDIA-Nemotron-3-Nano-4B-FP8`. Image pulls require NGC registry login (`docker login nvcr.io`); onboard prompts for the NGC API key when authentication is missing. | + +## Messaging integrations + +NemoClaw configures messaging channels during onboarding. The OpenShell gateway runs each channel as a supervised process; NemoClaw supplies onboarding, credential delivery, and policy presets for the sandbox egress rules. + +| Channel | Status | Notes | +|---------|--------|-------| +| Slack | Tested | Configured through an OpenShell-managed channel during onboarding. Sandbox egress allowed by the `slack` policy preset. | +| Discord | Tested | Configured through an OpenShell-managed channel during onboarding. Sandbox egress allowed by the `discord` policy preset. | +| Telegram | Tested | Configured through an OpenShell-managed channel during onboarding. | +| WeChat | Tested with limitations | Channel hook available. Verify regional account access before relying on this path. | +| WhatsApp | Tested with limitations | Supported by both OpenClaw and Hermes (see `messaging_platforms` in `agents/openclaw/manifest.yaml` and `agents/hermes/manifest.yaml`). Pairing happens in the sandbox through WhatsApp Web by scanning a QR code at first run; the Hermes flow exposes this as `hermes whatsapp` and persists session credentials under `~/.hermes/platforms/whatsapp/session` (`agents/hermes/manifest.yaml:69-71`). Sandbox egress goes through the `whatsapp` policy preset, which carries the WebSocket / Noise / h1-ALPN caveats documented in `nemoclaw-blueprint/policies/presets/whatsapp.yaml`. No Meta Business API integration today; that path is out of scope for this matrix. | + +## Capabilities + +Each row below is a launch-facing capability claim that NemoClaw makes in docs, blog posts, or demos. Use the status to decide whether the claim is safe to repeat verbatim or needs a caveat. + +| Capability | Status | Notes | +|------------|--------|-------| +| Guided onboarding | Tested | Single-command interactive wizard (`nemoclaw onboard`) that walks the user through inference provider selection, credential setup, sandbox creation, and dashboard launch. Non-interactive mode is supported with `--non-interactive` + `NEMOCLAW_*` environment variables for CI and scripted installs. | +| Sandboxed execution | Tested with limitations | Landlock, seccomp, network namespace isolation, no-new-privileges, privilege dropping, and process limits (ulimit -u 512 at `scripts/lib/sandbox-init.sh:237`) are tested and on by default. The `DANGEROUS_CAPS` list at `scripts/lib/sandbox-init.sh:288-299` drops cap_sys_admin, cap_sys_ptrace, cap_net_raw, cap_dac_override, cap_sys_chroot, cap_fsetid, cap_setfcap, cap_mknod, cap_audit_write, cap_net_bind_service with `capsh --drop` when CAP_SETPCAP is present. Limitation (active issue #3280): the fail-closed bounding-set gate is opt-in via `NEMOCLAW_REQUIRE_CAP_DROP=1`; the default is warn-and-continue so hosts without CAP_SETPCAP still boot, which means dangerous caps can remain in the bounding set on some hosts even though the effective set is empty. | +| Routed inference | Tested | Provider-routed model calls through the OpenShell gateway, transparent to the agent. The agent uses `inference.local` inside the sandbox; provider credentials stay on the host. Supports every entry in the Providers table. | +| Declarative network policy | Tested | YAML-defined egress with policy presets. Presets include `slack`, `discord`, `telegram`, `weather`, `openclaw-pricing`, `huggingface`, `npm`, `pypi`, `brew`, and others. Hot-reloadable at runtime with `nemoclaw <name> policy-add`. | +| Snapshot and restore | Tested | Create, list, and restore named snapshots of sandbox state with the `nemoclaw <name> snapshot` subcommands (`create`, `list`, `restore`). Credential stripping is enforced on capture. Unsafe symlinks are rejected on restore. | +| Agent skills | Tested | Packaged agent skills are discoverable by Cursor, Claude Code, and other coding assistants under `.agents/skills/`. Skills also install into the sandbox with `nemoclaw <name> skill install`. | +| State migration | Tested | Sandbox state migrates across rebuilds with credentials intentionally excluded. Hermes excludes `auth.json` and restores its SQLite session DB through the backup API. OpenClaw config merge prevents stale state from overwriting fresh values. | +| Blueprint versioning | Tested | Versioned, digest-verified, and reproducible blueprint lifecycle. Drives `nemoclaw <name> rebuild` and the migration safeguards above. | +| Web search backend | Tested with limitations | Runtime-configurable web-search backend plumbed through the OpenShell gateway. Brave is the currently-implemented backend. See `src/lib/onboard/brave-provider-profile.ts` and `src/lib/onboard/web-search-flow.ts`. Users supply backend credentials during an onboard prompt. NemoClaw does not bundle a key. | + +## Deployment paths + +How NemoClaw can be brought up on a given host. Pick the row that matches the target environment. + +| Path | Status | Notes | +|------|--------|-------| +| Local CLI onboard | Tested | Run `nemoclaw onboard` on a tested platform with Docker available locally. Primary path. | +| Remote GPU with Brev CLI | Tested with limitations | Legacy compatibility wrapper provisions a Brev VM, installs Docker + NVIDIA Container Toolkit, and runs `nemoclaw onboard` on that host. Defaults to GCP; override with `NEMOCLAW_BREV_PROVIDER`. The preferred path is the standard installer followed by `nemoclaw onboard` after the VM is reachable. | +| Brev web UI | Tested | Browser-driven launcher provisions a Brev-managed Linux VM with Docker, the OpenShell runtime, a NemoClaw sandbox running OpenClaw, inference routing, and the OpenClaw dashboard. | + +## Out of scope and not supported + +The items below come up in conversations but are explicitly out of scope. They are listed here so launch material, sales conversations, and support triage have a clear "we do not claim to do this" reference. + +| Item | Status | Why | +|------|--------|-----| +| Podman / other container runtimes | Unsupported | Onboard surfaces an explicit unsupported-runtime error for Podman (`src/lib/onboard.ts:1611` prints the rejection; `src/lib/onboard/preflight.ts:586` flags the unsupported runtime upstream). Only Docker Engine, Docker Desktop, and Colima are supported. See issue #420 (closed). | +| Intel Mac (macOS x86_64) | Unsupported | OpenShell does not publish macOS x86_64 standalone gateway assets. Install hard-fails on x86_64 macOS (`scripts/install-openshell.sh:315`). See issue #954 (closed). | +| Non-Ubuntu/Debian Linux distros | Unsupported | Installer assumes `apt-get`. Fedora/Rocky/Alma/Arch/NixOS are not validated and the installer's package-manager probes do not cover them. See open issue #899 (Fedora hang). | +| Native Kubernetes or OpenShift deployments | Unsupported | NemoClaw runs the sandbox as a Docker container, not a Kubernetes pod. The default Docker-driver topology does not embed k3s. Operator-managed K8s/OpenShift deployments are out of scope; see issue #407 (community OpenShift through agent-sandbox CRD). | +| Air-gapped / offline installs | Unsupported | Onboard assumes network reachability for package fetches, container pulls, and provider validation. See open issues #4872 and #2218 (production-deployment epic covering air-gapped support, China network guidance, multi-host topology). | +| Windows-on-ARM GPU passthrough | Unsupported | Windows-on-ARM CPU paths run under WSL2 'tested with limitations', but GPU passthrough on WOA is denylisted (`src/lib/onboard/wsl-docker-desktop-gpu.ts:188`, `src/lib/inference/gpu-trust.test.ts:70`). See closed issue #4565. | +| Non-NVIDIA GPUs (AMD/ROCm, Intel Arc, Apple Metal) | Unsupported | Local vLLM and NIM paths assert NVIDIA CDI presence with `assertCdiNvidiaGpuSpecPresent` (`src/lib/onboard.ts:1581`, called at `:1646`). NemoClaw does not install non-NVIDIA accelerator drivers. | +| Other LangChain, AutoGen, CrewAI, or non-listed agent harnesses | Unsupported | LangChain Deep Agents Code is the only integrated LangChain-family harness (see the Agents section above; status `Experimental`). Other LangChain harnesses, AutoGen, CrewAI, and any agent runtime not listed in the Agents table are not integrated. Bringing more harnesses is tracked as a research epic (see open issue #4861) but is not on the current roadmap. | +| Multi-user host sharing | Unsupported | Sandboxes are scoped to a single host user. NemoClaw treats multi-user hosts as a risk and warns at onboard; see `docs/security/openclaw-controls.mdx` Multi-user detection. | +| Hosted SaaS / managed NemoClaw | Unsupported | There is no managed offering. Supported deployment paths are Local CLI onboard, Remote GPU with Brev CLI, and Brev web UI. | +| Native provider integrations not in the Providers table | Unsupported | Vertex AI, Azure OpenAI, SageMaker, Together.ai, Replicate, and HuggingFace Inference Endpoints are not first-class onboarding entries. AWS Bedrock works through the `compatible-anthropic-endpoint` adapter (`src/lib/onboard/bedrock-runtime.ts`). | +| Production SLA or guaranteed response times | Unsupported | NemoClaw is an early-preview alpha project. Maintainers respond on a best-effort basis. No SLA is offered. | + +## Known caveats and active blockers + +- Sandbox bounding-set capability drop on hosts without `CAP_SETPCAP` is partially fixed. The agent process tree drops dangerous caps with `NEMOCLAW_REQUIRE_CAP_DROP=1` (see [#4707](https://github.com/NVIDIA/NemoClaw/pull/4707)). The `nemoclaw connect` shell still inherits the container's create-time bounding set on Colossus, Docker Desktop, and WSL hosts where `CAP_SETPCAP` is absent. The remaining fix is upstream in [NVIDIA/OpenShell#1452](https://github.com/NVIDIA/OpenShell/issues/1452). See tracking [#3280](https://github.com/NVIDIA/NemoClaw/issues/3280). + +## Using this matrix + +- Docs and READMEs that reference any row above should link to this page instead of restating status. Partial tables, such as the prerequisites page, generate from the same JSON and stay in sync with `scripts/generate-platform-docs.py`. +- Demos and launch material should cite the status verbatim. A "Tested with limitations" row is not a "Tested" row. +- Customer support can use the matrix to triage incoming reports. A failure on a Tested row is a bug. A failure on a Deferred row is an unsupported configuration request. A failure on an Unsupported row is a feature request that needs separate triage. +- Roadmap changes land in the JSON first, then propagate to this page on the next generator run. + +## Updating the matrix + +1. Edit [`ci/platform-matrix.json`](https://github.com/NVIDIA/NemoClaw/blob/main/ci/platform-matrix.json). +2. Run `python3 scripts/generate-platform-docs.py` to regenerate this page and the partial tables on prerequisites and inference-options. +3. Open a PR. The engineering owner team is auto-assigned through CODEOWNERS and explicitly acknowledges launch impact in the PR review for any launch-facing claim change. +4. The `generate-platform-docs.py --check` step in pre-commit fails if the docs drift from the JSON. diff --git a/.agents/skills/nemoclaw-user-reference/references/troubleshooting.md b/.agents/skills/nemoclaw-user-reference/references/troubleshooting.md index 297e4f8ff9f..fcd259c511a 100644 --- a/.agents/skills/nemoclaw-user-reference/references/troubleshooting.md +++ b/.agents/skills/nemoclaw-user-reference/references/troubleshooting.md @@ -378,6 +378,30 @@ nemoclaw connect Run `nemoclaw status` for a broader gateway health report. +### Sandbox container reports `(unhealthy)` while the agent gateway process is still alive + +The in-sandbox OpenClaw gateway can drop its HTTP listener while its process stays alive. +A restart-class configuration change makes the gateway restart itself in place, and if that restart fails the process parks with no listener (`/tmp/gateway.log` shows `gateway startup failed: ... Process will stay alive`). +Docker then marks the container `(unhealthy)` even though `pgrep` still finds the gateway. + +NemoClaw prevents this state and recovers it when it happens: + +- The generated sandbox config pins `gateway.reload.mode` to `hot`, so configuration changes never make the gateway restart itself out from under the sandbox supervisor. +- A serving watchdog inside the sandbox kills a gateway that stops listening after it has served, and the supervisor relaunches it (look for `[gateway-watchdog]` lines in `nemoclaw logs`). + +Because of the `hot` pin, restart-class configuration changes made inside the sandbox, for example `openclaw plugins install`, log `config reload requires gateway restart; hot mode ignoring` and do not take effect until the gateway restarts. +Apply them with a supervised restart: + +```bash +nemoclaw recover +``` + +For changes that affect provisioning, rebuild the sandbox: + +```bash +nemoclaw rebuild --yes +``` + ### Invalid sandbox name Sandbox names must be lowercase, start with a letter, contain only letters, numbers, and internal hyphens, and end with a letter or number. diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 2fe3288677b..7974afc223f 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -81,9 +81,9 @@ repos: hooks: - id: platform-matrix-sync name: Sync platform matrix to docs - entry: bash -c 'python3 scripts/generate-platform-docs.py && git add docs/get-started/prerequisites.mdx docs/inference/inference-options.mdx' + entry: bash -c 'python3 scripts/generate-platform-docs.py && git add docs/get-started/prerequisites.mdx docs/inference/inference-options.mdx docs/reference/platform-support.mdx' language: system - files: ^(ci/platform-matrix\.json|docs/get-started/prerequisites\.mdx|docs/inference/inference-options\.mdx|scripts/generate-platform-docs\.py)$ + files: ^(ci/platform-matrix\.json|docs/get-started/prerequisites\.mdx|docs/inference/inference-options\.mdx|docs/reference/platform-support\.mdx|scripts/generate-platform-docs\.py)$ pass_filenames: false priority: 3 diff --git a/README.md b/README.md index 159b2d3c820..02d3944f518 100644 --- a/README.md +++ b/README.md @@ -61,6 +61,7 @@ NemoClaw is an alpha project, so maintainers review issues, discussions, and pul | Reproducible bugs | [GitHub Issues](https://github.com/NVIDIA/NemoClaw/issues) | | Feature proposals | Start with [GitHub Discussions](https://github.com/NVIDIA/NemoClaw/discussions), then open an issue when the scope is clear | | Current priorities | [Current Priorities](#current-priorities) | +| Supported platforms, providers, and integrations | [Platform Support and Launch Claims](docs/reference/platform-support.mdx) | | Contribution help | [CONTRIBUTING.md](CONTRIBUTING.md) | | Security vulnerabilities | Use the private channels in [SECURITY.md](SECURITY.md); do not open public issues | diff --git a/ci/platform-matrix.json b/ci/platform-matrix.json index 887ee0bd5fb..6dcaf5fe78d 100644 --- a/ci/platform-matrix.json +++ b/ci/platform-matrix.json @@ -1,13 +1,27 @@ { - "$comment": "Single source of truth for tested platforms and providers. Scripts read this to generate README and docs tables. QA/CI update this file; docs are derived.", - "version": "1.0", - "updated": "2026-04-08", + "$comment": "Single source of truth for NemoClaw launch claims and platform support. Covers platforms, inference providers, supported agents, messaging integrations, and deployment paths. Scripts read this to generate README and docs tables. QA/CI update platform/provider rows; the engineering owner reviews other rows. Docs are derived.", + "version": "1.1", + "updated": "2026-06-12", + + "project_status": { + "stage": "alpha", + "label": "Early preview", + "since": "2026-03-16", + "notes": "Maintainers review issues, discussions, and PRs on a best-effort basis without guaranteed response timelines." + }, + + "owners": { + "engineering": "@NVIDIA/nemoclaw-maintainer", + "$comment": "Engineering owner is the GitHub team that auto-reviews changes to this file through CODEOWNERS and signs off on launch-facing claim changes before they reach demos or sales material. NemoClaw is maintainer-run; there is no separate product owner role today." + }, "statuses": { "tested": "Validated by CI/QA. Primary path.", "caveated": "Tested with limitations. See Notes.", "experimental": "Requires NEMOCLAW_EXPERIMENTAL=1.", - "deferred": "Planned but not yet validated." + "deferred": "Planned but not yet validated.", + "unsupported": "Explicitly out of scope. Not validated and not planned.", + "hermes only": "Available only when onboarding the Hermes agent." }, "platforms": [ @@ -17,7 +31,7 @@ "status": "tested", "prd_priority": "P0", "ci_tested": true, - "notes": "Primary tested path." + "notes": "Primary tested path. Ubuntu 24.04 is the validated distro in production source (`DEFAULT_COMPAT_IMAGE` in `src/lib/onboard/docker-driver-gateway-launch.ts:10` and the preflight tests pin 24.04 only); the installer's package-manager probes assume apt-get. Other distros (Ubuntu 22.04, Fedora, Rocky, Alma, NixOS, Arch) may work but are not validated." }, { "name": "macOS (Apple Silicon)", @@ -25,7 +39,7 @@ "status": "caveated", "prd_priority": "P0", "ci_tested": true, - "notes": "Install Xcode Command Line Tools (`xcode-select --install`) and start the runtime before running the installer." + "notes": "Start the container runtime (Colima or Docker Desktop) before running the installer. Xcode Command Line Tools (`xcode-select --install`) are typically required for Node native modules during install. NemoClaw recommends them but does not enforce them during preflight." }, { "name": "DGX Spark", @@ -50,31 +64,15 @@ "status": "deferred", "prd_priority": "P1", "ci_tested": false, - "notes": "P1 per PRD. Setup path not yet validated." + "notes": "The PRD marks this platform as P1. Workstation form-factor with NVIDIA GPUs and the same Docker + NVIDIA Container Toolkit + CDI requirements as DGX Spark. Onboard path not yet validated end-to-end on the hardware; vLLM has a placeholder default model defined for this host class (`Qwen/Qwen3.6-27B-FP8`) that will move out of `deferred` once the hardware run is signed off." }, { - "name": "RTX Spark", + "name": "NVIDIA RTX (consumer and Pro workstation GPUs)", "runtimes": ["Docker"], "status": "deferred", "prd_priority": "P1", "ci_tested": false, - "notes": "P1 per PRD. Setup path not yet validated." - }, - { - "name": "NVIDIA RTX", - "runtimes": ["Docker"], - "status": "deferred", - "prd_priority": "P1", - "ci_tested": false, - "notes": "P1 per PRD. Setup path not yet validated." - }, - { - "name": "NVIDIA RTX Pro", - "runtimes": ["Docker"], - "status": "deferred", - "prd_priority": "P1", - "ci_tested": false, - "notes": "P1 per PRD. Setup path not yet validated." + "notes": "The PRD marks this platform as P1. Covers RTX consumer cards and RTX Pro workstation cards on Linux hosts that meet the generic-Linux-GPU requirements (NVIDIA Container Toolkit + CDI present). The provider menu emits managed vLLM behind `NEMOCLAW_EXPERIMENTAL=1` or `NEMOCLAW_PROVIDER=install-vllm` for this host class today; the end-to-end onboard path on this hardware is not yet validated in CI." } ], @@ -93,9 +91,9 @@ }, { "name": "Other OpenAI-compatible endpoint", - "status": "tested", + "status": "caveated", "endpoint_type": "Custom OpenAI-compatible", - "notes": "For compatible proxies and gateways" + "notes": "Adapter path validated with OpenRouter (`https://openrouter.ai`, see `src/lib/onboard.ts:3673`). Behavior on other OpenAI-compatible proxies, gateways, and self-hosted implementations may vary; this row claims the adapter, not the universe of compatible endpoints." }, { "name": "Anthropic", @@ -105,9 +103,9 @@ }, { "name": "Other Anthropic-compatible endpoint", - "status": "tested", + "status": "caveated", "endpoint_type": "Custom Anthropic-compatible", - "notes": "For Claude proxies and compatible gateways" + "notes": "Adapter path validated with AWS Bedrock (`src/lib/onboard/bedrock-runtime.ts`). Behavior on other Anthropic-compatible proxies and gateways may vary; this row claims the adapter, not the universe of compatible endpoints." }, { "name": "Google Gemini", @@ -125,25 +123,203 @@ "name": "Local Ollama", "status": "caveated", "endpoint_type": "Local Ollama API", - "notes": "Available when Ollama is installed or running on the host" + "notes": "Available when Ollama is installed or running on the host. Validated default models: `qwen3.6:35b` (high VRAM), `nemotron-3-nano:30b` (medium VRAM), `qwen3.5:9b` (low VRAM fallback)." }, { "name": "Local NVIDIA NIM", "status": "experimental", "endpoint_type": "Local OpenAI-compatible", - "notes": "Requires `NEMOCLAW_EXPERIMENTAL=1` and a NIM-capable GPU" + "notes": "Requires `NEMOCLAW_EXPERIMENTAL=1` and a NIM-capable NVIDIA GPU. Host must have the NVIDIA Container Toolkit installed and a CDI spec present (`onboard` asserts CDI presence with `assertCdiNvidiaGpuSpecPresent`, `src/lib/onboard.ts:1581`). NIM images pull from `nvcr.io` and require NGC registry login. NemoClaw gates this path behind the experimental flag because it does not auto-select a NIM image for the host today. You must explicitly pick from the validated image list. Managed vLLM has host-specific default models and is not gated on the same boxes. Validated images referenced in `src/lib/inference/config.ts` and `nemoclaw/src/index.ts`: `nvidia/nemotron-3-super-120b-a12b` (default cloud model), `nvidia/nemotron-3-nano-30b-a3b`, `nvidia/llama-3.3-nemotron-super-49b-v1.5`." }, { "name": "Local vLLM (already running)", "status": "caveated", "endpoint_type": "Local OpenAI-compatible", - "notes": "Appears in the onboarding menu when NemoClaw detects a server already on `localhost:8000`. No flag required." + "notes": "Appears in the onboarding menu when NemoClaw detects a server already on `localhost:8000`. No flag required. Model is whatever the existing server serves." }, { "name": "Local vLLM (managed install/start)", "status": "caveated", "endpoint_type": "Local OpenAI-compatible", - "notes": "Appears by default on DGX Spark and DGX Station. Generic Linux NVIDIA GPU hosts require `NEMOCLAW_EXPERIMENTAL=1` or `NEMOCLAW_PROVIDER=install-vllm`. NemoClaw pulls/starts a vLLM container on a supported NVIDIA GPU host." + "notes": "Appears by default on DGX Spark and DGX Station. Generic Linux NVIDIA GPU hosts require `NEMOCLAW_EXPERIMENTAL=1` or `NEMOCLAW_PROVIDER=install-vllm`. Host must have the NVIDIA Container Toolkit installed and a CDI spec present (`onboard` asserts CDI presence). NemoClaw pulls or starts the stable NGC vLLM container for each host profile. See `src/lib/inference/vllm.ts:55,177` for the pins. DGX Spark and DGX Station use `nvcr.io/nvidia/vllm:26.05.post1-py3`; generic Linux NVIDIA GPU hosts use `nvcr.io/nvidia/vllm:26.03.post1-py3`. Validated defaults are listed in `src/lib/inference/vllm-models.ts`: DGX Spark uses `nvidia/Qwen3.6-35B-A3B-NVFP4`, DGX Station uses `Qwen/Qwen3.6-27B-FP8`, and Linux NVIDIA GPU uses `nvidia/NVIDIA-Nemotron-3-Nano-4B-FP8`. Image pulls require NGC registry login (`docker login nvcr.io`); onboard prompts for the NGC API key when authentication is missing." + } + ], + + "agents": [ + { + "name": "OpenClaw", + "status": "tested", + "default": true, + "notes": "Default agent runtime. Onboard with `$$nemoclaw onboard` (no `--agent` flag required)." + }, + { + "name": "Hermes", + "status": "caveated", + "default": false, + "notes": "First-class agent with dedicated CLI (`$$nemohermes`), Dockerfile, manifest, docs, and nightly E2E job coverage (`hermes-e2e` job in `.github/workflows/nightly-e2e.yaml` plus the `hermes-*-vitest` jobs in `e2e-vitest-scenarios.yaml`). Onboard with `$$nemohermes onboard` or pass `--agent hermes` to `$$nemoclaw onboard`. Unlocks the Hermes Provider inference route. Known structural gaps: model-provider compatibility registry is empty (backfilled after failures, see `nemoclaw-blueprint/model-specific-setup/hermes/README.md`); no Hermes-specific unit tests in `nemoclaw/src/`; macOS and WSL CI suites do not differentiate agents. Suitable for evaluation and the documented onboarding paths; production parity with OpenClaw is not yet asserted." + }, + { + "name": "LangChain Deep Agents Code", + "status": "experimental", + "default": false, + "notes": "Terminal-oriented coding harness (no in-sandbox gateway, no dashboard) built on the Deep Agents SDK; manifest at `agents/langchain-deepagents-code/manifest.yaml` with binary `dcode`. Onboard with `$$nemoclaw onboard --agent langchain-deepagents-code` and follow [the quickstart](../get-started/quickstart-langchain-deepagents-code). NemoClaw runs it as a managed harness: unmanaged sandbox/MCP/shell overrides are rejected and credential-bearing proxy URLs are dropped from persisted shell env. Inference routes through OpenShell's `inference.local` endpoint via Deep Agents Code's OpenAI-compatible provider. Live runtime acceptance, broader launch material, and terminal-agent diagnostics are tracked at open issue #4861." + } + ], + + "capabilities": [ + { + "name": "Guided onboarding", + "status": "tested", + "notes": "Single-command interactive wizard (`$$nemoclaw onboard`) that walks the user through inference provider selection, credential setup, sandbox creation, and dashboard launch. Non-interactive mode is supported with `--non-interactive` + `NEMOCLAW_*` environment variables for CI and scripted installs." + }, + { + "name": "Sandboxed execution", + "status": "caveated", + "notes": "Landlock, seccomp, network namespace isolation, no-new-privileges, privilege dropping, and process limits (ulimit -u 512 at `scripts/lib/sandbox-init.sh:237`) are tested and on by default. The `DANGEROUS_CAPS` list at `scripts/lib/sandbox-init.sh:288-299` drops cap_sys_admin, cap_sys_ptrace, cap_net_raw, cap_dac_override, cap_sys_chroot, cap_fsetid, cap_setfcap, cap_mknod, cap_audit_write, cap_net_bind_service with `capsh --drop` when CAP_SETPCAP is present. Limitation (active issue #3280): the fail-closed bounding-set gate is opt-in via `NEMOCLAW_REQUIRE_CAP_DROP=1`; the default is warn-and-continue so hosts without CAP_SETPCAP still boot, which means dangerous caps can remain in the bounding set on some hosts even though the effective set is empty." + }, + { + "name": "Routed inference", + "status": "tested", + "notes": "Provider-routed model calls through the OpenShell gateway, transparent to the agent. The agent uses `inference.local` inside the sandbox; provider credentials stay on the host. Supports every entry in the Providers table." + }, + { + "name": "Declarative network policy", + "status": "tested", + "notes": "YAML-defined egress with policy presets. Presets include `slack`, `discord`, `telegram`, `weather`, `openclaw-pricing`, `huggingface`, `npm`, `pypi`, `brew`, and others. Hot-reloadable at runtime with `$$nemoclaw policy-add`." + }, + { + "name": "Snapshot and restore", + "status": "tested", + "notes": "Create, list, and restore named snapshots of sandbox state with the `$$nemoclaw snapshot` subcommands (`create`, `list`, `restore`). Credential stripping is enforced on capture. Unsafe symlinks are rejected on restore." + }, + { + "name": "Agent skills", + "status": "tested", + "notes": "Packaged agent skills are discoverable by Cursor, Claude Code, and other coding assistants under `.agents/skills/`. Skills also install into the sandbox with `$$nemoclaw skill install`." + }, + { + "name": "State migration", + "status": "tested", + "notes": "Sandbox state migrates across rebuilds with credentials intentionally excluded. Hermes excludes `auth.json` and restores its SQLite session DB through the backup API. OpenClaw config merge prevents stale state from overwriting fresh values." + }, + { + "name": "Blueprint versioning", + "status": "tested", + "notes": "Versioned, digest-verified, and reproducible blueprint lifecycle. Drives `$$nemoclaw rebuild` and the migration safeguards above." + }, + { + "name": "Web search backend", + "status": "caveated", + "notes": "Runtime-configurable web-search backend plumbed through the OpenShell gateway. Brave is the currently-implemented backend. See `src/lib/onboard/brave-provider-profile.ts` and `src/lib/onboard/web-search-flow.ts`. Users supply backend credentials during an onboard prompt. NemoClaw does not bundle a key." + } + ], + + "out_of_scope": [ + { + "name": "Podman / other container runtimes", + "status": "unsupported", + "notes": "Onboard surfaces an explicit unsupported-runtime error for Podman (`src/lib/onboard.ts:1611` prints the rejection; `src/lib/onboard/preflight.ts:586` flags the unsupported runtime upstream). Only Docker Engine, Docker Desktop, and Colima are supported. See issue #420 (closed)." + }, + { + "name": "Intel Mac (macOS x86_64)", + "status": "unsupported", + "notes": "OpenShell does not publish macOS x86_64 standalone gateway assets. Install hard-fails on x86_64 macOS (`scripts/install-openshell.sh:315`). See issue #954 (closed)." + }, + { + "name": "Non-Ubuntu/Debian Linux distros", + "status": "unsupported", + "notes": "Installer assumes `apt-get`. Fedora/Rocky/Alma/Arch/NixOS are not validated and the installer's package-manager probes do not cover them. See open issue #899 (Fedora hang)." + }, + { + "name": "Native Kubernetes or OpenShift deployments", + "status": "unsupported", + "notes": "NemoClaw runs the sandbox as a Docker container, not a Kubernetes pod. The default Docker-driver topology does not embed k3s. Operator-managed K8s/OpenShift deployments are out of scope; see issue #407 (community OpenShift through agent-sandbox CRD)." + }, + { + "name": "Air-gapped / offline installs", + "status": "unsupported", + "notes": "Onboard assumes network reachability for package fetches, container pulls, and provider validation. See open issues #4872 and #2218 (production-deployment epic covering air-gapped support, China network guidance, multi-host topology)." + }, + { + "name": "Windows-on-ARM GPU passthrough", + "status": "unsupported", + "notes": "Windows-on-ARM CPU paths run under WSL2 'tested with limitations', but GPU passthrough on WOA is denylisted (`src/lib/onboard/wsl-docker-desktop-gpu.ts:188`, `src/lib/inference/gpu-trust.test.ts:70`). See closed issue #4565." + }, + { + "name": "Non-NVIDIA GPUs (AMD/ROCm, Intel Arc, Apple Metal)", + "status": "unsupported", + "notes": "Local vLLM and NIM paths assert NVIDIA CDI presence with `assertCdiNvidiaGpuSpecPresent` (`src/lib/onboard.ts:1581`, called at `:1646`). NemoClaw does not install non-NVIDIA accelerator drivers." + }, + { + "name": "Other LangChain, AutoGen, CrewAI, or non-listed agent harnesses", + "status": "unsupported", + "notes": "LangChain Deep Agents Code is the only integrated LangChain-family harness (see the Agents section above; status `Experimental`). Other LangChain harnesses, AutoGen, CrewAI, and any agent runtime not listed in the Agents table are not integrated. Bringing more harnesses is tracked as a research epic (see open issue #4861) but is not on the current roadmap." + }, + { + "name": "Multi-user host sharing", + "status": "unsupported", + "notes": "Sandboxes are scoped to a single host user. NemoClaw treats multi-user hosts as a risk and warns at onboard; see `docs/security/openclaw-controls.mdx` Multi-user detection." + }, + { + "name": "Hosted SaaS / managed NemoClaw", + "status": "unsupported", + "notes": "There is no managed offering. Supported deployment paths are Local CLI onboard, Remote GPU with Brev CLI, and Brev web UI." + }, + { + "name": "Native provider integrations not in the Providers table", + "status": "unsupported", + "notes": "Vertex AI, Azure OpenAI, SageMaker, Together.ai, Replicate, and HuggingFace Inference Endpoints are not first-class onboarding entries. AWS Bedrock works through the `compatible-anthropic-endpoint` adapter (`src/lib/onboard/bedrock-runtime.ts`)." + }, + { + "name": "Production SLA or guaranteed response times", + "status": "unsupported", + "notes": "NemoClaw is an early-preview alpha project. Maintainers respond on a best-effort basis. No SLA is offered." + } + ], + + "integrations": [ + { + "name": "Slack", + "status": "tested", + "notes": "Configured through an OpenShell-managed channel during onboarding. Sandbox egress allowed by the `slack` policy preset." + }, + { + "name": "Discord", + "status": "tested", + "notes": "Configured through an OpenShell-managed channel during onboarding. Sandbox egress allowed by the `discord` policy preset." + }, + { + "name": "Telegram", + "status": "tested", + "notes": "Configured through an OpenShell-managed channel during onboarding." + }, + { + "name": "WeChat", + "status": "caveated", + "notes": "Channel hook available. Verify regional account access before relying on this path." + }, + { + "name": "WhatsApp", + "status": "caveated", + "notes": "Supported by both OpenClaw and Hermes (see `messaging_platforms` in `agents/openclaw/manifest.yaml` and `agents/hermes/manifest.yaml`). Pairing happens in the sandbox through WhatsApp Web by scanning a QR code at first run; the Hermes flow exposes this as `hermes whatsapp` and persists session credentials under `~/.hermes/platforms/whatsapp/session` (`agents/hermes/manifest.yaml:69-71`). Sandbox egress goes through the `whatsapp` policy preset, which carries the WebSocket / Noise / h1-ALPN caveats documented in `nemoclaw-blueprint/policies/presets/whatsapp.yaml`. No Meta Business API integration today; that path is out of scope for this matrix." + } + ], + + "deployment_paths": [ + { + "name": "Local CLI onboard", + "status": "tested", + "notes": "Run `$$nemoclaw onboard` on a tested platform with Docker available locally. Primary path." + }, + { + "name": "Remote GPU with Brev CLI", + "status": "caveated", + "notes": "Legacy compatibility wrapper provisions a Brev VM, installs Docker + NVIDIA Container Toolkit, and runs `$$nemoclaw onboard` on that host. Defaults to GCP; override with `NEMOCLAW_BREV_PROVIDER`. The preferred path is the standard installer followed by `$$nemoclaw onboard` after the VM is reachable." + }, + { + "name": "Brev web UI", + "status": "tested", + "notes": "Browser-driven launcher provisions a Brev-managed Linux VM with Docker, the OpenShell runtime, a NemoClaw sandbox running OpenClaw, inference routing, and the OpenClaw dashboard." } ] } diff --git a/docs/about/overview.mdx b/docs/about/overview.mdx index 689849cde16..8b12ff98484 100644 --- a/docs/about/overview.mdx +++ b/docs/about/overview.mdx @@ -22,6 +22,8 @@ NemoClaw pairs hosted models on inference providers or local endpoints with a ha The sandbox runtime comes from [NVIDIA OpenShell](https://github.com/NVIDIA/OpenShell). NemoClaw adds the blueprint, CLI, onboarding, and related tooling as the reference way to run supported agents there. +For the canonical list of what NemoClaw supports today across platforms, inference providers, agents, messaging integrations, and deployment paths, see [Platform Support and Launch Claims](../reference/platform-support). + | Capability | Description | |-------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------| | Sandbox supported agents | Creates an OpenShell sandbox pre-configured for your selected agent, with filesystem and network policies applied from the first boot. | diff --git a/docs/about/release-notes.mdx b/docs/about/release-notes.mdx index d76011be692..07da68416d2 100644 --- a/docs/about/release-notes.mdx +++ b/docs/about/release-notes.mdx @@ -14,6 +14,7 @@ import { AgentOnly } from "../_components/AgentGuide"; NVIDIA NemoClaw is available in early preview starting March 16, 2026. Use this page to track the highlights of the latest release. For more detailed release notes, refer to the [NemoClaw GitHub announcements](https://github.com/NVIDIA/NemoClaw/discussions/categories/announcements?discussions_q=is%3Aopen+category%3AAnnouncements). +For the canonical list of supported platforms, providers, agents, integrations, and deployment paths with explicit status for each row, see [Platform Support and Launch Claims](../reference/platform-support). ## v0.0.65 diff --git a/docs/get-started/prerequisites.mdx b/docs/get-started/prerequisites.mdx index d5fd11b62c0..c6de4ba8bf6 100644 --- a/docs/get-started/prerequisites.mdx +++ b/docs/get-started/prerequisites.mdx @@ -71,13 +71,14 @@ Refer to the [troubleshooting guide](../reference/troubleshooting) for the overr The following table lists tested platform and runtime combinations. Availability is not limited to these entries, but untested configurations can have issues. +For the full canonical matrix including deferred platforms, inference providers, agents, messaging integrations, and deployment paths, see [Platform Support and Launch Claims](../reference/platform-support). The table comes from [`ci/platform-matrix.json`](https://github.com/NVIDIA/NemoClaw/blob/main/ci/platform-matrix.json), the single source of truth kept in sync by CI and QA. {/* platform-matrix:begin */} | OS | Container runtime | Status | Notes | |----|-------------------|--------|-------| -| 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. | +| Linux | Docker | Tested | Primary tested path. Ubuntu 24.04 is the validated distro in production source (`DEFAULT_COMPAT_IMAGE` in `src/lib/onboard/docker-driver-gateway-launch.ts:10` and the preflight tests pin 24.04 only); the installer's package-manager probes assume apt-get. Other distros (Ubuntu 22.04, Fedora, Rocky, Alma, NixOS, Arch) may work but are not validated. | +| macOS (Apple Silicon) | Colima, Docker Desktop | Tested with limitations | Start the container runtime (Colima or Docker Desktop) before running the installer. Xcode Command Line Tools (`xcode-select --install`) are typically required for Node native modules during install. NemoClaw recommends them but does not enforce them during preflight. | | 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 */} diff --git a/docs/index.mdx b/docs/index.mdx index 3fa31cce292..15b23ee4b0b 100644 --- a/docs/index.mdx +++ b/docs/index.mdx @@ -37,6 +37,8 @@ NVIDIA NemoClaw is an open-source reference stack for running always-on AI agent NemoClaw provides onboarding, lifecycle management, and agent operations within OpenShell containers. It installs the OpenShell runtime, part of NVIDIA Agent Toolkit, and sets up an environment designed for executing agents with additional security and inference routing capabilities. +For the canonical list of supported platforms, inference providers, agents, messaging integrations, and deployment paths with explicit status for each row, see [Platform Support and Launch Claims](./reference/platform-support). + ## Get Started Install NemoClaw and run the onboard wizard to get started. diff --git a/docs/index.yml b/docs/index.yml index fa589c267f0..9195aa3409d 100644 --- a/docs/index.yml +++ b/docs/index.yml @@ -159,6 +159,9 @@ navigation: - page: "Network Policies" path: _build/agent-variants/reference/network-policies.openclaw.generated.mdx slug: network-policies + - page: "Platform Support" + path: reference/platform-support.mdx + slug: platform-support - page: "Troubleshooting" path: _build/agent-variants/reference/troubleshooting.openclaw.generated.mdx slug: troubleshooting @@ -299,6 +302,9 @@ navigation: - page: "Network Policies" path: _build/agent-variants/reference/network-policies.hermes.generated.mdx slug: network-policies + - page: "Platform Support" + path: reference/platform-support.mdx + slug: platform-support - page: "Troubleshooting" path: _build/agent-variants/reference/troubleshooting.hermes.generated.mdx slug: troubleshooting diff --git a/docs/inference/declarative-agents-manifest.mdx b/docs/inference/declarative-agents-manifest.mdx index 1c97b7681a9..51ec9ebcd06 100644 --- a/docs/inference/declarative-agents-manifest.mdx +++ b/docs/inference/declarative-agents-manifest.mdx @@ -3,7 +3,7 @@ # SPDX-License-Identifier: Apache-2.0 title: "Declarative Multi-Agent Manifest" sidebar-title: "Declarative Multi-Agent Manifest" -description: "Bake secondary OpenClaw agents into a NemoClaw sandbox image from a checked-in agents.yaml manifest, including per-agent models and OpenClaw-native sub-agent delegation." +description: "Bake secondary OpenClaw agents into a NemoClaw sandbox image from a checked-in agents.yaml manifest, including agent-specific models and OpenClaw-native sub-agent delegation." description-agent: "Documents the `nemoclaw onboard --agents ` flag and the YAML schema it consumes. Use when users ask how to declare a manager-worker layout, how to give a secondary agent its own model, or how to express OpenClaw's `subagents.allowAgents` from NemoClaw." keywords: - "nemoclaw agents.yaml" @@ -11,7 +11,7 @@ keywords: - "agents.list bake" - "manager worker agents" - "subagents allowAgents" - - "per-agent model" + - "agent-specific model" topics: ["generative_ai", "ai_agents"] tags: ["nemoclaw", "openclaw", "openshell", "agents.yaml", "subagents"] content: @@ -24,7 +24,7 @@ status: published --- NemoClaw can bake a multi-agent OpenClaw layout into a sandbox image from a single checked-in manifest. -Supply the manifest at onboard time with `--agents ` and NemoClaw embeds the resulting `agents.list` entries, per-agent overrides, and `agents.defaults.subagents` block into `openclaw.json` during the image build. +Supply the manifest at onboard time with `--agents ` and NemoClaw embeds the resulting `agents.list` entries, agent-specific overrides, and `agents.defaults.subagents` block into `openclaw.json` during the image build. The schema mirrors OpenClaw's own `agents.list[]` field names, so the same keys you read in [OpenClaw's sub-agents reference](https://docs.openclaw.ai/tools/subagents) appear verbatim in the manifest. @@ -36,7 +36,8 @@ Use `--agents` when: - A secondary agent needs its own model (different size, different capability profile). - You want OpenClaw's `sessions_spawn` validator to enforce a fixed spawn allowlist, not the broad default. -For a single primary agent on the configured inference route, no manifest is required — the canonical `main` agent is always baked in as the default. +For a single primary agent on the configured inference route, no manifest is required. +The canonical `main` agent is always baked in as the default. ## Invocation @@ -83,21 +84,21 @@ agents: # required when secondary agents are needed | Field | Purpose | Bakes Into | |---|---|---| | `defaults.subagents.maxSpawnDepth` | Maximum nesting depth for sub-agent spawning. Integer 1..5. | `agents.defaults.subagents.maxSpawnDepth` | -| `main.tools` | Per-agent tool policy for the canonical `main` agent. | `agents.list[id=main].tools` | +| `main.tools` | Agent-specific tool policy for the canonical `main` agent. | `agents.list[id=main].tools` | | `main.subagents` | Sub-agent delegation policy for `main`. Same shape as a secondary agent's `subagents` block. | `agents.list[id=main].subagents` | | `agents[]` | Secondary agents to append after `main` in `agents.list`. | `agents.list[]` | The `main` agent is always written first into `agents.list` with `default: true`. Operators cannot set `default: true` on a secondary agent and cannot rename the primary slot. -### Per-Agent Fields +### Agent Fields | Field | Required | Purpose | |---|---|---| -| `id` | yes | Lowercase alphanumeric + `_`/`-`, 1-32 chars, must start with a letter. Cannot be `main`. | +| `id` | yes | Lowercase alphanumeric + `_`/`-`, 1-32 chars, must start with a letter, and cannot be `main`. | | `workspace` | auto-filled | Defaults to `/sandbox/.openclaw/workspace-`. Must match the canonical sandbox layout if supplied. | | `agentDir` | auto-filled | Defaults to `/sandbox/.openclaw/agents/`. Must match the canonical sandbox layout if supplied. | -| `tools` | yes | `{profile?, allow?, deny?}`. Must declare a non-empty `allow[]` or `deny[]` — secondary agents inherit no tools by default. | +| `tools` | yes | `{profile?, allow?, deny?}`. Must declare a non-empty `allow[]` or `deny[]`. Secondary agents inherit no tools by default. | | `description` | no | Human-readable. Baked verbatim. | | `model` | no | `provider/model` reference. The provider must match the onboard provider; cross-provider manifests are not supported. | | `subagents` | no | OpenClaw-native sub-agent delegation policy. See below. | @@ -109,18 +110,20 @@ Both `main.subagents` and `agents[].subagents` use the same shape, which mirrors | Field | Type | Purpose | |---|---|---| | `delegationMode` | `"suggest"` or `"prefer"` | Prompt-only steering for how strongly this agent should delegate. No enforcement. | -| `allowAgents` | `string[]` | Allowlist of agent ids this agent may target via `sessions_spawn`. `["*"]` allows any configured target; omit for self-only. | +| `allowAgents` | `string[]` | Allowlist of agent ids this agent may target through `sessions_spawn`. `["*"]` allows any configured target; omit for self-only. | | `model` | `provider/model` | Default model for spawned sub-agents. Provider must match the onboard provider. | | `thinking` | string | Default thinking level for spawned sub-agents. | | `requireAgentId` | boolean | Force the model to pass `agentId` explicitly to `sessions_spawn` rather than defaulting to self. | -`maxSpawnDepth` is **not accepted per-agent** — OpenClaw only honours it on `agents.defaults.subagents`, so the manifest exposes it only under the top-level `defaults` block. +`maxSpawnDepth` is not accepted for individual agents. +OpenClaw only honors it on `agents.defaults.subagents`, so the manifest exposes it only under the top-level `defaults` block. ### Multi-Model Sandboxes -When a secondary agent declares its own `model` (or `subagents.model`), NemoClaw widens the baked `models.providers[].models[]` array with one entry per unique `provider/model` reference. +When a secondary agent declares its own `model` (or `subagents.model`), NemoClaw widens the baked `models.providers[].models[]` array with one entry for each unique `provider/model` reference. The base `contextWindow`, `maxTokens`, `reasoning`, and `input` settings from the onboard route apply to each appended entry. -Per-model overrides beyond these defaults are out of scope for v1 — edit the generated `openclaw.json` in-place if you need finer control. +Model-specific overrides beyond these defaults are out of scope for v1. +Edit the generated `openclaw.json` in place if you need finer control. ## Manager-Worker Example @@ -155,14 +158,14 @@ What this produces in the baked `openclaw.json`: Edit `agents.yaml`, re-run `nemoclaw onboard --agents ./agents.yaml --recreate-sandbox`. Workspaces under `/sandbox/.openclaw/workspace-` are preserved across rebuilds because the runtime startup script provisions them on first boot rather than baking their contents. -For ad-hoc per-agent edits inside an existing sandbox (no rebuild), use the in-sandbox CLI: `nemoclaw agents add|delete|list`. +For interactive agent-specific edits inside an existing sandbox with no rebuild, use the in-sandbox CLI, `nemoclaw agents add|delete|list`. The manifest path is for fixed, checked-in layouts; the CLI passthrough is for interactive work. ## Apply To An Existing Sandbox `nemoclaw agents apply -f ` reconciles the live sandbox roster against the manifest **without a rebuild**. -The verb lists current agents via `openclaw agents list --json`, diffs them against the manifest, and drives `openclaw agents add|delete` per item. -Per-agent `model`, `subagents.*`, top-level `defaults`, and `main` overrides require a sandbox rebuild and are reported as warnings the verb prints before exit; rerun `nemoclaw onboard --agents --recreate-sandbox` to bake those. +The verb lists current agents with `openclaw agents list --json`, diffs them against the manifest, and drives `openclaw agents add|delete` for each item. +Agent-specific `model`, `subagents.*`, top-level `defaults`, and `main` overrides require a sandbox rebuild and are reported as warnings the verb prints before exit; rerun `nemoclaw onboard --agents --recreate-sandbox` to bake those. ```bash nemoclaw my-assistant agents apply -f ./agents.yaml --yes @@ -174,7 +177,7 @@ The flag pair `--yes / --non-interactive` is required for scripted use: `--yes` Use the following resources for more information: -- Refer to [OpenClaw Sub-Agents](https://docs.openclaw.ai/tools/subagents) for the runtime semantics of `sessions_spawn`, `subagents.allowAgents`, and nesting depth. -- Refer to [Set Up Task-Specific Sub-Agents](set-up-sub-agent) for the in-sandbox path that edits `agents.list` directly without a rebuild. -- Refer to [Switch Inference Providers](switch-inference-providers) before swapping the primary onboard provider — per-agent `model` refs must share that provider. -- Refer to [Workspace Files](../manage-sandboxes/workspace-files) to understand how per-agent `workspace-` directories are provisioned and persisted across rebuilds. +- Use [OpenClaw Sub-Agents](https://docs.openclaw.ai/tools/subagents) for runtime semantics of `sessions_spawn`, `subagents.allowAgents`, and nesting depth. +- Use [Set Up Task-Specific Sub-Agents](set-up-sub-agent) for the in-sandbox path that edits `agents.list` directly without a rebuild. +- Use [Switch Inference Providers](switch-inference-providers) before changing agent-specific `model` refs, since refs must share the primary onboard provider. +- Use [Workspace Files](../manage-sandboxes/workspace-files) to learn how agent-specific `workspace-` directories are provisioned and persisted across rebuilds. diff --git a/docs/inference/inference-options.mdx b/docs/inference/inference-options.mdx index f07adf448a1..85b10a05a35 100644 --- a/docs/inference/inference-options.mdx +++ b/docs/inference/inference-options.mdx @@ -43,15 +43,15 @@ NemoClaw uses provider-specific local tokens for those routes, and rebuilds of l |----------|--------|---------------|-------| | NVIDIA Endpoints | Tested | OpenAI-compatible | Hosted models on integrate.api.nvidia.com | | OpenAI | Tested | Native OpenAI-compatible | Uses OpenAI model IDs | -| Other OpenAI-compatible endpoint | Tested | Custom OpenAI-compatible | For compatible proxies and gateways | +| Other OpenAI-compatible endpoint | Tested with limitations | Custom OpenAI-compatible | Adapter path validated with OpenRouter (`https://openrouter.ai`, see `src/lib/onboard.ts:3673`). Behavior on other OpenAI-compatible proxies, gateways, and self-hosted implementations may vary; this row claims the adapter, not the universe of compatible endpoints. | | Anthropic | Tested | Native Anthropic | Uses anthropic-messages | -| Other Anthropic-compatible endpoint | Tested | Custom Anthropic-compatible | For Claude proxies and compatible gateways | +| Other Anthropic-compatible endpoint | Tested with limitations | Custom Anthropic-compatible | Adapter path validated with AWS Bedrock (`src/lib/onboard/bedrock-runtime.ts`). Behavior on other Anthropic-compatible proxies and gateways may vary; this row claims the adapter, not the universe of compatible endpoints. | | Google Gemini | Tested | OpenAI-compatible | Uses Google's OpenAI-compatible endpoint | | Hermes Provider | Hermes only | OpenAI-compatible route | Available when onboarding Hermes Agent through `nemohermes` | -| Local Ollama | Caveated | Local Ollama API | Available when Ollama is installed or running on the host | -| Local NVIDIA NIM | Experimental | Local OpenAI-compatible | Requires `NEMOCLAW_EXPERIMENTAL=1` and a NIM-capable GPU | -| Local vLLM (already running) | Caveated | Local OpenAI-compatible | Appears in the onboarding menu when NemoClaw detects a server already on `localhost:8000`. No flag required. | -| Local vLLM (managed install/start) | Caveated | Local OpenAI-compatible | Appears by default on DGX Spark and DGX Station. Generic Linux NVIDIA GPU hosts require `NEMOCLAW_EXPERIMENTAL=1` or `NEMOCLAW_PROVIDER=install-vllm`. NemoClaw pulls/starts a vLLM container on a supported NVIDIA GPU host. | +| Local Ollama | Tested with limitations | Local Ollama API | Available when Ollama is installed or running on the host. Validated default models: `qwen3.6:35b` (high VRAM), `nemotron-3-nano:30b` (medium VRAM), `qwen3.5:9b` (low VRAM fallback). | +| Local NVIDIA NIM | Experimental | Local OpenAI-compatible | Requires `NEMOCLAW_EXPERIMENTAL=1` and a NIM-capable NVIDIA GPU. Host must have the NVIDIA Container Toolkit installed and a CDI spec present (`onboard` asserts CDI presence with `assertCdiNvidiaGpuSpecPresent`, `src/lib/onboard.ts:1581`). NIM images pull from `nvcr.io` and require NGC registry login. NemoClaw gates this path behind the experimental flag because it does not auto-select a NIM image for the host today. You must explicitly pick from the validated image list. Managed vLLM has host-specific default models and is not gated on the same boxes. Validated images referenced in `src/lib/inference/config.ts` and `nemoclaw/src/index.ts`: `nvidia/nemotron-3-super-120b-a12b` (default cloud model), `nvidia/nemotron-3-nano-30b-a3b`, `nvidia/llama-3.3-nemotron-super-49b-v1.5`. | +| Local vLLM (already running) | Tested with limitations | Local OpenAI-compatible | Appears in the onboarding menu when NemoClaw detects a server already on `localhost:8000`. No flag required. Model is whatever the existing server serves. | +| Local vLLM (managed install/start) | Tested with limitations | Local OpenAI-compatible | Appears by default on DGX Spark and DGX Station. Generic Linux NVIDIA GPU hosts require `NEMOCLAW_EXPERIMENTAL=1` or `NEMOCLAW_PROVIDER=install-vllm`. Host must have the NVIDIA Container Toolkit installed and a CDI spec present (`onboard` asserts CDI presence). NemoClaw pulls or starts the stable NGC vLLM container for each host profile. See `src/lib/inference/vllm.ts:55,177` for the pins. DGX Spark and DGX Station use `nvcr.io/nvidia/vllm:26.05.post1-py3`; generic Linux NVIDIA GPU hosts use `nvcr.io/nvidia/vllm:26.03.post1-py3`. Validated defaults are listed in `src/lib/inference/vllm-models.ts`: DGX Spark uses `nvidia/Qwen3.6-35B-A3B-NVFP4`, DGX Station uses `Qwen/Qwen3.6-27B-FP8`, and Linux NVIDIA GPU uses `nvidia/NVIDIA-Nemotron-3-Nano-4B-FP8`. Image pulls require NGC registry login (`docker login nvcr.io`); onboard prompts for the NGC API key when authentication is missing. | {/* provider-status:end */} ## Provider Options diff --git a/docs/inference/set-up-sub-agent.mdx b/docs/inference/set-up-sub-agent.mdx index 2bfdfc2ba8c..0d5e56c350d 100644 --- a/docs/inference/set-up-sub-agent.mdx +++ b/docs/inference/set-up-sub-agent.mdx @@ -68,23 +68,33 @@ if [ -z "$SANDBOX_CTR" ]; then echo "No running sandbox container found for $SANDBOX. Start the sandbox before editing its config." exit 1 fi -docker exec --user root "$SANDBOX_CTR" cat /sandbox/.openclaw/openclaw.json > /tmp/openclaw.json +umask 077 +WORK_DIR=$(mktemp -d -t nemoclaw-subagent-XXXXXX) +trap 'rm -rf "$WORK_DIR"' EXIT +docker exec --user root "$SANDBOX_CTR" cat /sandbox/.openclaw/openclaw.json > "$WORK_DIR/openclaw.json" ``` If `SANDBOX_CTR` is empty, the sandbox is not running on this host. Start the sandbox, confirm that `docker ps` shows the matching `openshell.ai/sandbox-name` label, then rerun the export commands before continuing. -Create `/tmp/openclaw.updated.json` with the OpenClaw sub-agent config. +Produce the patched OpenClaw sub-agent config in the same mode-0600 temp directory. For the Omni example, the demo provides `vlm-demo/vlm-subagent/openclaw-patch.py`. Set `VLM_DEMO_DIR` to the local `vlm-demo` directory from the demo assets, then run the patch helper: ```bash export VLM_DEMO_DIR=/path/to/nemoclaw-demos/vlm-demo -python3 "$VLM_DEMO_DIR/vlm-subagent/openclaw-patch.py" "$NVIDIA_API_KEY" < /tmp/openclaw.json > /tmp/openclaw.updated.json +NVIDIA_API_KEY="$NVIDIA_API_KEY" python3 "$VLM_DEMO_DIR/vlm-subagent/openclaw-patch.py" \ + < "$WORK_DIR/openclaw.json" > "$WORK_DIR/openclaw.updated.json" ``` -The helper reads `/tmp/openclaw.json` from standard input, adds the Omni provider and `vision-operator` entry, and writes the patched config to `/tmp/openclaw.updated.json`. -Do not commit `/tmp/openclaw.updated.json` or any other file that contains a real API key. +The helper reads `NVIDIA_API_KEY` from the environment (so the key avoids argv and shell history), reads the unmodified config from `$WORK_DIR/openclaw.json`, adds the Omni provider and `vision-operator` entry, and writes the patched config to a mode-0600 temp file under `$WORK_DIR`. +The `trap` cleans up the temp directory on shell exit so the patched JSON does not linger on disk. +Do not commit the patched config or any other file that contains a real API key. + + +The auxiliary sub-agent path writes a real provider key into sandbox state at `/sandbox/.openclaw/agents//agent/auth-profiles.json`. That file sits outside NemoClaw's normal host-side OpenShell credential-store boundary, so a snapshot, backup, or cloned sandbox image carries the key with it. Use this flow only when the normal host-side credential route cannot serve the auxiliary provider, and treat the affected sandbox as credential-bearing. +Environment-delivered keys also remain readable from `/proc` by same-user or root processes on most Linux configurations; this pattern avoids argv and shell history, not all process inspection. Prefer a stdin or mode-0600 input file when the demo helper supports it. + Upload the patched config and refresh the hash. In the default mutable state, this keeps the local hash consistent but does not make it tamper-proof. @@ -93,7 +103,7 @@ Use NemoClaw runtime controls when the sandbox needs a hardened config posture a ```bash docker exec --user root "$SANDBOX_CTR" chmod 644 /sandbox/.openclaw/openclaw.json docker exec --user root "$SANDBOX_CTR" chmod 644 /sandbox/.openclaw/.config-hash -docker exec --user root -i "$SANDBOX_CTR" sh -c 'cat > /sandbox/.openclaw/openclaw.json' < /tmp/openclaw.updated.json +docker exec --user root -i "$SANDBOX_CTR" sh -c 'cat > /sandbox/.openclaw/openclaw.json' < "$WORK_DIR/openclaw.updated.json" docker exec --user root "$SANDBOX_CTR" /bin/bash -c "cd /sandbox/.openclaw && sha256sum openclaw.json > .config-hash" docker exec --user root "$SANDBOX_CTR" chown sandbox:sandbox /sandbox/.openclaw/openclaw.json /sandbox/.openclaw/.config-hash docker exec --user root "$SANDBOX_CTR" chmod 444 /sandbox/.openclaw/openclaw.json @@ -126,14 +136,19 @@ For the Omni example: ``` Use the same provider ID that appears in `models.providers`, such as `nvidia-omni`. -Create `/tmp/auth-profiles.json` from `vlm-demo/vlm-subagent/auth-profiles.template.json`, replace `YOUR_NVIDIA_API_KEY_HERE` with the provider key, then upload it into the sandbox: +Create the auth profile in the same mode-0600 work directory used above (so the trap from the patch step also cleans this file up on exit), then upload it into the sandbox. +The example below pulls `$NVIDIA_API_KEY` from the environment and writes the auth profile through `envsubst` so the key never appears in argv or shell history: ```bash docker exec --user root "$SANDBOX_CTR" mkdir -p /sandbox/.openclaw/agents/vision-operator/agent -docker exec --user root -i "$SANDBOX_CTR" sh -c 'cat > /sandbox/.openclaw/agents/vision-operator/agent/auth-profiles.json' < /tmp/auth-profiles.json +NVIDIA_API_KEY="$NVIDIA_API_KEY" envsubst '$NVIDIA_API_KEY' < "$VLM_DEMO_DIR/vlm-subagent/auth-profiles.template.json" \ + > "$WORK_DIR/auth-profiles.json" +docker exec --user root -i "$SANDBOX_CTR" sh -c 'cat > /sandbox/.openclaw/agents/vision-operator/agent/auth-profiles.json' < "$WORK_DIR/auth-profiles.json" docker exec --user root "$SANDBOX_CTR" chmod 600 /sandbox/.openclaw/agents/vision-operator/agent/auth-profiles.json ``` +The `'$NVIDIA_API_KEY'` argument to `envsubst` is an allowlist: only that one variable is expanded in the template. Any other `$VAR` references the demo template uses for unrelated text are left intact, so a stray placeholder cannot accidentally pull in another environment variable. + After uploading the auth profile, make sure the sandbox user owns the sub-agent directory: ```bash diff --git a/docs/reference/platform-support.mdx b/docs/reference/platform-support.mdx new file mode 100644 index 00000000000..01106e25058 --- /dev/null +++ b/docs/reference/platform-support.mdx @@ -0,0 +1,187 @@ +--- +# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# SPDX-License-Identifier: Apache-2.0 +title: "Platform Support and Launch Claims" +sidebar-title: "Platform Support" +description: "Canonical matrix of supported platforms, inference providers, agents, integrations, and deployment paths for NemoClaw, with explicit status for each row." +description-agent: "Single source of truth for what NemoClaw supports today. Use when verifying whether a platform, inference provider, agent, messaging integration, or deployment path is validated, partially validated, experimental, or out of scope before relying on it in docs, demos, sales material, or support conversations." +keywords: ["nemoclaw platform support", "nemoclaw launch claims", "nemoclaw support matrix", "nemoclaw what is supported", "nemoclaw status"] +content: + type: "reference" +--- +This page is the canonical reference for what NemoClaw supports today. Any documentation, demo, blog post, sales conversation, or support reply that describes NemoClaw capability should agree with the entries below. + +The tables on this page are generated from [`ci/platform-matrix.json`](https://github.com/NVIDIA/NemoClaw/blob/main/ci/platform-matrix.json). +Update the JSON; the tables and the partial views on other pages stay in sync with `scripts/generate-platform-docs.py`. + +## Status vocabulary + +| Status | Meaning | +|--------|---------| +| Tested | Validated by CI or QA. Safe to claim and to demo. | +| Tested with limitations | Works on the listed setup with documented caveats. Caveats must be cited whenever this row is claimed. | +| Experimental | Available behind `NEMOCLAW_EXPERIMENTAL=1` or an equivalent opt-in flag. Do not claim in launch-facing material without the opt-in mentioned. | +| Deferred | Planned but not yet validated. Roadmap-only. Do not claim as supported. | +| Unsupported | Explicitly out of scope. Not validated and not planned. Documented to set expectations and prevent drift. | +| Hermes only | Available only when onboarding the Hermes agent. | + +## Project status + +For version highlights, see [Release Notes](../about/release-notes). + +{/* project-status:begin */} +- **Stage:** alpha +- **Label:** Early preview +- **Since:** 2026-03-16 +- **Notes:** Maintainers review issues, discussions, and PRs on a best-effort basis without guaranteed response timelines. +{/* project-status:end */} + +## Owners + +{/* matrix-owners:begin */} +- **Engineering owner:** @NVIDIA/nemoclaw-maintainer (reviews through CODEOWNERS and signs off on launch-facing claim changes before they reach demos or sales material). +{/* matrix-owners:end */} + +The engineering owner is the GitHub team auto-assigned to review changes to `ci/platform-matrix.json` through CODEOWNERS, and the same team signs off on launch-facing claim changes before they reach demos, blog posts, or sales material. + +### Review process + +1. A change to a status or note opens a PR that touches `ci/platform-matrix.json`. +2. CODEOWNERS auto-requests review from the engineering owner team. +3. If the change is launch-facing (any status promotion, demotion, or new public claim), the engineering owner team explicitly acknowledges the launch impact in the PR review before approval. +4. The pre-commit `python3 scripts/generate-platform-docs.py --check` hook fails CI if the rendered tables on this page have drifted from the JSON. +5. After merge, the next NemoClaw release picks up the updated matrix automatically through the docs build. + +## Agents + +NemoClaw supports the agent runtimes listed below. +Pick the matching onboarding entry point for each agent. + +{/* agent-status:begin */} +| Agent | Status | Default | Notes | +|-------|--------|---------|-------| +| OpenClaw | Tested | Yes | Default agent runtime. Onboard with `$$nemoclaw onboard` (no `--agent` flag required). | +| Hermes | Tested with limitations | No | First-class agent with dedicated CLI (`$$nemohermes`), Dockerfile, manifest, docs, and nightly E2E job coverage (`hermes-e2e` job in `.github/workflows/nightly-e2e.yaml` plus the `hermes-*-vitest` jobs in `e2e-vitest-scenarios.yaml`). Onboard with `$$nemohermes onboard` or pass `--agent hermes` to `$$nemoclaw onboard`. Unlocks the Hermes Provider inference route. Known structural gaps: model-provider compatibility registry is empty (backfilled after failures, see `nemoclaw-blueprint/model-specific-setup/hermes/README.md`); no Hermes-specific unit tests in `nemoclaw/src/`; macOS and WSL CI suites do not differentiate agents. Suitable for evaluation and the documented onboarding paths; production parity with OpenClaw is not yet asserted. | +| LangChain Deep Agents Code | Experimental | No | Terminal-oriented coding harness (no in-sandbox gateway, no dashboard) built on the Deep Agents SDK; manifest at `agents/langchain-deepagents-code/manifest.yaml` with binary `dcode`. Onboard with `$$nemoclaw onboard --agent langchain-deepagents-code` and follow [the quickstart](../get-started/quickstart-langchain-deepagents-code). NemoClaw runs it as a managed harness: unmanaged sandbox/MCP/shell overrides are rejected and credential-bearing proxy URLs are dropped from persisted shell env. Inference routes through OpenShell's `inference.local` endpoint via Deep Agents Code's OpenAI-compatible provider. Live runtime acceptance, broader launch material, and terminal-agent diagnostics are tracked at open issue #4861. | +{/* agent-status:end */} + +## Platforms + +The table below lists every platform tracked by NemoClaw, including deferred entries that are on the roadmap but not yet validated. +The `CI` column reports whether the platform has a dedicated GitHub Actions job. +A "Tested with limitations" row that is not in CI carries a stronger caveat than one that is. +For the onboarding-time supported set without deferred rows, see [Prerequisites](../get-started/prerequisites#platforms). + +{/* platform-matrix-full:begin */} +| OS | Container runtime | Status | PRD priority | CI | Notes | +|----|-------------------|--------|--------------|----|-------| +| Linux | Docker | Tested | P0 | Yes | Primary tested path. Ubuntu 24.04 is the validated distro in production source (`DEFAULT_COMPAT_IMAGE` in `src/lib/onboard/docker-driver-gateway-launch.ts:10` and the preflight tests pin 24.04 only); the installer's package-manager probes assume apt-get. Other distros (Ubuntu 22.04, Fedora, Rocky, Alma, NixOS, Arch) may work but are not validated. | +| macOS (Apple Silicon) | Colima, Docker Desktop | Tested with limitations | P0 | Yes | Start the container runtime (Colima or Docker Desktop) before running the installer. Xcode Command Line Tools (`xcode-select --install`) are typically required for Node native modules during install. NemoClaw recommends them but does not enforce them during preflight. | +| DGX Spark | Docker | Tested | P1 | Yes | 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 | P1 | No | Requires WSL2 with Docker Desktop backend. | +| DGX Station | Docker | Deferred | P1 | No | The PRD marks this platform as P1. Workstation form-factor with NVIDIA GPUs and the same Docker + NVIDIA Container Toolkit + CDI requirements as DGX Spark. Onboard path not yet validated end-to-end on the hardware; vLLM has a placeholder default model defined for this host class (`Qwen/Qwen3.6-27B-FP8`) that will move out of `deferred` once the hardware run is signed off. | +| NVIDIA RTX (consumer and Pro workstation GPUs) | Docker | Deferred | P1 | No | The PRD marks this platform as P1. Covers RTX consumer cards and RTX Pro workstation cards on Linux hosts that meet the generic-Linux-GPU requirements (NVIDIA Container Toolkit + CDI present). The provider menu emits managed vLLM behind `NEMOCLAW_EXPERIMENTAL=1` or `NEMOCLAW_PROVIDER=install-vllm` for this host class today; the end-to-end onboard path on this hardware is not yet validated in CI. | +{/* platform-matrix-full:end */} + +## Inference providers + +NemoClaw routes inference through the OpenShell gateway. Each row below is a provider the onboarding wizard can configure end-to-end. + +{/* provider-status-full:begin */} +| Provider | Status | Endpoint type | Notes | +|----------|--------|---------------|-------| +| NVIDIA Endpoints | Tested | OpenAI-compatible | Hosted models on integrate.api.nvidia.com | +| OpenAI | Tested | Native OpenAI-compatible | Uses OpenAI model IDs | +| Other OpenAI-compatible endpoint | Tested with limitations | Custom OpenAI-compatible | Adapter path validated with OpenRouter (`https://openrouter.ai`, see `src/lib/onboard.ts:3673`). Behavior on other OpenAI-compatible proxies, gateways, and self-hosted implementations may vary; this row claims the adapter, not the universe of compatible endpoints. | +| Anthropic | Tested | Native Anthropic | Uses anthropic-messages | +| Other Anthropic-compatible endpoint | Tested with limitations | Custom Anthropic-compatible | Adapter path validated with AWS Bedrock (`src/lib/onboard/bedrock-runtime.ts`). Behavior on other Anthropic-compatible proxies and gateways may vary; this row claims the adapter, not the universe of compatible endpoints. | +| Google Gemini | Tested | OpenAI-compatible | Uses Google's OpenAI-compatible endpoint | +| Hermes Provider | Hermes only | OpenAI-compatible route | Available when onboarding Hermes Agent through `nemohermes` | +| Local Ollama | Tested with limitations | Local Ollama API | Available when Ollama is installed or running on the host. Validated default models: `qwen3.6:35b` (high VRAM), `nemotron-3-nano:30b` (medium VRAM), `qwen3.5:9b` (low VRAM fallback). | +| Local NVIDIA NIM | Experimental | Local OpenAI-compatible | Requires `NEMOCLAW_EXPERIMENTAL=1` and a NIM-capable NVIDIA GPU. Host must have the NVIDIA Container Toolkit installed and a CDI spec present (`onboard` asserts CDI presence with `assertCdiNvidiaGpuSpecPresent`, `src/lib/onboard.ts:1581`). NIM images pull from `nvcr.io` and require NGC registry login. NemoClaw gates this path behind the experimental flag because it does not auto-select a NIM image for the host today. You must explicitly pick from the validated image list. Managed vLLM has host-specific default models and is not gated on the same boxes. Validated images referenced in `src/lib/inference/config.ts` and `nemoclaw/src/index.ts`: `nvidia/nemotron-3-super-120b-a12b` (default cloud model), `nvidia/nemotron-3-nano-30b-a3b`, `nvidia/llama-3.3-nemotron-super-49b-v1.5`. | +| Local vLLM (already running) | Tested with limitations | Local OpenAI-compatible | Appears in the onboarding menu when NemoClaw detects a server already on `localhost:8000`. No flag required. Model is whatever the existing server serves. | +| Local vLLM (managed install/start) | Tested with limitations | Local OpenAI-compatible | Appears by default on DGX Spark and DGX Station. Generic Linux NVIDIA GPU hosts require `NEMOCLAW_EXPERIMENTAL=1` or `NEMOCLAW_PROVIDER=install-vllm`. Host must have the NVIDIA Container Toolkit installed and a CDI spec present (`onboard` asserts CDI presence). NemoClaw pulls or starts the stable NGC vLLM container for each host profile. See `src/lib/inference/vllm.ts:55,177` for the pins. DGX Spark and DGX Station use `nvcr.io/nvidia/vllm:26.05.post1-py3`; generic Linux NVIDIA GPU hosts use `nvcr.io/nvidia/vllm:26.03.post1-py3`. Validated defaults are listed in `src/lib/inference/vllm-models.ts`: DGX Spark uses `nvidia/Qwen3.6-35B-A3B-NVFP4`, DGX Station uses `Qwen/Qwen3.6-27B-FP8`, and Linux NVIDIA GPU uses `nvidia/NVIDIA-Nemotron-3-Nano-4B-FP8`. Image pulls require NGC registry login (`docker login nvcr.io`); onboard prompts for the NGC API key when authentication is missing. | +{/* provider-status-full:end */} + +## Messaging integrations + +NemoClaw configures messaging channels during onboarding. The OpenShell gateway runs each channel as a supervised process; NemoClaw supplies onboarding, credential delivery, and policy presets for the sandbox egress rules. + +{/* integration-status:begin */} +| Channel | Status | Notes | +|---------|--------|-------| +| Slack | Tested | Configured through an OpenShell-managed channel during onboarding. Sandbox egress allowed by the `slack` policy preset. | +| Discord | Tested | Configured through an OpenShell-managed channel during onboarding. Sandbox egress allowed by the `discord` policy preset. | +| Telegram | Tested | Configured through an OpenShell-managed channel during onboarding. | +| WeChat | Tested with limitations | Channel hook available. Verify regional account access before relying on this path. | +| WhatsApp | Tested with limitations | Supported by both OpenClaw and Hermes (see `messaging_platforms` in `agents/openclaw/manifest.yaml` and `agents/hermes/manifest.yaml`). Pairing happens in the sandbox through WhatsApp Web by scanning a QR code at first run; the Hermes flow exposes this as `hermes whatsapp` and persists session credentials under `~/.hermes/platforms/whatsapp/session` (`agents/hermes/manifest.yaml:69-71`). Sandbox egress goes through the `whatsapp` policy preset, which carries the WebSocket / Noise / h1-ALPN caveats documented in `nemoclaw-blueprint/policies/presets/whatsapp.yaml`. No Meta Business API integration today; that path is out of scope for this matrix. | +{/* integration-status:end */} + +## Capabilities + +Each row below is a launch-facing capability claim that NemoClaw makes in docs, blog posts, or demos. Use the status to decide whether the claim is safe to repeat verbatim or needs a caveat. + +{/* capability-status:begin */} +| Capability | Status | Notes | +|------------|--------|-------| +| Guided onboarding | Tested | Single-command interactive wizard (`$$nemoclaw onboard`) that walks the user through inference provider selection, credential setup, sandbox creation, and dashboard launch. Non-interactive mode is supported with `--non-interactive` + `NEMOCLAW_*` environment variables for CI and scripted installs. | +| Sandboxed execution | Tested with limitations | Landlock, seccomp, network namespace isolation, no-new-privileges, privilege dropping, and process limits (ulimit -u 512 at `scripts/lib/sandbox-init.sh:237`) are tested and on by default. The `DANGEROUS_CAPS` list at `scripts/lib/sandbox-init.sh:288-299` drops cap_sys_admin, cap_sys_ptrace, cap_net_raw, cap_dac_override, cap_sys_chroot, cap_fsetid, cap_setfcap, cap_mknod, cap_audit_write, cap_net_bind_service with `capsh --drop` when CAP_SETPCAP is present. Limitation (active issue #3280): the fail-closed bounding-set gate is opt-in via `NEMOCLAW_REQUIRE_CAP_DROP=1`; the default is warn-and-continue so hosts without CAP_SETPCAP still boot, which means dangerous caps can remain in the bounding set on some hosts even though the effective set is empty. | +| Routed inference | Tested | Provider-routed model calls through the OpenShell gateway, transparent to the agent. The agent uses `inference.local` inside the sandbox; provider credentials stay on the host. Supports every entry in the Providers table. | +| Declarative network policy | Tested | YAML-defined egress with policy presets. Presets include `slack`, `discord`, `telegram`, `weather`, `openclaw-pricing`, `huggingface`, `npm`, `pypi`, `brew`, and others. Hot-reloadable at runtime with `$$nemoclaw <name> policy-add`. | +| Snapshot and restore | Tested | Create, list, and restore named snapshots of sandbox state with the `$$nemoclaw <name> snapshot` subcommands (`create`, `list`, `restore`). Credential stripping is enforced on capture. Unsafe symlinks are rejected on restore. | +| Agent skills | Tested | Packaged agent skills are discoverable by Cursor, Claude Code, and other coding assistants under `.agents/skills/`. Skills also install into the sandbox with `$$nemoclaw <name> skill install`. | +| State migration | Tested | Sandbox state migrates across rebuilds with credentials intentionally excluded. Hermes excludes `auth.json` and restores its SQLite session DB through the backup API. OpenClaw config merge prevents stale state from overwriting fresh values. | +| Blueprint versioning | Tested | Versioned, digest-verified, and reproducible blueprint lifecycle. Drives `$$nemoclaw <name> rebuild` and the migration safeguards above. | +| Web search backend | Tested with limitations | Runtime-configurable web-search backend plumbed through the OpenShell gateway. Brave is the currently-implemented backend. See `src/lib/onboard/brave-provider-profile.ts` and `src/lib/onboard/web-search-flow.ts`. Users supply backend credentials during an onboard prompt. NemoClaw does not bundle a key. | +{/* capability-status:end */} + +## Deployment paths + +How NemoClaw can be brought up on a given host. Pick the row that matches the target environment. + +{/* deployment-status:begin */} +| Path | Status | Notes | +|------|--------|-------| +| Local CLI onboard | Tested | Run `$$nemoclaw onboard` on a tested platform with Docker available locally. Primary path. | +| Remote GPU with Brev CLI | Tested with limitations | Legacy compatibility wrapper provisions a Brev VM, installs Docker + NVIDIA Container Toolkit, and runs `$$nemoclaw onboard` on that host. Defaults to GCP; override with `NEMOCLAW_BREV_PROVIDER`. The preferred path is the standard installer followed by `$$nemoclaw onboard` after the VM is reachable. | +| Brev web UI | Tested | Browser-driven launcher provisions a Brev-managed Linux VM with Docker, the OpenShell runtime, a NemoClaw sandbox running OpenClaw, inference routing, and the OpenClaw dashboard. | +{/* deployment-status:end */} + +## Out of scope and not supported + +The items below come up in conversations but are explicitly out of scope. They are listed here so launch material, sales conversations, and support triage have a clear "we do not claim to do this" reference. + +{/* out-of-scope:begin */} +| Item | Status | Why | +|------|--------|-----| +| Podman / other container runtimes | Unsupported | Onboard surfaces an explicit unsupported-runtime error for Podman (`src/lib/onboard.ts:1611` prints the rejection; `src/lib/onboard/preflight.ts:586` flags the unsupported runtime upstream). Only Docker Engine, Docker Desktop, and Colima are supported. See issue #420 (closed). | +| Intel Mac (macOS x86_64) | Unsupported | OpenShell does not publish macOS x86_64 standalone gateway assets. Install hard-fails on x86_64 macOS (`scripts/install-openshell.sh:315`). See issue #954 (closed). | +| Non-Ubuntu/Debian Linux distros | Unsupported | Installer assumes `apt-get`. Fedora/Rocky/Alma/Arch/NixOS are not validated and the installer's package-manager probes do not cover them. See open issue #899 (Fedora hang). | +| Native Kubernetes or OpenShift deployments | Unsupported | NemoClaw runs the sandbox as a Docker container, not a Kubernetes pod. The default Docker-driver topology does not embed k3s. Operator-managed K8s/OpenShift deployments are out of scope; see issue #407 (community OpenShift through agent-sandbox CRD). | +| Air-gapped / offline installs | Unsupported | Onboard assumes network reachability for package fetches, container pulls, and provider validation. See open issues #4872 and #2218 (production-deployment epic covering air-gapped support, China network guidance, multi-host topology). | +| Windows-on-ARM GPU passthrough | Unsupported | Windows-on-ARM CPU paths run under WSL2 'tested with limitations', but GPU passthrough on WOA is denylisted (`src/lib/onboard/wsl-docker-desktop-gpu.ts:188`, `src/lib/inference/gpu-trust.test.ts:70`). See closed issue #4565. | +| Non-NVIDIA GPUs (AMD/ROCm, Intel Arc, Apple Metal) | Unsupported | Local vLLM and NIM paths assert NVIDIA CDI presence with `assertCdiNvidiaGpuSpecPresent` (`src/lib/onboard.ts:1581`, called at `:1646`). NemoClaw does not install non-NVIDIA accelerator drivers. | +| Other LangChain, AutoGen, CrewAI, or non-listed agent harnesses | Unsupported | LangChain Deep Agents Code is the only integrated LangChain-family harness (see the Agents section above; status `Experimental`). Other LangChain harnesses, AutoGen, CrewAI, and any agent runtime not listed in the Agents table are not integrated. Bringing more harnesses is tracked as a research epic (see open issue #4861) but is not on the current roadmap. | +| Multi-user host sharing | Unsupported | Sandboxes are scoped to a single host user. NemoClaw treats multi-user hosts as a risk and warns at onboard; see `docs/security/openclaw-controls.mdx` Multi-user detection. | +| Hosted SaaS / managed NemoClaw | Unsupported | There is no managed offering. Supported deployment paths are Local CLI onboard, Remote GPU with Brev CLI, and Brev web UI. | +| Native provider integrations not in the Providers table | Unsupported | Vertex AI, Azure OpenAI, SageMaker, Together.ai, Replicate, and HuggingFace Inference Endpoints are not first-class onboarding entries. AWS Bedrock works through the `compatible-anthropic-endpoint` adapter (`src/lib/onboard/bedrock-runtime.ts`). | +| Production SLA or guaranteed response times | Unsupported | NemoClaw is an early-preview alpha project. Maintainers respond on a best-effort basis. No SLA is offered. | +{/* out-of-scope:end */} + +## Known caveats and active blockers + +- Sandbox bounding-set capability drop on hosts without `CAP_SETPCAP` is partially fixed. The agent process tree drops dangerous caps with `NEMOCLAW_REQUIRE_CAP_DROP=1` (see [#4707](https://github.com/NVIDIA/NemoClaw/pull/4707)). The `nemoclaw connect` shell still inherits the container's create-time bounding set on Colossus, Docker Desktop, and WSL hosts where `CAP_SETPCAP` is absent. The remaining fix is upstream in [NVIDIA/OpenShell#1452](https://github.com/NVIDIA/OpenShell/issues/1452). See tracking [#3280](https://github.com/NVIDIA/NemoClaw/issues/3280). + +## Using this matrix + +- Docs and READMEs that reference any row above should link to this page instead of restating status. Partial tables, such as the prerequisites page, generate from the same JSON and stay in sync with `scripts/generate-platform-docs.py`. +- Demos and launch material should cite the status verbatim. A "Tested with limitations" row is not a "Tested" row. +- Customer support can use the matrix to triage incoming reports. A failure on a Tested row is a bug. A failure on a Deferred row is an unsupported configuration request. A failure on an Unsupported row is a feature request that needs separate triage. +- Roadmap changes land in the JSON first, then propagate to this page on the next generator run. + +## Updating the matrix + +1. Edit [`ci/platform-matrix.json`](https://github.com/NVIDIA/NemoClaw/blob/main/ci/platform-matrix.json). +2. Run `python3 scripts/generate-platform-docs.py` to regenerate this page and the partial tables on prerequisites and inference-options. +3. Open a PR. The engineering owner team is auto-assigned through CODEOWNERS and explicitly acknowledges launch impact in the PR review for any launch-facing claim change. +4. The `generate-platform-docs.py --check` step in pre-commit fails if the docs drift from the JSON. diff --git a/docs/reference/troubleshooting.mdx b/docs/reference/troubleshooting.mdx index 6ceac31cc0d..fb88faa8ddd 100644 --- a/docs/reference/troubleshooting.mdx +++ b/docs/reference/troubleshooting.mdx @@ -398,19 +398,19 @@ The in-sandbox OpenClaw gateway can drop its HTTP listener while its process sta A restart-class configuration change makes the gateway restart itself in place, and if that restart fails the process parks with no listener (`/tmp/gateway.log` shows `gateway startup failed: ... Process will stay alive`). Docker then marks the container `(unhealthy)` even though `pgrep` still finds the gateway. -NemoClaw prevents and self-heals this: +NemoClaw prevents this state and recovers it when it happens: - The generated sandbox config pins `gateway.reload.mode` to `hot`, so configuration changes never make the gateway restart itself out from under the sandbox supervisor. - A serving watchdog inside the sandbox kills a gateway that stops listening after it has served, and the supervisor relaunches it (look for `[gateway-watchdog]` lines in `$$nemoclaw logs`). -Because of the `hot` pin, restart-class configuration changes made inside the sandbox — for example `openclaw plugins install` — log `config reload requires gateway restart; hot mode ignoring` and do not take effect until the gateway restarts. +Because of the `hot` pin, restart-class configuration changes made inside the sandbox, for example `openclaw plugins install`, log `config reload requires gateway restart; hot mode ignoring` and do not take effect until the gateway restarts. Apply them with a supervised restart: ```bash $$nemoclaw recover ``` -or rebuild the sandbox for changes that affect provisioning: +For changes that affect provisioning, rebuild the sandbox: ```bash $$nemoclaw rebuild --yes diff --git a/scripts/docs-to-skills.py b/scripts/docs-to-skills.py index 14d7b935529..e925d8b8a30 100755 --- a/scripts/docs-to-skills.py +++ b/scripts/docs-to-skills.py @@ -422,6 +422,7 @@ def parse_doc(path: Path, doc_platform: str = "myst-md") -> DocPage: fm, body = parse_yaml_frontmatter(raw) if doc_platform == "fern-mdx": body = body.replace("$$nemoclaw", "nemoclaw") + body = body.replace("$$nemohermes", "nemohermes") body = strip_commented_out_blocks(body) page = DocPage(path=path, raw=raw, frontmatter=fm, body=body) diff --git a/scripts/generate-platform-docs.py b/scripts/generate-platform-docs.py index 391f8b9ac1e..a3e8f5fc1da 100755 --- a/scripts/generate-platform-docs.py +++ b/scripts/generate-platform-docs.py @@ -43,6 +43,69 @@ REPO_ROOT / "docs" / "inference" / "inference-options.mdx", ], ), + ( + "platform-matrix-full", + "platforms_full", + [ + REPO_ROOT / "docs" / "reference" / "platform-support.mdx", + ], + ), + ( + "provider-status-full", + "providers_full", + [ + REPO_ROOT / "docs" / "reference" / "platform-support.mdx", + ], + ), + ( + "agent-status", + "agents", + [ + REPO_ROOT / "docs" / "reference" / "platform-support.mdx", + ], + ), + ( + "integration-status", + "integrations", + [ + REPO_ROOT / "docs" / "reference" / "platform-support.mdx", + ], + ), + ( + "deployment-status", + "deployment_paths", + [ + REPO_ROOT / "docs" / "reference" / "platform-support.mdx", + ], + ), + ( + "capability-status", + "capabilities", + [ + REPO_ROOT / "docs" / "reference" / "platform-support.mdx", + ], + ), + ( + "out-of-scope", + "out_of_scope", + [ + REPO_ROOT / "docs" / "reference" / "platform-support.mdx", + ], + ), + ( + "project-status", + "project_status", + [ + REPO_ROOT / "docs" / "reference" / "platform-support.mdx", + ], + ), + ( + "matrix-owners", + "owners", + [ + REPO_ROOT / "docs" / "reference" / "platform-support.mdx", + ], + ), ] @@ -65,17 +128,120 @@ def load_matrix() -> dict: return json.load(f) +# Strings that should never reach a generated page as a real value. Owner +# fields are reviewed gates for launch-facing claims; placeholder text means +# the gate is undefined and the docs would ship with an unresolved sign-off +# path. Matched case-insensitively against the raw field value. +_PLACEHOLDER_OWNER_VALUES = ( + "", + "tbd", + "todo", + "fixme", + "see pr review", + "n/a", + "none", +) + + +def _is_placeholder_owner(value: str) -> bool: + raw = (value or "").strip().lower() + if not raw: + return True + if raw in _PLACEHOLDER_OWNER_VALUES: + return True + # Catch composite forms like "TBD (see PR review)" or "TODO: pick someone". + for marker in ("tbd", "todo", "fixme", "see pr review"): + if marker in raw: + return True + return False + + +def _escape_cell(value) -> str: + """Escape Markdown table cells for safe MDX rendering. + + `|` breaks the column count; literal newlines break the row layout (an + embedded newline turns one row into two malformed rows). `<` and `>` are + HTML control characters in MDX, so a future matrix edit that contains + `")) +`); + const sections = output.split("---\n").map((s) => s.trim()); + expect(sections[0]).toBe("a\\|b"); + expect(sections[1]).toBe("first second"); + // CRLF is collapsed to a single space (the \r\n branch runs first). + expect(sections[2]).toBe("crlf line"); + expect(sections[3]).toBe("<MyComponent prop='x' />"); + expect(sections[4]).toBe("<script>alert(1)</script>"); + }); + + it("escapes MDX expression braces in table cells", () => { + const output = runPython(` +${loadGeneratorAs("g")} + +# MDX evaluates {expression}. A future matrix note that mentions a +# JSON snippet or destructuring pattern should not get parsed as JSX. +print(module._escape_cell("{user.name}")) +print("---") +print(module._escape_cell("config = {key: value}")) +`); + const sections = output.split("---\n").map((s) => s.trim()); + expect(sections[0]).toBe("{user.name}"); + expect(sections[1]).toBe("config = {key: value}"); + }); + + it("escapes pipes when rendered through a real platform table row", () => { + const output = runPython(` +${loadGeneratorAs("g")} +import json + +platforms = [{"name": "Pipe|Name", "runtimes": ["A|B"], "status": "tested", "notes": "a|b note"}] +print(module.generate_platform_table(platforms)) +`); + const dataRow = output.trim().split("\n").at(-1) ?? ""; + expect(dataRow).toContain("Pipe\\|Name"); + expect(dataRow).toContain("A\\|B"); + expect(dataRow).toContain("a\\|b note"); + // A row with N escaped pipes inside cells still has exactly 5 unescaped + // pipes (4 columns → 5 separators); the escaped ones are preceded by `\`. + const unescapedPipes = dataRow.match(/(? { + const output = runPython(` +${loadGeneratorAs("g")} + +bad = { + "statuses": {"tested": "Validated.", "caveated": "Limited."}, + "owners": {"engineering": "@NVIDIA/nemoclaw-maintainer"}, + "platforms": [{"name": "X", "runtimes": ["Docker"], "status": "shipped", "notes": "n"}], + "providers": [], "agents": [], "integrations": [], + "deployment_paths": [], "capabilities": [], "out_of_scope": [] +} +try: + module._validate_matrix(bad) + print("NO_ERROR") +except ValueError as exc: + print(str(exc)) +`); + expect(output).toContain("unknown status"); + expect(output).toContain("'shipped'"); + expect(output).not.toContain("NO_ERROR"); + }); + + it("rejects placeholder owner values (TBD, TODO, see PR review, empty)", () => { + const output = runPython(` +${loadGeneratorAs("g")} + +cases = ["TBD (see PR review)", "TBD", "TODO: pick", "FIXME", "see PR review", "", "n/a"] +for raw in cases: + matrix = { + "statuses": {"tested": "Validated."}, + "owners": {"engineering": raw}, + "platforms": [], "providers": [], "agents": [], "integrations": [], + "deployment_paths": [], "capabilities": [], "out_of_scope": [] + } + try: + module._validate_matrix(matrix) + print(f"ACCEPTED:{raw!r}") + except ValueError: + print(f"REJECTED:{raw!r}") +`); + const lines = output.trim().split("\n"); + expect(lines.every((line) => line.startsWith("REJECTED:"))).toBe(true); + }); + + it("accepts a real engineering owner alias", () => { + const output = runPython(` +${loadGeneratorAs("g")} + +matrix = { + "statuses": {"tested": "Validated."}, + "owners": {"engineering": "@NVIDIA/nemoclaw-maintainer"}, + "platforms": [], "providers": [], "agents": [], "integrations": [], + "deployment_paths": [], "capabilities": [], "out_of_scope": [] +} +module._validate_matrix(matrix) +print("OK") +`); + expect(output.trim()).toBe("OK"); + }); + + // PRA-4 on #5345: the partial provider table renders the canonical label + // for caveated entries, omits deferred entries, and escapes pipes across + // name, endpoint type, and notes so a future matrix edit cannot break the + // launch-claims page. + it("provider table uses canonical labels, excludes deferred entries, and escapes pipes across all cells", () => { + const output = runPython(` +${loadGeneratorAs("g")} + +providers = [ + {"name": "Caveated|Provider", "status": "caveated", "endpoint_type": "Type|A", "notes": "note|A"}, + {"name": "Deferred|Provider", "status": "deferred", "endpoint_type": "Type|B", "notes": "note|B"}, +] +print(module.generate_provider_table(providers)) +`); + const lines = output.trim().split("\n"); + const dataRows = lines.slice(2); + expect(dataRows).toHaveLength(1); + const row = dataRows[0]; + expect(row).toContain("Caveated\\|Provider"); + expect(row).toContain("Tested with limitations"); + expect(row).not.toContain("Caveated |"); + expect(row).toContain("Type\\|A"); + expect(row).toContain("note\\|A"); + expect(output).not.toContain("Deferred\\|Provider"); + }); + + it("full platform table includes deferred rows; partial table excludes them", () => { + const output = runPython(` +${loadGeneratorAs("g")} + +platforms = [ + {"name": "Linux", "runtimes": ["Docker"], "status": "tested", "ci_tested": True, "notes": "n"}, + {"name": "WSL", "runtimes": ["Docker"], "status": "deferred", "ci_tested": False, "notes": "later"} +] +print("PARTIAL:") +print(module.generate_platform_table(platforms)) +print("FULL:") +print(module.generate_platform_table_full(platforms)) +`); + const [partial, full] = output.split("FULL:"); + expect(partial).toContain("Linux"); + expect(partial).not.toContain("WSL"); + expect(full).toContain("Linux"); + expect(full).toContain("WSL"); + }); + + it("--check exits non-zero on placeholder owner in real matrix", () => { + const tmp = mkdtempSync(path.join(tmpdir(), "genplatform-")); + const matrixPath = path.join(tmp, "matrix.json"); + writeFileSync( + matrixPath, + JSON.stringify({ + statuses: { tested: "Validated." }, + owners: { engineering: "TBD" }, + platforms: [], + providers: [], + agents: [], + integrations: [], + deployment_paths: [], + capabilities: [], + out_of_scope: [], + }), + ); + + const result = spawnSync( + "python3", + [ + "-c", + ` +${loadGeneratorAs("g")} +matrix = module.load_matrix.__globals__["json"].load(open("${matrixPath}")) +try: + module._validate_matrix(matrix) + raise SystemExit(0) +except ValueError as exc: + print(str(exc)) + raise SystemExit(2) +`, + SCRIPT_PATH, + ], + { encoding: "utf-8" }, + ); + expect(result.status).toBe(2); + // Either error path is acceptable: engineering-is-placeholder OR + // engineering-must-be-real-alias. Just assert it surfaced as a validation error. + expect(`${result.stdout}${result.stderr}`).toMatch(/owners\.engineering|placeholder/); + }); + + it("generate_owners_block emits engineering owner only (no product owner row)", () => { + const output = runPython(` +${loadGeneratorAs("g")} + +block = module.generate_owners_block({"engineering": "@NVIDIA/nemoclaw-maintainer"}) +print(block) +`); + expect(output).toContain("Engineering owner:"); + expect(output).toContain("@NVIDIA/nemoclaw-maintainer"); + expect(output).not.toContain("Product owner"); + expect(output).not.toContain("TBD"); + }); + + // PRA-3 on #5345: semantic regression tests for launch-claim and + // credential-boundary invariants. Each test reads the actual matrix and + // docs at the PR head, not a fixture, so a future edit that breaks the + // invariant fails this suite before the change ships. + it("every `--agent ` example across matrix, docs, and generated skills resolves to a manifest whose name field agrees", () => { + const repoRoot = path.join(import.meta.dirname, ".."); + const matrix = JSON.parse( + readFileSync(path.join(repoRoot, "ci", "platform-matrix.json"), "utf-8"), + ); + const onboardExample = /(?:\$\$)?nemoclaw onboard --agent ([a-z0-9-]+)/g; + const agentIds = new Set(); + for (const section of ["agents", "out_of_scope"] as const) { + for (const row of matrix[section] ?? []) { + const notes: string = row.notes ?? ""; + for (const match of notes.matchAll(onboardExample)) agentIds.add(match[1]); + } + } + const docTargets = [ + "docs/get-started/quickstart-langchain-deepagents-code.mdx", + "docs/reference/platform-support.mdx", + ".agents/skills/nemoclaw-user-reference/references/platform-support.md", + "skills/nemoclaw-user-reference/references/platform-support.md", + ].filter((rel) => existsSync(path.join(repoRoot, rel))); + for (const rel of docTargets) { + const body = readFileSync(path.join(repoRoot, rel), "utf-8"); + for (const match of body.matchAll(onboardExample)) agentIds.add(match[1]); + } + expect(agentIds.size).toBeGreaterThan(0); + const agentsRoot = path.join(repoRoot, "agents"); + for (const id of agentIds) { + const manifest = path.join(agentsRoot, id, "manifest.yaml"); + expect( + existsSync(manifest), + `\`--agent ${id}\` advertised somewhere in matrix/docs/skills but agents/${id}/manifest.yaml is missing`, + ).toBe(true); + const manifestBody = readFileSync(manifest, "utf-8"); + const nameMatch = manifestBody.match(/^name:\s*([a-z0-9-]+)\s*$/m); + expect(nameMatch?.[1], `agents/${id}/manifest.yaml lacks a name field`).toBeDefined(); + expect( + nameMatch?.[1], + `agents/${id}/manifest.yaml declares name ${nameMatch?.[1]}, breaking the loader contract for documented \`--agent ${id}\``, + ).toBe(id); + } + }); + + it("out-of-scope LangChain row scopes itself and names Deep Agents Code as the integrated exception", () => { + const matrixPath = path.join(import.meta.dirname, "..", "ci", "platform-matrix.json"); + const matrix = JSON.parse(readFileSync(matrixPath, "utf-8")); + const langchainRow = (matrix.out_of_scope ?? []).find( + (row: { name: string; notes: string }) => + /LangChain/i.test(row.name) || /LangChain/i.test(row.notes), + ); + expect(langchainRow, "expected an out_of_scope row mentioning LangChain").toBeDefined(); + expect(langchainRow.name + " " + langchainRow.notes).toMatch(/Deep Agents Code/); + expect(langchainRow.notes).not.toMatch(/Only OpenClaw and Hermes are integrated\.?\s*$/); + }); + + it("every `path:line` citation embedded in matrix notes resolves to a non-empty line in the repo", () => { + const repoRoot = path.join(import.meta.dirname, ".."); + const matrix = JSON.parse(readFileSync(path.join(repoRoot, "ci", "platform-matrix.json"), "utf-8")); + const citationRe = /([a-z][a-z0-9_/.-]*\.(?:ts|sh|py|yaml|yml|mdx|md|json)):(\d+)/gi; + const citations: Array<{ section: string; file: string; line: number }> = []; + for (const section of [ + "platforms", + "providers", + "agents", + "integrations", + "deployment_paths", + "capabilities", + "out_of_scope", + ] as const) { + for (const row of matrix[section] ?? []) { + const notes: string = row.notes ?? ""; + for (const match of notes.matchAll(citationRe)) { + citations.push({ section, file: match[1], line: Number(match[2]) }); + } + } + } + expect(citations.length).toBeGreaterThan(0); + for (const { section, file, line } of citations) { + const fullPath = path.join(repoRoot, file); + expect( + existsSync(fullPath), + `${section} row cites ${file}:${line} but ${file} is missing`, + ).toBe(true); + const fileBody = readFileSync(fullPath, "utf-8").split(/\r?\n/); + expect( + line <= fileBody.length, + `${section} row cites ${file}:${line} but ${file} only has ${fileBody.length} lines`, + ).toBe(true); + expect( + fileBody[line - 1].trim(), + `${section} row cites ${file}:${line} but that line is empty`, + ).not.toBe(""); + } + }); + + it("sub-agent credential guide retains safe temp-file and boundary-warning properties across source and generated skill copies", () => { + const repoRoot = path.join(import.meta.dirname, ".."); + const targets = [ + "docs/inference/set-up-sub-agent.mdx", + ".agents/skills/nemoclaw-user-configure-inference/references/set-up-sub-agent.md", + "skills/nemoclaw-user-configure-inference/references/set-up-sub-agent.md", + ]; + for (const rel of targets) { + const body = readFileSync(path.join(repoRoot, rel), "utf-8"); + expect(body, `${rel} missing umask 077`).toMatch(/umask 077/); + expect(body, `${rel} missing mktemp -d`).toMatch(/mktemp -d/); + expect(body, `${rel} missing trap EXIT cleanup`).toMatch(/trap .* EXIT/); + expect(body, `${rel} missing credential-boundary callout`).toMatch(/credential-bearing/); + expect( + body, + `${rel} missing the /proc readability caveat that distinguishes env delivery from full process isolation`, + ).toMatch(/\/proc/); + expect(body, `${rel} still passes \$NVIDIA_API_KEY via argv`).not.toMatch( + /python3 [^\n]*"\$NVIDIA_API_KEY"/, + ); + expect( + body, + `${rel} reintroduces a fixed secret-bearing /tmp/auth-profiles.json output`, + ).not.toMatch(/\/tmp\/auth-profiles\.json/); + expect( + body, + `${rel} reintroduces a fixed secret-bearing /tmp/openclaw\\.updated\\.json output`, + ).not.toMatch(/\/tmp\/openclaw\.updated\.json/); + expect( + body, + `${rel} exports openclaw.json to a fixed /tmp path instead of the protected $WORK_DIR`, + ).not.toMatch(/\/tmp\/openclaw\.json/); + } + }); +});