diff --git a/.agents/skills/update-docs/SKILL.md b/.agents/skills/nemoclaw-contributor-update-docs/SKILL.md similarity index 99% rename from .agents/skills/update-docs/SKILL.md rename to .agents/skills/nemoclaw-contributor-update-docs/SKILL.md index a876ca0c9..680026ef9 100644 --- a/.agents/skills/update-docs/SKILL.md +++ b/.agents/skills/nemoclaw-contributor-update-docs/SKILL.md @@ -1,5 +1,5 @@ --- -name: update-docs +name: nemoclaw-contributor-update-docs description: Scan recent git commits for changes that affect user-facing behavior, then draft or update the corresponding documentation pages. Use when docs have fallen behind code changes, after a batch of features lands, or when preparing a release. Trigger keywords - update docs, draft docs, docs from commits, sync docs, catch up docs, doc debt, docs behind, docs drift. --- diff --git a/.agents/skills/cut-release-tag/SKILL.md b/.agents/skills/nemoclaw-maintainer-cut-release-tag/SKILL.md similarity index 98% rename from .agents/skills/cut-release-tag/SKILL.md rename to .agents/skills/nemoclaw-maintainer-cut-release-tag/SKILL.md index 488d3d32d..710a0c615 100644 --- a/.agents/skills/cut-release-tag/SKILL.md +++ b/.agents/skills/nemoclaw-maintainer-cut-release-tag/SKILL.md @@ -1,5 +1,5 @@ --- -name: cut-release-tag +name: nemoclaw-maintainer-cut-release-tag description: Cut a new semver release tag on main, move the `latest` tag, and push. Use when cutting a release, tagging a version, shipping a build, or preparing a deployment. Trigger keywords - cut tag, release tag, new tag, cut release, tag version, ship it. user_invocable: true --- diff --git a/.agents/skills/find-review-pr/SKILL.md b/.agents/skills/nemoclaw-maintainer-find-review-pr/SKILL.md similarity index 98% rename from .agents/skills/find-review-pr/SKILL.md rename to .agents/skills/nemoclaw-maintainer-find-review-pr/SKILL.md index dce8d5fc1..071b74b30 100644 --- a/.agents/skills/find-review-pr/SKILL.md +++ b/.agents/skills/nemoclaw-maintainer-find-review-pr/SKILL.md @@ -1,5 +1,5 @@ --- -name: find-review-pr +name: nemoclaw-maintainer-find-review-pr description: Finds open GitHub PRs with security and priority-high labels, links each to its issue, detects duplicates (multiple PRs fixing the same issue), and presents a table of review candidates. Use when looking for the next PR to review. Trigger keywords - find pr, find review, next pr, pr to review, duplicate pr, security pr. user_invocable: true --- diff --git a/.agents/skills/security-code-review/SKILL.md b/.agents/skills/nemoclaw-maintainer-security-code-review/SKILL.md similarity index 99% rename from .agents/skills/security-code-review/SKILL.md rename to .agents/skills/nemoclaw-maintainer-security-code-review/SKILL.md index db79ab640..86af1fd9a 100644 --- a/.agents/skills/security-code-review/SKILL.md +++ b/.agents/skills/nemoclaw-maintainer-security-code-review/SKILL.md @@ -1,5 +1,5 @@ --- -name: security-code-review +name: nemoclaw-maintainer-security-code-review description: Performs a comprehensive security review of code changes in a GitHub PR or issue. Checks out the branch, analyzes changed files against a 9-category security checklist, and produces PASS/WARNING/FAIL verdicts. Use when reviewing pull requests for security vulnerabilities, hardcoded secrets, injection flaws, auth bypasses, or insecure configurations. Trigger keywords - security review, code review, appsec, vulnerability assessment, security audit, review PR security. user_invocable: true --- diff --git a/.agents/skills/nemoclaw-reference/references/inference-profiles.md b/.agents/skills/nemoclaw-reference/references/inference-profiles.md deleted file mode 100644 index 2920cdbe5..000000000 --- a/.agents/skills/nemoclaw-reference/references/inference-profiles.md +++ /dev/null @@ -1,78 +0,0 @@ -# Inference Profiles - -NemoClaw configures inference through the OpenShell gateway. -The agent inside the sandbox talks to `inference.local`, and OpenShell routes that traffic to the provider you selected during onboarding. - -## Routed Provider Model - -NemoClaw keeps provider credentials on the host. -The sandbox does not receive your raw OpenAI, Anthropic, Gemini, or NVIDIA API key. - -At onboard time, NemoClaw configures: - -- an OpenShell provider -- an OpenShell inference route -- the baked OpenClaw model reference inside the sandbox - -That means the sandbox knows which model family to use, while OpenShell owns the actual provider credential and upstream endpoint. - -## Supported Providers - -The following non-experimental provider paths are available through `nemoclaw onboard`. - -| Provider | Endpoint Type | Notes | -|---|---|---| -| NVIDIA Endpoints | OpenAI-compatible | Hosted models on `integrate.api.nvidia.com` | -| OpenAI | Native OpenAI-compatible | Uses OpenAI model IDs | -| Other OpenAI-compatible endpoint | Custom OpenAI-compatible | For compatible proxies and gateways | -| Anthropic | Native Anthropic | Uses `anthropic-messages` | -| Other Anthropic-compatible endpoint | Custom Anthropic-compatible | For Claude proxies and compatible gateways | -| Google Gemini | OpenAI-compatible | Uses Google's OpenAI-compatible endpoint | - -## Validation During Onboarding - -NemoClaw validates the selected provider and model before it creates the sandbox. - -- OpenAI-compatible providers: - NemoClaw tries `/responses` first, then `/chat/completions`. -- Anthropic-compatible providers: - NemoClaw tries `/v1/messages`. -- NVIDIA Endpoints manual model entry: - NemoClaw also validates the model name against `https://integrate.api.nvidia.com/v1/models`. -- Compatible endpoint flows: - NemoClaw validates by sending a real inference request, because many proxies do not expose a reliable `/models` endpoint. - -If validation fails, the wizard does not continue to sandbox creation. - -## Local Ollama - -Local Ollama is available in the standard onboarding flow when Ollama is installed or running on the host. -It uses the same routed `inference.local` pattern, but the upstream runtime runs locally instead of in the cloud. - -Ollama gets additional onboarding help: - -- if no models are installed, NemoClaw offers starter models -- it pulls the selected model -- it warms the model -- it validates the model before continuing - -On Linux hosts that run NemoClaw with Docker, the sandbox reaches Ollama through `http://host.openshell.internal:11434`, not the host shell's `localhost` socket. -If Ollama is already running, make sure it listens on `0.0.0.0:11434` instead of `127.0.0.1:11434`. -Run the following command to start Ollama with that bind address. - -```console -$ OLLAMA_HOST=0.0.0.0:11434 ollama serve -``` - -If Ollama only binds loopback, NemoClaw can detect it on the host, but the sandbox-side validation step fails because containers cannot reach it. - -## Experimental Local Providers - -The following local providers require `NEMOCLAW_EXPERIMENTAL=1`: - -- Local NVIDIA NIM (requires a NIM-capable GPU) -- Local vLLM (must already be running on `localhost:8000`) - -## Runtime Switching - -For runtime switching guidance, refer to Switch Inference Models (see the `nemoclaw-configure-inference` skill). diff --git a/.agents/skills/nemoclaw-skills-guide/SKILL.md b/.agents/skills/nemoclaw-skills-guide/SKILL.md new file mode 100644 index 000000000..ca7b2e1d8 --- /dev/null +++ b/.agents/skills/nemoclaw-skills-guide/SKILL.md @@ -0,0 +1,85 @@ +--- +name: "nemoclaw-skills-guide" +description: "Start here. Introduces what NemoClaw is, what agent skills are available, and which skill to use for a given task. Use when discovering NemoClaw capabilities, choosing the right skill, or orienting in the project. Trigger keywords - skills, capabilities, what can I do, help, guide, index, overview, start here." +--- + +# NemoClaw Skills Guide + +NVIDIA NemoClaw runs OpenClaw always-on assistants inside hardened OpenShell sandboxes with NVIDIA inference (Nemotron). +It provides CLI tooling, guided onboarding, a security blueprint, routed inference, and workspace management. + +This guide lists every agent skill shipped with NemoClaw, organized by audience. +Load the specific skill you need after identifying it here. + +## Skill Buckets + +Skills are grouped into three buckets by audience. +The prefix in each skill name indicates who it is for. + +### `nemoclaw-user-*` (9 skills) + +For end users operating a NemoClaw sandbox. +Covers installation, inference configuration, network policy management, monitoring, remote deployment, security configuration, workspace management, and reference material. + +### `nemoclaw-maintainer-*` (3 skills) + +For project maintainers. +Covers cutting releases, finding PRs to review, and performing security code reviews. + +### `nemoclaw-contributor-*` (1 skill) + +For contributors to the NemoClaw codebase. +Covers drafting documentation updates from recent commits. + +## Skill Catalog + +### User Skills + +| Skill | Summary | +|-------|---------| +| `nemoclaw-user-overview` | What NemoClaw is, ecosystem placement (OpenClaw + OpenShell + NemoClaw), how it works internally, and release notes. | +| `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). | +| `nemoclaw-user-monitor-sandbox` | Check sandbox health, read logs, and trace agent behavior to diagnose problems. | +| `nemoclaw-user-deploy-remote` | Deploy NemoClaw to a remote GPU instance, set up the Telegram bridge, and review sandbox container hardening. | +| `nemoclaw-user-configure-security` | Review the risk framework for every configurable security control, understand credential storage, and assess posture trade-offs. | +| `nemoclaw-user-workspace` | Back up and restore OpenClaw workspace files (soul.md, identity.md, memory.md, agents.md) and understand file persistence across sandbox restarts. | +| `nemoclaw-user-reference` | CLI command reference, plugin and blueprint architecture, baseline network policies, and troubleshooting guide. | + +### Maintainer Skills + +| Skill | Summary | +|-------|---------| +| `nemoclaw-maintainer-cut-release-tag` | Cut an annotated semver tag on main, move the `latest` floating tag, and push both to origin. | +| `nemoclaw-maintainer-find-review-pr` | Find open PRs labeled security + priority-high, link each to its issue, detect duplicates, and present a review summary. | +| `nemoclaw-maintainer-security-code-review` | Perform a 9-category security review of a PR or issue, producing per-category PASS/WARNING/FAIL verdicts. | + +### Contributor Skills + +| Skill | Summary | +|-------|---------| +| `nemoclaw-contributor-update-docs` | Scan recent git commits for user-facing changes and draft or update the corresponding documentation pages. | + +## Quick Decision Guide + +Use this table to jump directly to the right skill. + +| I want to... | Load this skill | +|---------------|-----------------| +| Install NemoClaw or onboard for the first time | `nemoclaw-user-get-started` | +| Understand what NemoClaw is or how it fits together | `nemoclaw-user-overview` | +| Switch my inference provider or model | `nemoclaw-user-configure-inference` | +| Set up a local model server (Ollama, vLLM, NIM) | `nemoclaw-user-configure-inference` | +| Approve or deny a blocked network request | `nemoclaw-user-manage-policy` | +| Add or remove endpoints from the network policy | `nemoclaw-user-manage-policy` | +| Check sandbox logs, status, or health | `nemoclaw-user-monitor-sandbox` | +| Deploy to a remote GPU or cloud instance | `nemoclaw-user-deploy-remote` | +| Set up Telegram or a chat bridge | `nemoclaw-user-deploy-remote` | +| Review security controls or credential storage | `nemoclaw-user-configure-security` | +| Back up or restore workspace files | `nemoclaw-user-workspace` | +| Look up a CLI command or troubleshoot an error | `nemoclaw-user-reference` | +| Cut a new release tag | `nemoclaw-maintainer-cut-release-tag` | +| Find the next PR to review | `nemoclaw-maintainer-find-review-pr` | +| Security review a pull request | `nemoclaw-maintainer-security-code-review` | +| Update docs after landing code changes | `nemoclaw-contributor-update-docs` | diff --git a/.agents/skills/nemoclaw-user-configure-inference/SKILL.md b/.agents/skills/nemoclaw-user-configure-inference/SKILL.md new file mode 100644 index 000000000..63e1a0e72 --- /dev/null +++ b/.agents/skills/nemoclaw-user-configure-inference/SKILL.md @@ -0,0 +1,342 @@ +--- +name: "nemoclaw-user-configure-inference" +description: "Lists all inference providers offered during NemoClaw onboarding. Use when explaining which providers are available, what the onboard wizard presents, or how inference routing works. Changes the active inference model without restarting the sandbox. Use when switching inference providers, changing the model runtime, or reconfiguring inference routing. Connects NemoClaw to a local inference server. Use when setting up Ollama, vLLM, TensorRT-LLM, NIM, or any OpenAI-compatible local model server with NemoClaw." +--- + +# NemoClaw User Configure Inference + +Lists all inference providers offered during NemoClaw onboarding. Use when explaining which providers are available, what the onboard wizard presents, or how inference routing works. + +## Context + +NemoClaw supports multiple inference providers. +During onboarding, the `nemoclaw onboard` wizard presents a numbered list of providers to choose from. +Your selection determines where the agent's inference traffic is routed. + +## How Inference Routing Works + +The agent inside the sandbox talks to `inference.local`. +It never connects to a provider directly. +OpenShell intercepts inference traffic on the host and forwards it to the provider you selected. + +Provider credentials stay on the host. +The sandbox does not receive your API key. + +## Provider Options + +The onboard wizard presents the following provider options by default. +The first six are always available. +Ollama appears when it is installed or running on the host. + +| Option | Description | Curated models | +|--------|-------------|----------------| +| NVIDIA Endpoints | Routes to models hosted on [build.nvidia.com](https://build.nvidia.com). You can also enter any model ID from the catalog. Set `NVIDIA_API_KEY`. | Nemotron 3 Super 120B, Kimi K2.5, GLM-5, MiniMax M2.5, GPT-OSS 120B | +| OpenAI | Routes to the OpenAI API. Set `OPENAI_API_KEY`. | `gpt-5.4`, `gpt-5.4-mini`, `gpt-5.4-nano`, `gpt-5.4-pro-2026-03-05` | +| Other OpenAI-compatible endpoint | Routes to any server that implements `/v1/chat/completions`. If the endpoint also supports `/responses` with OpenClaw-style tool calling, NemoClaw can use that path; otherwise it falls back to `/chat/completions`. The wizard prompts for a base URL and model name. Works with OpenRouter, LocalAI, llama.cpp, or any compatible proxy. Set `COMPATIBLE_API_KEY`. | You provide the model name. | +| Anthropic | Routes to the Anthropic Messages API. Set `ANTHROPIC_API_KEY`. | `claude-sonnet-4-6`, `claude-haiku-4-5`, `claude-opus-4-6` | +| Other Anthropic-compatible endpoint | Routes to any server that implements the Anthropic Messages API (`/v1/messages`). The wizard prompts for a base URL and model name. Set `COMPATIBLE_ANTHROPIC_API_KEY`. | You provide the model name. | +| Google Gemini | Routes to Google's OpenAI-compatible endpoint. NemoClaw prefers `/responses` only when the endpoint proves it can handle tool calling in a way OpenClaw uses; otherwise it falls back to `/chat/completions`. Set `GEMINI_API_KEY`. | `gemini-3.1-pro-preview`, `gemini-3.1-flash-lite-preview`, `gemini-3-flash-preview`, `gemini-2.5-pro`, `gemini-2.5-flash`, `gemini-2.5-flash-lite` | +| Local Ollama | Routes to a local Ollama instance on `localhost:11434`. NemoClaw detects installed models, offers starter models if none are present, pulls and warms the selected model, and validates it. | Selected during onboarding. For more information, refer to Use a Local Inference Server (see the `nemoclaw-user-configure-inference` skill). | + +## Experimental Options + +The following local inference options require `NEMOCLAW_EXPERIMENTAL=1` and, when prerequisites are met, appear in the onboarding selection list. + +| Option | Condition | Notes | +|--------|-----------|-------| +| Local NVIDIA NIM | NIM-capable GPU detected | Pulls and manages a NIM container. | +| Local vLLM | vLLM running on `localhost:8000` | Auto-detects the loaded model. | + +For setup instructions, refer to Use a Local Inference Server (see the `nemoclaw-user-configure-inference` skill). + +## Validation + +NemoClaw validates the selected provider and model before creating the sandbox. +If validation fails, the wizard returns to provider selection. + +| Provider type | Validation method | +|---|---| +| OpenAI | Tries `/responses` first, then `/chat/completions`. | +| NVIDIA Endpoints | Tries `/responses` first with a tool-calling probe that matches OpenClaw behavior. Falls back to `/chat/completions` if the endpoint does not return a compatible tool call. | +| Google Gemini | Tries `/responses` first with a tool-calling probe that matches OpenClaw behavior. Falls back to `/chat/completions` if the endpoint does not return a compatible tool call. | +| Other OpenAI-compatible endpoint | Tries `/responses` first with a tool-calling probe that matches OpenClaw behavior. Falls back to `/chat/completions` if the endpoint does not return a compatible tool call. | +| Anthropic-compatible | Tries `/v1/messages`. | +| NVIDIA Endpoints (manual model entry) | Validates the model name against the catalog API. | +| Compatible endpoints | Sends a real inference request because many proxies do not expose a `/models` endpoint. For OpenAI-compatible endpoints, the probe includes tool calling before NemoClaw favors `/responses`. | + +## Prerequisites + +- A running NemoClaw sandbox. +- The OpenShell CLI on your `PATH`. +- NemoClaw installed. +- A local model server running, or Ollama installed. The NemoClaw onboard wizard can also start Ollama for you. + +Change the active inference model while the sandbox is running. +No restart is required. + +## Step 1: Switch to a Different Model + +Switching happens through the OpenShell inference route. +Use the provider and model that match the upstream you want to use. + +### NVIDIA Endpoints + +```console +$ openshell inference set --provider nvidia-prod --model nvidia/nemotron-3-super-120b-a12b +``` + +### OpenAI + +```console +$ openshell inference set --provider openai-api --model gpt-5.4 +``` + +### Anthropic + +```console +$ openshell inference set --provider anthropic-prod --model claude-sonnet-4-6 +``` + +### Google Gemini + +```console +$ openshell inference set --provider gemini-api --model gemini-2.5-flash +``` + +### Compatible Endpoints + +If you onboarded a custom compatible endpoint, switch models with the provider created for that endpoint: + +```console +$ openshell inference set --provider compatible-endpoint --model +``` + +```console +$ openshell inference set --provider compatible-anthropic-endpoint --model +``` + +If the provider itself needs to change, rerun `nemoclaw onboard`. + +## Step 2: Verify the Active Model + +Run the status command to confirm the change: + +```console +$ nemoclaw status +``` + +Add the `--json` flag for machine-readable output: + +```console +$ nemoclaw status --json +``` + +The output includes the active provider, model, and endpoint. + +## Step 3: Notes + +- The host keeps provider credentials. +- The sandbox continues to use `inference.local`. +- Runtime switching changes the OpenShell route. It does not rewrite your stored credentials. + +--- + +NemoClaw can route inference to a model server running on your machine instead of a cloud API. +This page covers Ollama, compatible-endpoint paths for other servers, and two experimental options for vLLM and NVIDIA NIM. + +All approaches use the same `inference.local` routing model. +The agent inside the sandbox never connects to your model server directly. +OpenShell intercepts inference traffic and forwards it to the local endpoint you configure. + +## Step 4: Ollama + +Ollama is the default local inference option. +The onboard wizard detects Ollama automatically when it is installed or running on the host. + +If Ollama is not running, NemoClaw starts it for you. +On macOS, the wizard also offers to install Ollama through Homebrew if it is not present. + +Run the onboard wizard. + +```console +$ nemoclaw onboard +``` + +Select **Local Ollama** from the provider list. +NemoClaw lists installed models or offers starter models if none are installed. +It pulls the selected model, loads it into memory, and validates it before continuing. + +### Linux with Docker + +On Linux hosts that run NemoClaw with Docker, the sandbox reaches Ollama through +`http://host.openshell.internal:11434`, not the host shell's `localhost` socket. +If Ollama is already running, make sure it listens on `0.0.0.0:11434` instead of +`127.0.0.1:11434`. + +```console +$ OLLAMA_HOST=0.0.0.0:11434 ollama serve +``` + +If Ollama only binds loopback, NemoClaw can detect it on the host, but the +sandbox-side validation step fails because containers cannot reach it. + +### Non-Interactive Setup + +```console +$ NEMOCLAW_PROVIDER=ollama \ + NEMOCLAW_MODEL=qwen2.5:14b \ + nemoclaw onboard --non-interactive +``` + +If `NEMOCLAW_MODEL` is not set, NemoClaw selects a default model based on available memory. + +| Variable | Purpose | +|---|---| +| `NEMOCLAW_PROVIDER` | Set to `ollama`. | +| `NEMOCLAW_MODEL` | Ollama model tag to use. Optional. | + +## Step 5: OpenAI-Compatible Server + +This option works with any server that implements `/v1/chat/completions`, including vLLM, TensorRT-LLM, llama.cpp, LocalAI, and others. +If the server also supports `/v1/responses`, NemoClaw only favors that path when onboarding can verify tool-calling behavior that matches what OpenClaw actually sends. +Otherwise NemoClaw falls back to `/v1/chat/completions`. + +Start your model server. +The examples below use vLLM, but any OpenAI-compatible server works. + +```console +$ vllm serve meta-llama/Llama-3.1-8B-Instruct --port 8000 +``` + +Run the onboard wizard. + +```console +$ nemoclaw onboard +``` + +When the wizard asks you to choose an inference provider, select **Other OpenAI-compatible endpoint**. +Enter the base URL of your local server, for example `http://localhost:8000/v1`. + +The wizard prompts for an API key. +If your server does not require authentication, enter any non-empty string (for example, `dummy`). + +NemoClaw validates the endpoint by sending a test inference request before continuing. +For OpenAI-compatible endpoints, the validation prefers `/responses` only when the probe produces a compatible function or tool call. +Endpoints that return `200 OK` on `/responses` but do not format tool calls the way OpenClaw expects are configured to use `/chat/completions` instead. + +### Non-Interactive Setup + +Set the following environment variables for scripted or CI/CD deployments. + +```console +$ NEMOCLAW_PROVIDER=custom \ + NEMOCLAW_ENDPOINT_URL=http://localhost:8000/v1 \ + NEMOCLAW_MODEL=meta-llama/Llama-3.1-8B-Instruct \ + COMPATIBLE_API_KEY=dummy \ + nemoclaw onboard --non-interactive +``` + +| Variable | Purpose | +|---|---| +| `NEMOCLAW_PROVIDER` | Set to `custom` for an OpenAI-compatible endpoint. | +| `NEMOCLAW_ENDPOINT_URL` | Base URL of the local server. | +| `NEMOCLAW_MODEL` | Model ID as reported by the server. | +| `COMPATIBLE_API_KEY` | API key for the endpoint. Use any non-empty value if authentication is not required. | + +## Step 6: Anthropic-Compatible Server + +If your local server implements the Anthropic Messages API (`/v1/messages`), choose **Other Anthropic-compatible endpoint** during onboarding instead. + +```console +$ nemoclaw onboard +``` + +For non-interactive setup, use `NEMOCLAW_PROVIDER=anthropicCompatible` and set `COMPATIBLE_ANTHROPIC_API_KEY`. + +```console +$ NEMOCLAW_PROVIDER=anthropicCompatible \ + NEMOCLAW_ENDPOINT_URL=http://localhost:8080 \ + NEMOCLAW_MODEL=my-model \ + COMPATIBLE_ANTHROPIC_API_KEY=dummy \ + nemoclaw onboard --non-interactive +``` + +## Step 7: vLLM Auto-Detection (Experimental) + +When vLLM is already running on `localhost:8000`, NemoClaw can detect it automatically and query the `/v1/models` endpoint to determine the loaded model. + +Set the experimental flag and run onboard. + +```console +$ NEMOCLAW_EXPERIMENTAL=1 nemoclaw onboard +``` + +Select **Local vLLM [experimental]** from the provider list. +NemoClaw detects the running model and validates the endpoint. + +> **Note:** NemoClaw forces the `chat/completions` API path for vLLM. +> The vLLM `/v1/responses` endpoint does not run the `--tool-call-parser`, so tool calls arrive as raw text. + +### Non-Interactive Setup + +```console +$ NEMOCLAW_EXPERIMENTAL=1 \ + NEMOCLAW_PROVIDER=vllm \ + nemoclaw onboard --non-interactive +``` + +NemoClaw auto-detects the model from the running vLLM instance. +To override the model, set `NEMOCLAW_MODEL`. + +## Step 8: NVIDIA NIM (Experimental) + +NemoClaw can pull, start, and manage a NIM container on hosts with a NIM-capable NVIDIA GPU. + +Set the experimental flag and run onboard. + +```console +$ NEMOCLAW_EXPERIMENTAL=1 nemoclaw onboard +``` + +Select **Local NVIDIA NIM [experimental]** from the provider list. +NemoClaw filters available models by GPU VRAM, pulls the NIM container image, starts it, and waits for it to become healthy before continuing. + +> **Note:** NIM uses vLLM internally. +> The same `chat/completions` API path restriction applies. + +### Non-Interactive Setup + +```console +$ NEMOCLAW_EXPERIMENTAL=1 \ + NEMOCLAW_PROVIDER=nim \ + nemoclaw onboard --non-interactive +``` + +To select a specific model, set `NEMOCLAW_MODEL`. + +## Step 9: Verify the Configuration + +After onboarding completes, confirm the active provider and model. + +```console +$ nemoclaw status +``` + +The output shows the provider label (for example, "Local vLLM" or "Other OpenAI-compatible endpoint") and the active model. + +## Step 10: Switch Models at Runtime + +You can change the model without re-running onboard. +Refer to Switch Inference Models (see the `nemoclaw-user-configure-inference` skill) for the full procedure. + +For compatible endpoints, the command is: + +```console +$ openshell inference set --provider compatible-endpoint --model +``` + +If the provider itself needs to change (for example, switching from vLLM to a cloud API), rerun `nemoclaw onboard`. + +## Related Skills + +- `nemoclaw-user-get-started` — Quickstart for first-time installation diff --git a/.agents/skills/nemoclaw-user-configure-inference/references/inference-options.md b/.agents/skills/nemoclaw-user-configure-inference/references/inference-options.md new file mode 100644 index 000000000..085ada570 --- /dev/null +++ b/.agents/skills/nemoclaw-user-configure-inference/references/inference-options.md @@ -0,0 +1,61 @@ +# Inference Options + +NemoClaw supports multiple inference providers. +During onboarding, the `nemoclaw onboard` wizard presents a numbered list of providers to choose from. +Your selection determines where the agent's inference traffic is routed. + +## How Inference Routing Works + +The agent inside the sandbox talks to `inference.local`. +It never connects to a provider directly. +OpenShell intercepts inference traffic on the host and forwards it to the provider you selected. + +Provider credentials stay on the host. +The sandbox does not receive your API key. + +## Provider Options + +The onboard wizard presents the following provider options by default. +The first six are always available. +Ollama appears when it is installed or running on the host. + +| Option | Description | Curated models | +|--------|-------------|----------------| +| NVIDIA Endpoints | Routes to models hosted on [build.nvidia.com](https://build.nvidia.com). You can also enter any model ID from the catalog. Set `NVIDIA_API_KEY`. | Nemotron 3 Super 120B, Kimi K2.5, GLM-5, MiniMax M2.5, GPT-OSS 120B | +| OpenAI | Routes to the OpenAI API. Set `OPENAI_API_KEY`. | `gpt-5.4`, `gpt-5.4-mini`, `gpt-5.4-nano`, `gpt-5.4-pro-2026-03-05` | +| Other OpenAI-compatible endpoint | Routes to any server that implements `/v1/chat/completions`. If the endpoint also supports `/responses` with OpenClaw-style tool calling, NemoClaw can use that path; otherwise it falls back to `/chat/completions`. The wizard prompts for a base URL and model name. Works with OpenRouter, LocalAI, llama.cpp, or any compatible proxy. Set `COMPATIBLE_API_KEY`. | You provide the model name. | +| Anthropic | Routes to the Anthropic Messages API. Set `ANTHROPIC_API_KEY`. | `claude-sonnet-4-6`, `claude-haiku-4-5`, `claude-opus-4-6` | +| Other Anthropic-compatible endpoint | Routes to any server that implements the Anthropic Messages API (`/v1/messages`). The wizard prompts for a base URL and model name. Set `COMPATIBLE_ANTHROPIC_API_KEY`. | You provide the model name. | +| Google Gemini | Routes to Google's OpenAI-compatible endpoint. NemoClaw prefers `/responses` only when the endpoint proves it can handle tool calling in a way OpenClaw uses; otherwise it falls back to `/chat/completions`. Set `GEMINI_API_KEY`. | `gemini-3.1-pro-preview`, `gemini-3.1-flash-lite-preview`, `gemini-3-flash-preview`, `gemini-2.5-pro`, `gemini-2.5-flash`, `gemini-2.5-flash-lite` | +| Local Ollama | Routes to a local Ollama instance on `localhost:11434`. NemoClaw detects installed models, offers starter models if none are present, pulls and warms the selected model, and validates it. | Selected during onboarding. For more information, refer to Use a Local Inference Server (see the `nemoclaw-user-configure-inference` skill). | + +## Experimental Options + +The following local inference options require `NEMOCLAW_EXPERIMENTAL=1` and, when prerequisites are met, appear in the onboarding selection list. + +| Option | Condition | Notes | +|--------|-----------|-------| +| Local NVIDIA NIM | NIM-capable GPU detected | Pulls and manages a NIM container. | +| Local vLLM | vLLM running on `localhost:8000` | Auto-detects the loaded model. | + +For setup instructions, refer to Use a Local Inference Server (see the `nemoclaw-user-configure-inference` skill). + +## Validation + +NemoClaw validates the selected provider and model before creating the sandbox. +If validation fails, the wizard returns to provider selection. + +| Provider type | Validation method | +|---|---| +| OpenAI | Tries `/responses` first, then `/chat/completions`. | +| NVIDIA Endpoints | Tries `/responses` first with a tool-calling probe that matches OpenClaw behavior. Falls back to `/chat/completions` if the endpoint does not return a compatible tool call. | +| Google Gemini | Tries `/responses` first with a tool-calling probe that matches OpenClaw behavior. Falls back to `/chat/completions` if the endpoint does not return a compatible tool call. | +| Other OpenAI-compatible endpoint | Tries `/responses` first with a tool-calling probe that matches OpenClaw behavior. Falls back to `/chat/completions` if the endpoint does not return a compatible tool call. | +| Anthropic-compatible | Tries `/v1/messages`. | +| NVIDIA Endpoints (manual model entry) | Validates the model name against the catalog API. | +| Compatible endpoints | Sends a real inference request because many proxies do not expose a `/models` endpoint. For OpenAI-compatible endpoints, the probe includes tool calling before NemoClaw favors `/responses`. | + +## Next Steps + +- Use a Local Inference Server (see the `nemoclaw-user-configure-inference` skill) for Ollama, vLLM, NIM, and compatible-endpoint setup details. +- Switch Inference Models (see the `nemoclaw-user-configure-inference` skill) for changing the model at runtime without re-onboarding. diff --git a/.agents/skills/nemoclaw-security-best/SKILL.md b/.agents/skills/nemoclaw-user-configure-security/SKILL.md similarity index 88% rename from .agents/skills/nemoclaw-security-best/SKILL.md rename to .agents/skills/nemoclaw-user-configure-security/SKILL.md index 0dc0b1f5a..c3afd0239 100644 --- a/.agents/skills/nemoclaw-security-best/SKILL.md +++ b/.agents/skills/nemoclaw-user-configure-security/SKILL.md @@ -1,9 +1,9 @@ --- -name: "nemoclaw-security-best" -description: "Presents a risk framework for every configurable security control in NemoClaw. Use when evaluating security posture, reviewing sandbox security defaults, or assessing control trade-offs." +name: "nemoclaw-user-configure-security" +description: "Presents a risk framework for every configurable security control in NemoClaw. Use when evaluating security posture, reviewing sandbox security defaults, or assessing control trade-offs. Explains where NemoClaw stores provider credentials, the file permissions it applies, and the operational security trade-offs of plaintext local storage. Use when reviewing credential handling or advising users how to secure stored API keys." --- -# NemoClaw Security Best +# NemoClaw User Configure Security Presents a risk framework for every configurable security control in NemoClaw. Use when evaluating security posture, reviewing sandbox security defaults, or assessing control trade-offs. @@ -13,7 +13,7 @@ NemoClaw ships with deny-by-default security controls across four layers: networ You can tune every control, but each change shifts the risk profile. This page documents every configurable knob, its default, what it protects, the concrete risk of relaxing it, and a recommendation for common use cases. -For background on how the layers fit together, refer to How It Works (see the `nemoclaw-overview` skill). +For background on how the layers fit together, refer to How It Works (see the `nemoclaw-user-overview` skill). diff --git a/.agents/skills/nemoclaw-user-configure-security/references/credential-storage.md b/.agents/skills/nemoclaw-user-configure-security/references/credential-storage.md new file mode 100644 index 000000000..8fb1f6272 --- /dev/null +++ b/.agents/skills/nemoclaw-user-configure-security/references/credential-storage.md @@ -0,0 +1,111 @@ +# Credential Storage + +NemoClaw stores operator-provided host-side credentials under `~/.nemoclaw/`. +These credentials are used during onboarding and host-side lifecycle operations. +They are not encrypted at rest by NemoClaw. +Instead, NemoClaw relies on local filesystem ownership and Unix permissions to limit access. + +## Location and Permissions + +By default, NemoClaw stores credentials in: + +```text +~/.nemoclaw/credentials.json +``` + +When NemoClaw creates this state directory, it uses owner-only permissions: + +- `~/.nemoclaw/` is created with mode `0700` +- `~/.nemoclaw/credentials.json` is written with mode `0600` + +That means only the local account that owns the files should be able to read or modify them. + +NemoClaw also refuses to use obviously unsafe `HOME` paths such as `/tmp`, `/var/tmp`, `/dev/shm`, or `/` for credential storage. +If `HOME` points to one of those locations, onboarding exits with an error instead of writing secrets there. + +## Plaintext Storage Warning + +The credential file is plaintext JSON. +NemoClaw does **not** currently encrypt the file or integrate with the host operating system keychain. + +A typical file looks like this: + +```json +{ + "NVIDIA_API_KEY": "nvapi-...", + "GITHUB_TOKEN": "ghp_...", + "OPENAI_API_KEY": "sk-..." +} +``` + +Treat this file like any other local secret material. +Anyone who can read it can reuse those credentials with the upstream provider. + +## Precedence and Scope + +When NemoClaw looks up a credential, it checks environment variables first. +If the corresponding environment variable is set, NemoClaw uses that value instead of the stored file. + +This behavior is useful for: + +- CI or automation where you do not want to persist secrets to disk +- temporary overrides during testing +- short-lived or rotated credentials + +For interactive local use, `nemoclaw onboard` can save credentials into `~/.nemoclaw/credentials.json` so future runs do not prompt again. + +## Security Recommendations + +Use the following practices to reduce the risk of credential exposure. + +1. Keep your home directory private and owned by your user account. +2. Exclude `~/.nemoclaw/` from cloud-sync folders, shared folders, and broad backup exports unless those systems are already approved for secret storage. +3. Prefer short-lived or low-scope provider credentials where the upstream service supports them. +4. Rotate keys after suspected exposure, machine transfer, or account changes. +5. Prefer environment variables for ephemeral automation instead of persisting long-lived secrets locally. +6. Do not copy `credentials.json` into container images, Git repositories, bug reports, or support bundles. + +## Inspect and Repair Permissions + +To inspect the current permissions: + +```console +$ ls -ld ~/.nemoclaw ~/.nemoclaw/credentials.json +``` + +Expected output should show a private directory and file, for example: + +```text +drwx------ ... ~/.nemoclaw +-rw------- ... ~/.nemoclaw/credentials.json +``` + +If the permissions are broader than expected, tighten them: + +```console +$ chmod 700 ~/.nemoclaw +$ chmod 600 ~/.nemoclaw/credentials.json +``` + +## Rotate or Remove Stored Credentials + +The simplest way to replace a stored provider key is to rerun onboarding and provide the new value when prompted: + +```console +$ nemoclaw onboard +``` + +To remove the stored file entirely: + +```console +$ rm -f ~/.nemoclaw/credentials.json +``` + +On the next run, NemoClaw prompts again unless the credential is supplied through the environment. + +## Related Files + +Other NemoClaw host-side state also lives under `~/.nemoclaw/`, such as sandbox registry metadata. +These files are operational state, not provider secrets, but they should still remain in a user-owned home directory. + +For the broader sandbox security model and operational trade-offs, see Security Best Practices (see the `nemoclaw-user-configure-security` skill) and Architecture (see the `nemoclaw-user-reference` skill). diff --git a/.agents/skills/nemoclaw-user-deploy-remote/SKILL.md b/.agents/skills/nemoclaw-user-deploy-remote/SKILL.md new file mode 100644 index 000000000..37e4d8c80 --- /dev/null +++ b/.agents/skills/nemoclaw-user-deploy-remote/SKILL.md @@ -0,0 +1,184 @@ +--- +name: "nemoclaw-user-deploy-remote" +description: "Explains how to run NemoClaw on a remote GPU instance, including the deprecated Brev compatibility path and the preferred installer plus onboard flow. Describes security hardening measures applied to the NemoClaw sandbox container image. Use when reviewing container security, Docker capabilities, process limits, or sandbox hardening controls. Explains how Telegram reaches the sandboxed OpenClaw agent through OpenShell-managed processes and onboarding-time channel configuration. Use when setting up Telegram, a chat interface, or messaging integration without relying on nemoclaw start for bridges." +--- + +# NemoClaw User Deploy Remote + +Explains how to run NemoClaw on a remote GPU instance, including the deprecated Brev compatibility path and the preferred installer plus onboard flow. + +## Prerequisites + +- The [Brev CLI](https://brev.nvidia.com) installed and authenticated. +- A provider credential for the inference backend you want to use during onboarding. +- NemoClaw installed locally if you plan to use the deprecated `nemoclaw deploy` wrapper. Otherwise, install NemoClaw directly on the remote host after provisioning it. +- A machine where you can run `nemoclaw onboard` (local or remote host that runs the gateway and sandbox). +- A Telegram bot token from [BotFather](https://t.me/BotFather). + +Run NemoClaw on a remote GPU instance through [Brev](https://brev.nvidia.com). +The preferred path is to provision the VM, run the standard NemoClaw installer on that host, and then run `nemoclaw onboard`. + +## Step 1: Quick Start + +If your Brev instance is already up and has already been onboarded with a sandbox, start with the standard sandbox chat flow: + +```console +$ nemoclaw my-assistant connect +$ openclaw tui +``` + +This gets you into the sandbox shell first and opens the OpenClaw chat UI right away. +If the VM is fresh, run the standard installer on that host and then run `nemoclaw onboard` before trying `nemoclaw my-assistant connect`. + +If you are connecting from your local machine and still need to provision the remote VM, you can still use `nemoclaw deploy ` as the legacy compatibility path described below. + +## Step 2: Deploy the Instance + +> **Warning:** The `nemoclaw deploy` command is deprecated. +> Prefer provisioning the remote host separately, then running the standard NemoClaw installer and `nemoclaw onboard` on that host. + +Create a Brev instance and run the legacy compatibility flow: + +```console +$ nemoclaw deploy +``` + +Replace `` with a name for your remote instance, for example `my-gpu-box`. + +The legacy compatibility flow performs the following steps on the VM: + +1. Installs Docker and the NVIDIA Container Toolkit if a GPU is present. +2. Installs the OpenShell CLI. +3. Runs `nemoclaw onboard` (the setup wizard) to create the gateway, register providers, and launch the sandbox. +4. Starts optional host auxiliary services (for example the cloudflared tunnel) when `cloudflared` is available. Channel messaging is configured during onboarding and runs through OpenShell-managed processes, not through `nemoclaw start`. + +By default, the compatibility wrapper asks Brev to provision on `gcp`. Override this with `NEMOCLAW_BREV_PROVIDER` if you need a different Brev cloud provider. + +## Step 3: Connect to the Remote Sandbox + +After deployment finishes, the deploy command opens an interactive shell inside the remote sandbox. +To reconnect after closing the session, run the command again: + +```console +$ nemoclaw deploy +``` + +## Step 4: Monitor the Remote Sandbox + +SSH to the instance and run the OpenShell TUI to monitor activity and approve network requests: + +```console +$ ssh 'cd /home/ubuntu/nemoclaw && set -a && . .env && set +a && openshell term' +``` + +## Step 5: Verify Inference + +Run a test agent prompt inside the remote sandbox: + +```console +$ openclaw agent --agent main --local -m "Hello from the remote sandbox" --session-id test +``` + +## Step 6: Remote Dashboard Access + +The NemoClaw dashboard validates the browser origin against an allowlist baked +into the sandbox image at build time. By default the allowlist only contains +`http://127.0.0.1:18789`. When accessing the dashboard from a remote browser +(for example through a Brev public URL or an SSH port-forward), set +`CHAT_UI_URL` to the origin the browser will use **before** running setup: + +```console +$ export CHAT_UI_URL="https://openclaw0-.brevlab.com" +$ nemoclaw deploy +``` + +For SSH port-forwarding, the origin is typically `http://127.0.0.1:18789` (the +default), so no extra configuration is needed. + +> **Warning:** On Brev, set `CHAT_UI_URL` in the launchable environment configuration so it is +> available when the installer builds the sandbox image. If `CHAT_UI_URL` is not +> set on a headless host, the compatibility wrapper prints a warning. +> +> `NEMOCLAW_DISABLE_DEVICE_AUTH` is also evaluated at image build time. +> If you disable device auth for a remote deployment, any device that can reach the dashboard origin can connect without pairing. +> Avoid this on internet-reachable or shared-network deployments. + +## Step 7: GPU Configuration + +The deploy script uses the `NEMOCLAW_GPU` environment variable to select the GPU type. +The default value is `a2-highgpu-1g:nvidia-tesla-a100:1`. +Set this variable before running `nemoclaw deploy` to use a different GPU configuration: + +```console +$ export NEMOCLAW_GPU="a2-highgpu-1g:nvidia-tesla-a100:2" +$ nemoclaw deploy +``` + +--- + +Telegram, Discord, and Slack reach your agent through OpenShell-managed processes and gateway constructs. +NemoClaw configures those channels during `nemoclaw onboard`. Tokens are registered with OpenShell providers, channel configuration is baked into the sandbox image, and runtime delivery stays under OpenShell control. + +`nemoclaw start` does not start Telegram (or other chat bridges). It only starts optional host services such as the cloudflared tunnel when that binary is present. +For details, refer to Commands (see the `nemoclaw-user-reference` skill). + +## Step 8: Create a Telegram Bot + +Open Telegram and send `/newbot` to [@BotFather](https://t.me/BotFather). +Follow the prompts to create a bot and copy the bot token. + +## Step 9: Provide the Bot Token and Optional Allowlist + +Onboarding reads Telegram credentials from either host environment variables or the NemoClaw credential store (`getCredential` / `saveCredential` in the onboard flow). You do not have to export variables if you enter the token when the wizard asks. + +### Option A: Environment variables (CI, scripts, or before you start the wizard) + +```console +$ export TELEGRAM_BOT_TOKEN= +``` + +Optional comma-separated allowlist (maps to the wizard field “Telegram User ID (for DM access)”): + +```console +$ export TELEGRAM_ALLOWED_IDS="123456789,987654321" +``` + +### Option B: Interactive `nemoclaw onboard` + +When the wizard reaches **Messaging channels**, it lists Telegram, Discord, and Slack. +Press **1** to toggle Telegram on or off, then **Enter** when done. +If the token is not already in the environment or credential store, the wizard prompts for it and saves it to the store. +If `TELEGRAM_ALLOWED_IDS` is not set, the wizard can prompt for allowed sender IDs for Telegram DMs (you can leave this blank and rely on OpenClaw pairing instead). + +## Step 10: Run `nemoclaw onboard` + +Complete the rest of the wizard so the blueprint can create OpenShell providers (for example `-telegram-bridge`), bake channel configuration into the image (`NEMOCLAW_MESSAGING_CHANNELS_B64`), and start the sandbox. + +Channel entries in `/sandbox/.openclaw/openclaw.json` are fixed at image build time. Landlock keeps that path read-only at runtime, so you cannot patch messaging config inside a running sandbox. + +If you add or change `TELEGRAM_BOT_TOKEN` (or toggle channels) after a sandbox already exists, you typically need to run `nemoclaw onboard` again so the image and provider attachments are rebuilt with the new settings. + +For a full first-time flow, refer to Quickstart (see the `nemoclaw-user-get-started` skill). + +## Step 11: Confirm Delivery + +After the sandbox is running, send a message to your bot in Telegram. +If something fails, use `openshell term` on the host, check gateway logs, and verify network policy allows the Telegram API (see Customize the Network Policy (see the `nemoclaw-user-manage-policy` skill) and the `telegram` preset). + +## Step 12: `nemoclaw start` (cloudflared Only) + +`nemoclaw start` starts cloudflared when it is installed, which can expose the dashboard with a public URL. +It does not affect Telegram connectivity. + +```console +$ nemoclaw start +``` + +## Reference + +- [Sandbox Image Hardening](references/sandbox-hardening.md) + +## Related Skills + +- `nemoclaw-user-monitor-sandbox` — Monitor Sandbox Activity for sandbox monitoring tools +- `nemoclaw-user-reference` — Commands for the full `deploy` command reference diff --git a/.agents/skills/nemoclaw-user-deploy-remote/references/sandbox-hardening.md b/.agents/skills/nemoclaw-user-deploy-remote/references/sandbox-hardening.md new file mode 100644 index 000000000..dc0ad59fa --- /dev/null +++ b/.agents/skills/nemoclaw-user-deploy-remote/references/sandbox-hardening.md @@ -0,0 +1,68 @@ +# Sandbox Image Hardening + +The NemoClaw sandbox image applies several security measures to reduce attack +surface and limit the blast radius of untrusted workloads. + +## Removed Unnecessary Tools + +Build toolchains (`gcc`, `g++`, `make`) and network probes (`netcat`) are +explicitly purged from the runtime image. These tools are not needed at runtime +and would unnecessarily widen the attack surface. + +If you need a compiler during build, use the existing multi-stage build +(the `builder` stage has full Node.js tooling) and copy only artifacts into the +runtime stage. + +## Process Limits + +The container ENTRYPOINT sets `ulimit -u 512` to cap the number of processes +a sandbox user can spawn. This mitigates fork-bomb attacks. The startup script +(`nemoclaw-start.sh`) applies the same limit. + +Adjust the value via the `--ulimit nproc=512:512` flag if launching with +`docker run` directly. + +## Dropping Linux Capabilities + +When running the sandbox container, drop all Linux capabilities and re-add only +what is strictly required: + +```console +$ docker run --rm \ + --cap-drop=ALL \ + --ulimit nproc=512:512 \ + nemoclaw-sandbox +``` + +### Docker Compose Example + +```yaml +services: + nemoclaw-sandbox: + image: nemoclaw-sandbox:latest + cap_drop: + - ALL + cap_add: + - NET_BIND_SERVICE + ulimits: + nproc: + soft: 512 + hard: 512 + security_opt: + - no-new-privileges:true + read_only: true + tmpfs: + - /tmp:size=64m +``` + +> **Note:** The `Dockerfile` itself cannot enforce `--cap-drop`. That is a +> runtime concern controlled by the container orchestrator. Always configure +> capability dropping in your `docker run` flags, Compose file, or Kubernetes +> `securityContext`. + +## References + +- [#807](https://github.com/NVIDIA/NemoClaw/issues/807): gcc in sandbox image +- [#808](https://github.com/NVIDIA/NemoClaw/issues/808): netcat in sandbox image +- [#809](https://github.com/NVIDIA/NemoClaw/issues/809): No process limit +- [#797](https://github.com/NVIDIA/NemoClaw/issues/797): Drop Linux capabilities diff --git a/.agents/skills/nemoclaw-user-get-started/SKILL.md b/.agents/skills/nemoclaw-user-get-started/SKILL.md new file mode 100644 index 000000000..3874405c9 --- /dev/null +++ b/.agents/skills/nemoclaw-user-get-started/SKILL.md @@ -0,0 +1,95 @@ +--- +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." +--- + +# NemoClaw User Get Started + +Installs NemoClaw, launches a sandbox, and runs the first agent prompt. Use when onboarding, installing, or launching a NemoClaw sandbox for the first time. + +## Prerequisites + +Before getting started, check the prerequisites to ensure you have the necessary software and hardware to run NemoClaw. + +> **Alpha software:** NemoClaw is in alpha, available as an early preview since March 16, 2026. +> APIs, configuration schemas, and runtime behavior are subject to breaking changes between releases. +> Do not use this software in production environments. +> File issues and feedback through the GitHub repository as the project continues to stabilize. + +Follow these steps to get started with NemoClaw and your first sandboxed OpenClaw agent. + +## Step 1: Install NemoClaw and Onboard OpenClaw Agent + +Download and run the installer script. +The script installs Node.js if it is not already present, then runs the guided onboard wizard to create a sandbox, configure inference, and apply security policies. + +> **Note:** NemoClaw creates a fresh OpenClaw instance inside the sandbox during the onboarding process. + +```bash +curl -fsSL https://www.nvidia.com/nemoclaw.sh | bash +``` + +If you use nvm or fnm to manage Node.js, the installer may not update your current shell's PATH. +If `nemoclaw` is not found after install, run `source ~/.bashrc` (or `source ~/.zshrc` for zsh) or open a new terminal. + +> **Note:** The onboard flow builds the sandbox image with `NEMOCLAW_DISABLE_DEVICE_AUTH=1` so the dashboard is immediately usable during setup. +> This is a build-time setting baked into the sandbox image, not a runtime knob. +> If you export `NEMOCLAW_DISABLE_DEVICE_AUTH` after onboarding finishes, it has no effect on an existing sandbox. + +When the install completes, a summary confirms the running environment: + +```text +────────────────────────────────────────────────── +Sandbox my-assistant (Landlock + seccomp + netns) +Model nvidia/nemotron-3-super-120b-a12b (NVIDIA Endpoints) +────────────────────────────────────────────────── +Run: nemoclaw my-assistant connect +Status: nemoclaw my-assistant status +Logs: nemoclaw my-assistant logs --follow +────────────────────────────────────────────────── + +[INFO] === Installation complete === +``` + +## Step 2: Chat with the Agent + +Connect to the sandbox, then chat with the agent through the TUI or the CLI. + +```bash +nemoclaw my-assistant connect +``` + +In the sandbox shell, open the OpenClaw terminal UI and start a chat: + +```bash +openclaw tui +``` + +Alternatively, send a single message and print the response: + +```bash +openclaw agent --agent main --local -m "hello" --session-id test +``` + +## Step 3: Uninstall + +To remove NemoClaw and all resources created during setup, run the uninstall script: + +```bash +curl -fsSL https://raw.githubusercontent.com/NVIDIA/NemoClaw/refs/heads/main/uninstall.sh | bash +``` + +| Flag | Effect | +|--------------------|-----------------------------------------------------| +| `--yes` | Skip the confirmation prompt. | +| `--keep-openshell` | Leave the `openshell` binary installed. | +| `--delete-models` | Also remove NemoClaw-pulled Ollama models. | + +For troubleshooting installation or onboarding issues, see the Troubleshooting guide (see the `nemoclaw-user-reference` skill). + +## Related Skills + +- `nemoclaw-user-configure-inference` — Switch inference providers to use a different model or endpoint +- `nemoclaw-user-manage-policy` — Approve or deny network requests when the agent tries to reach external hosts +- `nemoclaw-user-deploy-remote` — Deploy to a remote GPU instance for always-on operation +- `nemoclaw-user-monitor-sandbox` — Monitor sandbox activity through the OpenShell TUI diff --git a/.agents/skills/nemoclaw-user-manage-policy/SKILL.md b/.agents/skills/nemoclaw-user-manage-policy/SKILL.md new file mode 100644 index 000000000..335c07ddb --- /dev/null +++ b/.agents/skills/nemoclaw-user-manage-policy/SKILL.md @@ -0,0 +1,166 @@ +--- +name: "nemoclaw-user-manage-policy" +description: "Reviews and approves blocked agent network requests in the TUI. Use when approving or denying sandbox egress requests, managing blocked network calls, or using the approval TUI. Adds, removes, or modifies allowed endpoints in the sandbox policy. Use when customizing network policy, changing egress rules, or configuring sandbox endpoint access." +--- + +# NemoClaw User Manage Policy + +Reviews and approves blocked agent network requests in the TUI. Use when approving or denying sandbox egress requests, managing blocked network calls, or using the approval TUI. + +## Prerequisites + +- A running NemoClaw sandbox. +- The OpenShell CLI on your `PATH`. +- A running NemoClaw sandbox for dynamic changes, or the NemoClaw source repository for static changes. + +Review and act on network requests that the agent makes to endpoints not listed in the sandbox policy. +OpenShell intercepts these requests and presents them in the TUI for operator approval. + +## Step 1: Open the TUI + +Start the OpenShell terminal UI to monitor sandbox activity: + +```console +$ openshell term +``` + +For a remote sandbox, pass the instance name: + +```console +$ ssh my-gpu-box 'cd /home/ubuntu/nemoclaw && . .env && openshell term' +``` + +The TUI displays the sandbox state, active inference provider, and a live feed of network activity. + +## Step 2: Trigger a Blocked Request + +When the agent attempts to reach an endpoint that is not in the baseline policy, OpenShell blocks the connection and displays the request in the TUI. +The blocked request includes the following details: + +- **Host and port** of the destination. +- **Binary** that initiated the request. +- **HTTP method** and path, if available. + +## Step 3: Approve or Deny the Request + +The TUI presents an approval prompt for each blocked request. + +- **Approve** the request to add the endpoint to the running policy for the current session. +- **Deny** the request to keep the endpoint blocked. + +Approved endpoints remain in the running policy until the sandbox stops. +They are not persisted to the baseline policy file. + +## Step 4: Run the Walkthrough + +To observe the approval flow in a guided session, run the walkthrough script: + +```console +$ ./scripts/walkthrough.sh +``` + +This script opens a split tmux session with the TUI on the left and the agent on the right. +The walkthrough requires tmux and the `NVIDIA_API_KEY` environment variable. + +--- + +Add, remove, or modify the endpoints that the sandbox is allowed to reach. + +The sandbox policy is defined in a declarative YAML file in the NemoClaw repository and enforced at runtime by [NVIDIA OpenShell](https://github.com/NVIDIA/OpenShell). +NemoClaw supports both static policy changes that persist across restarts and dynamic updates applied to a running sandbox through the OpenShell CLI. + +## Step 5: Static Changes + +Static changes modify the baseline policy file and take effect after the next sandbox creation. + +### Edit the Policy File + +Open `nemoclaw-blueprint/policies/openclaw-sandbox.yaml` and add or modify endpoint entries. + +Each entry in the `network` section defines an endpoint group with the following fields: + +`endpoints` +: Host and port pairs that the sandbox can reach. + +`binaries` +: Executables allowed to use this endpoint. + +`rules` +: HTTP methods and paths that are permitted. + +### Re-Run Onboard + +Apply the updated policy by re-running the onboard wizard: + +```console +$ nemoclaw onboard +``` + +The wizard picks up the modified policy file and applies it to the sandbox. + +### Verify the Policy + +Check that the sandbox is running with the updated policy: + +```console +$ nemoclaw status +``` + +## Step 6: Dynamic Changes + +Dynamic changes apply a policy update to a running sandbox without restarting it. + +### Create a Policy File + +Create a YAML file with the endpoints to add. +Follow the same format as the baseline policy in `nemoclaw-blueprint/policies/openclaw-sandbox.yaml`. + +### Apply the Policy + +Use the OpenShell CLI to apply the policy update: + +```console +$ openshell policy set +``` + +The change takes effect immediately. + +### Scope of Dynamic Changes + +Dynamic changes apply only to the current session. +When the sandbox stops, the running policy resets to the baseline defined in the policy file. +To make changes permanent, update the static policy file and re-run setup. + +## Step 7: Policy Presets + +NemoClaw ships preset policy files for common integrations in `nemoclaw-blueprint/policies/presets/`. +Apply a preset as-is or use it as a starting template for a custom policy. + +Available presets: + +| Preset | Endpoints | +|--------|-----------| +| `discord` | Discord webhook API | +| `docker` | Docker Hub, NVIDIA container registry | +| `huggingface` | Hugging Face model registry | +| `jira` | Atlassian Jira API | +| `npm` | npm and Yarn registries | +| `outlook` | Microsoft 365 and Outlook | +| `pypi` | Python Package Index | +| `slack` | Slack API and webhooks | +| `telegram` | Telegram Bot API | + +To apply a preset to a running sandbox, pass it as a policy file: + +```console +$ openshell policy set nemoclaw-blueprint/policies/presets/pypi.yaml +``` + +To include a preset in the baseline, merge its entries into `openclaw-sandbox.yaml` and re-run `nemoclaw onboard`. + +## Related Skills + +- `nemoclaw-user-reference` — Network Policies for the full baseline policy reference +- `nemoclaw-user-monitor-sandbox` — Monitor Sandbox Activity for general sandbox monitoring +- OpenShell [Policy Schema](https://docs.nvidia.com/openshell/latest/reference/policy-schema.html) for the full YAML policy schema reference. +- OpenShell [Sandbox Policies](https://docs.nvidia.com/openshell/latest/sandboxes/policies.html) for applying, iterating, and debugging policies at the OpenShell layer. diff --git a/.agents/skills/nemoclaw-user-monitor-sandbox/SKILL.md b/.agents/skills/nemoclaw-user-monitor-sandbox/SKILL.md new file mode 100644 index 000000000..449b80835 --- /dev/null +++ b/.agents/skills/nemoclaw-user-monitor-sandbox/SKILL.md @@ -0,0 +1,85 @@ +--- +name: "nemoclaw-user-monitor-sandbox" +description: "Inspects sandbox health, traces agent behavior, and diagnoses problems. Use when monitoring a running sandbox, debugging agent issues, or checking sandbox logs." +--- + +# NemoClaw User Monitor Sandbox + +Inspects sandbox health, traces agent behavior, and diagnoses problems. Use when monitoring a running sandbox, debugging agent issues, or checking sandbox logs. + +## Prerequisites + +- A running NemoClaw sandbox. +- The OpenShell CLI on your `PATH`. + +Use the NemoClaw status, logs, and TUI tools together to inspect sandbox health, trace agent behavior, and diagnose problems. + +## Step 1: Check Sandbox Health + +Run the status command to view the sandbox state, blueprint run information, and active inference configuration: + +```console +$ nemoclaw status +``` + +Key fields in the output include the following: + +- Sandbox state, which indicates whether the sandbox is running, stopped, or in an error state. +- Blueprint run ID, which is the identifier for the most recent blueprint execution. +- Inference provider, which shows the active provider, model, and endpoint. + +Run `nemoclaw status` on the host to check sandbox state. +Use `openshell sandbox list` for the underlying sandbox details. + +## Step 2: View Blueprint and Sandbox Logs + +Stream the most recent log output from the blueprint runner and sandbox: + +```console +$ nemoclaw logs +``` + +To follow the log output in real time: + +```console +$ nemoclaw logs --follow +``` + +## Step 3: Monitor Network Activity in the TUI + +Open the OpenShell terminal UI for a live view of sandbox network activity and egress requests: + +```console +$ openshell term +``` + +For a remote sandbox, SSH to the instance and run `openshell term` there. + +The TUI shows the following information: + +- Active network connections from the sandbox. +- Blocked egress requests awaiting operator approval. +- Inference routing status. + +Refer to Approve or Deny Agent Network Requests (see the `nemoclaw-user-manage-policy` skill) for details on handling blocked requests. + +## Step 4: Test Inference + +Run a test inference request to verify that the provider is responding: + +```console +$ nemoclaw my-assistant connect +$ openclaw agent --agent main --local -m "Test inference" --session-id debug +``` + +If the request fails, check the following: + +1. Run `nemoclaw status` to confirm the active provider and endpoint. +2. Run `nemoclaw logs --follow` to view error messages from the blueprint runner. +3. Verify that the inference endpoint is reachable from the host. + +## Related Skills + +- `nemoclaw-user-reference` — Troubleshooting for common issues and resolution steps +- `nemoclaw-user-manage-policy` — Approve or Deny Agent Network Requests for the operator approval flow +- `nemoclaw-user-configure-inference` — Switch Inference Providers to change the active provider diff --git a/.agents/skills/nemoclaw-user-overview/SKILL.md b/.agents/skills/nemoclaw-user-overview/SKILL.md new file mode 100644 index 000000000..33bed6767 --- /dev/null +++ b/.agents/skills/nemoclaw-user-overview/SKILL.md @@ -0,0 +1,201 @@ +--- +name: "nemoclaw-user-overview" +description: "Explains how OpenClaw, OpenShell, and NemoClaw form the ecosystem, NemoClaw’s position in the stack, and when to prefer NemoClaw versus integrating OpenShell and OpenClaw directly. Use when users ask about the relationship between OpenClaw, OpenShell, and NemoClaw, or when to use NemoClaw versus OpenShell. Describes how NemoClaw works internally: CLI, plugin, blueprint runner, OpenShell orchestration, inference routing, and protection layers. Use for sandbox lifecycle and architecture mechanics; not for product definition (Overview) or multi-project placement (Ecosystem). Explains what NemoClaw covers: onboarding, lifecycle management, and management of OpenClaw within OpenShell containers, plus capabilities and why it exists. Use when users ask what NemoClaw is or what the project provides. For ecosystem placement or OpenShell-only paths, use the Ecosystem page; for internal mechanics, use How It Works. Lists changelogs and feature history for NemoClaw releases. Use when checking what changed in a releas..." +--- + +# NemoClaw User Overview + +Explains how OpenClaw, OpenShell, and NemoClaw form the ecosystem, NemoClaw’s position in the stack, and when to prefer NemoClaw versus integrating OpenShell and OpenClaw directly. Use when users ask about the relationship between OpenClaw, OpenShell, and NemoClaw, or when to use NemoClaw versus OpenShell. + +## Context + +NemoClaw provides onboarding, lifecycle management, and management of OpenClaw within OpenShell containers. + +This page describes how the ecosystem is formed across projects, where NemoClaw sits relative to [OpenShell](https://github.com/NVIDIA/OpenShell) and [OpenClaw](https://openclaw.ai), and how to choose between NemoClaw and OpenShell. + +## How the Stack Fits Together + +Three pieces usually appear together in a NemoClaw deployment, each with a distinct scope: + +| Project | Scope | +|---------|--------| +| [OpenClaw](https://openclaw.ai) | The assistant: runtime, tools, memory, and behavior inside the container. It does not define the sandbox or the host gateway. | +| [OpenShell](https://github.com/NVIDIA/OpenShell) | The execution environment: sandbox lifecycle, network and filesystem policy, inference routing, and the operator-facing `openshell` CLI for those primitives. | +| NemoClaw | The NVIDIA reference stack that implements the definition above on the host: `nemoclaw` CLI and plugin, versioned blueprint, channel messaging configured for OpenShell-managed delivery, and state migration helpers so OpenClaw runs inside OpenShell in a documented, repeatable way. | + +NemoClaw sits above OpenShell in the operator workflow. +It drives OpenShell APIs and CLI to create and configure the sandbox that runs OpenClaw. +Models and endpoints sit behind OpenShell’s inference routing. +NemoClaw onboarding wires provider choice into that routing. + +```mermaid +flowchart TB + NC["🦞 NVIDIA NemoClaw
CLI, plugin, blueprint"] + OS["🐚 NVIDIA OpenShell
Gateway, policy, inference routing"] + OC["🦞 OpenClaw
Assistant in sandbox"] + + NC -->|orchestrates| OS + OS -->|isolates and runs| OC + + classDef nv fill:#76b900,stroke:#333,color:#fff + classDef nvLight fill:#e6f2cc,stroke:#76b900,color:#1a1a1a + classDef nvDark fill:#333,stroke:#76b900,color:#fff + + class NC nv + class OS nv + class OC nvDark + + linkStyle 0 stroke:#76b900,stroke-width:2px + linkStyle 1 stroke:#76b900,stroke-width:2px +``` + +## NemoClaw Path versus OpenShell Path + +Both paths assume OpenShell can sandbox a workload. +The difference is who owns the integration work. + +| Path | What it means | +|------|---------------| +| **NemoClaw path** | You adopt the reference stack. NemoClaw’s blueprint encodes a hardened image, default policies, and orchestration so `nemoclaw onboard` can stand up a known-good OpenClaw-on-OpenShell setup with less custom glue. | +| **OpenShell path** | You use OpenShell as the platform and supply your own container, install steps for OpenClaw, policy YAML, provider setup, and any host bridges. OpenShell stays the sandbox and policy engine; nothing requires NemoClaw’s blueprint or CLI. | + +## When to Use Which + +Use the following table to decide when to use NemoClaw versus OpenShell. + +| Situation | Prefer | +|-----------|--------| +| You want OpenClaw with minimal assembly, NVIDIA defaults, and the documented install and onboard flow. | NemoClaw | +| You need maximum flexibility: custom images, a layout that does not match the NemoClaw blueprint, or a workload outside this reference stack. | OpenShell with your own integration | +| You are standardizing on the NVIDIA reference for always-on assistants with policy and inference routing. | NemoClaw | +| You are building internal platform abstractions where the NemoClaw CLI or blueprint is not the right fit. | OpenShell (and your orchestration) | + +*Full details in `references/ecosystem.md`.* + +This page explains how NemoClaw operates, which parts run where, how the blueprint drives OpenShell, and how inference and policy attach to the sandbox. + +## How the Pieces Connect + +The `nemoclaw` CLI is the primary entrypoint for setting up and managing sandboxed OpenClaw agents. +It delegates heavy lifting to a versioned blueprint, a Python artifact that orchestrates sandbox creation, policy application, and inference provider setup through the OpenShell CLI. + +Between your shell and the running sandbox, NemoClaw contributes these integration layers: + +| Layer | Role in the flow | +|-------|------------------| +| Onboarding | `nemoclaw onboard` validates credentials, selects providers, and drives blueprint execution until the sandbox is ready. | +| Blueprint | Supplies the hardened image definition, default policies, capability posture, and orchestration steps the runner applies through OpenShell. | +| State management | Migrates agent state across machines with credential stripping and integrity checks. | +| Channel messaging | OpenShell-managed processes connect Telegram, Discord, Slack, and similar platforms to the agent. NemoClaw enables this through onboarding and blueprint wiring; delivery is not a separate NemoClaw host daemon. | + +For repository layout, file paths, and deeper diagrams, see Architecture (see the `nemoclaw-user-reference` skill). + +```mermaid +flowchart TB + subgraph Host + CMD["nemoclaw onboard"] + PLUGIN[nemoclaw plugin] + BLUEPRINT[blueprint runner] + CLI["openshell CLI sandbox · gateway · inference · policy"] + + CMD --> PLUGIN + PLUGIN --> BLUEPRINT + BLUEPRINT --> CLI + end + + subgraph Sandbox["OpenShell Sandbox"] + AGENT[OpenClaw agent] + INF[NVIDIA inference, routed] + NET[default network policy] + FS[filesystem isolation] + + AGENT --- INF + AGENT --- NET + AGENT --- FS + end + + PLUGIN --> AGENT + + classDef nv fill:#76b900,stroke:#333,color:#fff + classDef nvLight fill:#e6f2cc,stroke:#76b900,color:#1a1a1a + classDef nvDark fill:#333,stroke:#76b900,color:#fff + + class CMD,PLUGIN,BLUEPRINT nvDark + class CLI nv + class AGENT nv + class INF,NET,FS nvLight + + style Host fill:none,stroke:#76b900,stroke-width:2px,color:#1a1a1a + style Sandbox fill:#f5faed,stroke:#76b900,stroke-width:2px,color:#1a1a1a +``` + +## Design Principles + +NemoClaw architecture follows the following principles. + +*Full details in `references/how-it-works.md`.* + +NVIDIA NemoClaw is an open source reference stack that simplifies running [OpenClaw](https://openclaw.ai) always-on assistants. +NemoClaw provides onboarding, lifecycle management, and management of OpenClaw within OpenShell containers. +It incorporates policy-based privacy and security guardrails, giving you control over your agents’ behavior and data handling. +This enables self-evolving claws to run more safely in clouds, on prem, RTX PCs and DGX Spark. + +NemoClaw pairs open source and hosted models (for example [NVIDIA Nemotron](https://build.nvidia.com)) with a hardened sandbox, routed inference, and declarative egress policy so deployment stays safer and more repeatable. +The sandbox runtime comes from [NVIDIA OpenShell](https://github.com/NVIDIA/OpenShell); NemoClaw adds the blueprint, `nemoclaw` CLI, onboarding, and related tooling as the reference way to run OpenClaw there. + +| Capability | Description | +|-------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------| +| Sandbox OpenClaw | Creates an OpenShell sandbox pre-configured for OpenClaw, with filesystem and network policies applied from the first boot. | +| Route inference | Configures OpenShell inference routing so agent traffic goes to the provider and model you chose during onboarding (NVIDIA Endpoints, OpenAI, Anthropic, Gemini, compatible endpoints, local Ollama, and others). The agent uses `inference.local` inside the sandbox; credentials stay on the host. | +| Manage the lifecycle | Handles blueprint versioning, digest verification, and sandbox setup. | + +## Key Features + +NemoClaw provides the following product capabilities. + +| Feature | Description | +|---------|-------------| +| Guided onboarding | Validates credentials, selects providers, and creates a working sandbox in one command. | +| Hardened blueprint | A security-first Dockerfile with capability drops, least-privilege network rules, and declarative policy. | +| State management | Safe migration of agent state across machines with credential stripping and integrity verification. | +| Channel messaging | OpenShell-managed processes connect Telegram, Discord, Slack, and similar platforms to the sandboxed agent. NemoClaw configures channels during onboarding; OpenShell supplies the native constructs, credential flow, and runtime supervision. | +| Routed inference | Provider-routed model calls through the OpenShell gateway, transparent to the agent. Supports NVIDIA Endpoints, OpenAI, Anthropic, Google Gemini, and local Ollama. | +| Layered protection | Network, filesystem, process, and inference controls that can be hot-reloaded or locked at creation. | + +## Challenge + +Autonomous AI agents like OpenClaw can make arbitrary network requests, access the host filesystem, and call any inference endpoint. Without guardrails, this creates security, cost, and compliance risks that grow as agents run unattended. + +## Benefits + +NemoClaw provides the following benefits. + +| Benefit | Description | +|----------------------------|------------------------------------------------------------------------------------------------------------------------| +| Sandboxed execution | Every agent runs inside an OpenShell sandbox with Landlock, seccomp, and network namespace isolation. No access is granted by default. | +| Routed inference | Model traffic is routed through the OpenShell gateway to your selected provider, transparent to the agent. You can switch providers or models. Refer to Inference Options (see the `nemoclaw-user-configure-inference` skill). | +| Declarative network policy | Egress rules are defined in YAML. Unknown hosts are blocked and surfaced to the operator for approval. | +| Single CLI | The `nemoclaw` command orchestrates the full stack: gateway, sandbox, inference provider, and network policy. | +| Blueprint lifecycle | Versioned blueprints handle sandbox creation, digest verification, and reproducible setup. | + +## Use Cases + +You can use NemoClaw for various use cases including the following. + +| Use Case | Description | +|---------------------------|----------------------------------------------------------------------------------------------| +| Always-on assistant | Run an OpenClaw assistant with controlled network access and operator-approved egress. | +| Sandboxed testing | Test agent behavior in a locked-down environment before granting broader permissions. | +| Remote GPU deployment | Deploy a sandboxed agent to a remote GPU instance for persistent operation. | + +*Full details in `references/overview.md`.* + +## Reference + +- [NemoClaw Release Notes](references/release-notes.md) + +## Related Skills + +- `nemoclaw-user-get-started` — Quickstart to install NemoClaw and run your first agent +- `nemoclaw-user-configure-inference` — Switch Inference Providers to configure the inference provider +- `nemoclaw-user-manage-policy` — Approve or Deny Network Requests to manage egress approvals diff --git a/.agents/skills/nemoclaw-user-overview/references/ecosystem.md b/.agents/skills/nemoclaw-user-overview/references/ecosystem.md new file mode 100644 index 000000000..4a8e2c84f --- /dev/null +++ b/.agents/skills/nemoclaw-user-overview/references/ecosystem.md @@ -0,0 +1,70 @@ +# Ecosystem + +NemoClaw provides onboarding, lifecycle management, and management of OpenClaw within OpenShell containers. + +This page describes how the ecosystem is formed across projects, where NemoClaw sits relative to [OpenShell](https://github.com/NVIDIA/OpenShell) and [OpenClaw](https://openclaw.ai), and how to choose between NemoClaw and OpenShell. + +## How the Stack Fits Together + +Three pieces usually appear together in a NemoClaw deployment, each with a distinct scope: + +| Project | Scope | +|---------|--------| +| [OpenClaw](https://openclaw.ai) | The assistant: runtime, tools, memory, and behavior inside the container. It does not define the sandbox or the host gateway. | +| [OpenShell](https://github.com/NVIDIA/OpenShell) | The execution environment: sandbox lifecycle, network and filesystem policy, inference routing, and the operator-facing `openshell` CLI for those primitives. | +| NemoClaw | The NVIDIA reference stack that implements the definition above on the host: `nemoclaw` CLI and plugin, versioned blueprint, channel messaging configured for OpenShell-managed delivery, and state migration helpers so OpenClaw runs inside OpenShell in a documented, repeatable way. | + +NemoClaw sits above OpenShell in the operator workflow. +It drives OpenShell APIs and CLI to create and configure the sandbox that runs OpenClaw. +Models and endpoints sit behind OpenShell’s inference routing. +NemoClaw onboarding wires provider choice into that routing. + +```mermaid +flowchart TB + NC["🦞 NVIDIA NemoClaw
CLI, plugin, blueprint"] + OS["🐚 NVIDIA OpenShell
Gateway, policy, inference routing"] + OC["🦞 OpenClaw
Assistant in sandbox"] + + NC -->|orchestrates| OS + OS -->|isolates and runs| OC + + classDef nv fill:#76b900,stroke:#333,color:#fff + classDef nvLight fill:#e6f2cc,stroke:#76b900,color:#1a1a1a + classDef nvDark fill:#333,stroke:#76b900,color:#fff + + class NC nv + class OS nv + class OC nvDark + + linkStyle 0 stroke:#76b900,stroke-width:2px + linkStyle 1 stroke:#76b900,stroke-width:2px +``` + +## NemoClaw Path versus OpenShell Path + +Both paths assume OpenShell can sandbox a workload. +The difference is who owns the integration work. + +| Path | What it means | +|------|---------------| +| **NemoClaw path** | You adopt the reference stack. NemoClaw’s blueprint encodes a hardened image, default policies, and orchestration so `nemoclaw onboard` can stand up a known-good OpenClaw-on-OpenShell setup with less custom glue. | +| **OpenShell path** | You use OpenShell as the platform and supply your own container, install steps for OpenClaw, policy YAML, provider setup, and any host bridges. OpenShell stays the sandbox and policy engine; nothing requires NemoClaw’s blueprint or CLI. | + +## When to Use Which + +Use the following table to decide when to use NemoClaw versus OpenShell. + +| Situation | Prefer | +|-----------|--------| +| You want OpenClaw with minimal assembly, NVIDIA defaults, and the documented install and onboard flow. | NemoClaw | +| You need maximum flexibility: custom images, a layout that does not match the NemoClaw blueprint, or a workload outside this reference stack. | OpenShell with your own integration | +| You are standardizing on the NVIDIA reference for always-on assistants with policy and inference routing. | NemoClaw | +| You are building internal platform abstractions where the NemoClaw CLI or blueprint is not the right fit. | OpenShell (and your orchestration) | + +## Related topics + +| Page | View | +|------|------| +| Overview (see the `nemoclaw-user-overview` skill) | What NemoClaw is: capabilities, benefits, and use cases. | +| How It Works (see the `nemoclaw-user-overview` skill) | How NemoClaw runs: plugin, blueprint, sandbox creation, routing, protection layers. | +| Architecture (see the `nemoclaw-user-reference` skill) | Repository structure and technical diagrams. | diff --git a/.agents/skills/nemoclaw-user-overview/references/how-it-works.md b/.agents/skills/nemoclaw-user-overview/references/how-it-works.md new file mode 100644 index 000000000..c8fd5a01a --- /dev/null +++ b/.agents/skills/nemoclaw-user-overview/references/how-it-works.md @@ -0,0 +1,129 @@ +# How NemoClaw Works + +This page explains how NemoClaw operates, which parts run where, how the blueprint drives OpenShell, and how inference and policy attach to the sandbox. + +## How the Pieces Connect + +The `nemoclaw` CLI is the primary entrypoint for setting up and managing sandboxed OpenClaw agents. +It delegates heavy lifting to a versioned blueprint, a Python artifact that orchestrates sandbox creation, policy application, and inference provider setup through the OpenShell CLI. + +Between your shell and the running sandbox, NemoClaw contributes these integration layers: + +| Layer | Role in the flow | +|-------|------------------| +| Onboarding | `nemoclaw onboard` validates credentials, selects providers, and drives blueprint execution until the sandbox is ready. | +| Blueprint | Supplies the hardened image definition, default policies, capability posture, and orchestration steps the runner applies through OpenShell. | +| State management | Migrates agent state across machines with credential stripping and integrity checks. | +| Channel messaging | OpenShell-managed processes connect Telegram, Discord, Slack, and similar platforms to the agent. NemoClaw enables this through onboarding and blueprint wiring; delivery is not a separate NemoClaw host daemon. | + +For repository layout, file paths, and deeper diagrams, see Architecture (see the `nemoclaw-user-reference` skill). + +```mermaid +flowchart TB + subgraph Host + CMD["nemoclaw onboard"] + PLUGIN[nemoclaw plugin] + BLUEPRINT[blueprint runner] + CLI["openshell CLI sandbox · gateway · inference · policy"] + + CMD --> PLUGIN + PLUGIN --> BLUEPRINT + BLUEPRINT --> CLI + end + + subgraph Sandbox["OpenShell Sandbox"] + AGENT[OpenClaw agent] + INF[NVIDIA inference, routed] + NET[default network policy] + FS[filesystem isolation] + + AGENT --- INF + AGENT --- NET + AGENT --- FS + end + + PLUGIN --> AGENT + + classDef nv fill:#76b900,stroke:#333,color:#fff + classDef nvLight fill:#e6f2cc,stroke:#76b900,color:#1a1a1a + classDef nvDark fill:#333,stroke:#76b900,color:#fff + + class CMD,PLUGIN,BLUEPRINT nvDark + class CLI nv + class AGENT nv + class INF,NET,FS nvLight + + style Host fill:none,stroke:#76b900,stroke-width:2px,color:#1a1a1a + style Sandbox fill:#f5faed,stroke:#76b900,stroke-width:2px,color:#1a1a1a +``` + +## Design Principles + +NemoClaw architecture follows the following principles. + +Thin plugin, versioned blueprint +: The plugin stays small and stable. Orchestration logic lives in the blueprint and evolves on its own release cadence. + +Respect CLI boundaries +: The `nemoclaw` CLI is the primary interface for sandbox management. + +Supply chain safety +: Blueprint artifacts are immutable, versioned, and digest-verified before execution. + +OpenShell-backed lifecycle +: NemoClaw orchestrates OpenShell resources under the hood, but `nemoclaw onboard` + is the supported operator entry point for creating or recreating NemoClaw-managed sandboxes. + +Reproducible setup +: Running setup again recreates the sandbox from the same blueprint and policy definitions. + +## Plugin and Blueprint + +NemoClaw is split into two parts: + +- The *plugin* is a TypeScript package that registers an inference provider and the `/nemoclaw` slash command inside the sandbox. + It handles user interaction and delegates orchestration work to the blueprint. +- The *blueprint* is a versioned Python artifact that contains all the logic for creating sandboxes, applying policies, and configuring inference. + The plugin resolves, verifies, and executes the blueprint as a subprocess. + +This separation keeps the plugin small and stable while allowing the blueprint to evolve on its own release cadence. + +## Sandbox Creation + +When you run `nemoclaw onboard`, NemoClaw creates an OpenShell sandbox that runs OpenClaw in an isolated container. +The blueprint orchestrates this process through the OpenShell CLI: + +1. The plugin downloads the blueprint artifact, checks version compatibility, and verifies the digest. +2. The blueprint determines which OpenShell resources to create or update, such as the gateway, inference providers, sandbox, and network policy. +3. The blueprint calls OpenShell CLI commands to create the sandbox and configure each resource. + +After the sandbox starts, the agent runs inside it with all network, filesystem, and inference controls in place. + +## Inference Routing + +Inference requests from the agent never leave the sandbox directly. +OpenShell intercepts every inference call and routes it to the configured provider. +During onboarding, NemoClaw validates the selected provider and model, configures the OpenShell route, and bakes the matching model reference into the sandbox image. +The sandbox then talks to `inference.local`, while the host owns the actual provider credential and upstream endpoint. + +## Protection Layers + +The sandbox starts with a default policy that controls network egress, filesystem access, process privileges, and inference routing. + +| Layer | What it protects | When it applies | +|---|---|---| +| Network | Blocks unauthorized outbound connections. | Hot-reloadable at runtime. | +| Filesystem | Prevents reads and writes outside `/sandbox` and `/tmp`. | Locked at sandbox creation. | +| Process | Blocks privilege escalation and dangerous syscalls. | Locked at sandbox creation. | +| Inference | Reroutes model API calls to controlled backends. | Hot-reloadable at runtime. | + +When the agent tries to reach an unlisted host, OpenShell blocks the request and surfaces it in the TUI for operator approval. Approved endpoints persist for the current session but are not saved to the baseline policy file. + +For details on the baseline rules, refer to Network Policies (see the `nemoclaw-user-reference` skill). For container-level hardening, refer to Sandbox Hardening (see the `nemoclaw-user-deploy-remote` skill). + +## Next Steps + +- Read Ecosystem (see the `nemoclaw-user-overview` skill) for stack-level relationships and NemoClaw versus OpenShell-only paths. +- Follow the Quickstart (see the `nemoclaw-user-get-started` skill) to launch your first sandbox. +- Refer to the Architecture (see the `nemoclaw-user-reference` skill) for the full technical structure, including file layouts and the blueprint lifecycle. +- Refer to Inference Options (see the `nemoclaw-user-configure-inference` skill) for detailed provider configuration. diff --git a/.agents/skills/nemoclaw-user-overview/references/overview.md b/.agents/skills/nemoclaw-user-overview/references/overview.md new file mode 100644 index 000000000..18c7cf1e5 --- /dev/null +++ b/.agents/skills/nemoclaw-user-overview/references/overview.md @@ -0,0 +1,64 @@ +# Overview + +NVIDIA NemoClaw is an open source reference stack that simplifies running [OpenClaw](https://openclaw.ai) always-on assistants. +NemoClaw provides onboarding, lifecycle management, and management of OpenClaw within OpenShell containers. +It incorporates policy-based privacy and security guardrails, giving you control over your agents’ behavior and data handling. +This enables self-evolving claws to run more safely in clouds, on prem, RTX PCs and DGX Spark. + +NemoClaw pairs open source and hosted models (for example [NVIDIA Nemotron](https://build.nvidia.com)) with a hardened sandbox, routed inference, and declarative egress policy so deployment stays safer and more repeatable. +The sandbox runtime comes from [NVIDIA OpenShell](https://github.com/NVIDIA/OpenShell); NemoClaw adds the blueprint, `nemoclaw` CLI, onboarding, and related tooling as the reference way to run OpenClaw there. + +| Capability | Description | +|-------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------| +| Sandbox OpenClaw | Creates an OpenShell sandbox pre-configured for OpenClaw, with filesystem and network policies applied from the first boot. | +| Route inference | Configures OpenShell inference routing so agent traffic goes to the provider and model you chose during onboarding (NVIDIA Endpoints, OpenAI, Anthropic, Gemini, compatible endpoints, local Ollama, and others). The agent uses `inference.local` inside the sandbox; credentials stay on the host. | +| Manage the lifecycle | Handles blueprint versioning, digest verification, and sandbox setup. | + +## Key Features + +NemoClaw provides the following product capabilities. + +| Feature | Description | +|---------|-------------| +| Guided onboarding | Validates credentials, selects providers, and creates a working sandbox in one command. | +| Hardened blueprint | A security-first Dockerfile with capability drops, least-privilege network rules, and declarative policy. | +| State management | Safe migration of agent state across machines with credential stripping and integrity verification. | +| Channel messaging | OpenShell-managed processes connect Telegram, Discord, Slack, and similar platforms to the sandboxed agent. NemoClaw configures channels during onboarding; OpenShell supplies the native constructs, credential flow, and runtime supervision. | +| Routed inference | Provider-routed model calls through the OpenShell gateway, transparent to the agent. Supports NVIDIA Endpoints, OpenAI, Anthropic, Google Gemini, and local Ollama. | +| Layered protection | Network, filesystem, process, and inference controls that can be hot-reloaded or locked at creation. | + +## Challenge + +Autonomous AI agents like OpenClaw can make arbitrary network requests, access the host filesystem, and call any inference endpoint. Without guardrails, this creates security, cost, and compliance risks that grow as agents run unattended. + +## Benefits + +NemoClaw provides the following benefits. + +| Benefit | Description | +|----------------------------|------------------------------------------------------------------------------------------------------------------------| +| Sandboxed execution | Every agent runs inside an OpenShell sandbox with Landlock, seccomp, and network namespace isolation. No access is granted by default. | +| Routed inference | Model traffic is routed through the OpenShell gateway to your selected provider, transparent to the agent. You can switch providers or models. Refer to Inference Options (see the `nemoclaw-user-configure-inference` skill). | +| Declarative network policy | Egress rules are defined in YAML. Unknown hosts are blocked and surfaced to the operator for approval. | +| Single CLI | The `nemoclaw` command orchestrates the full stack: gateway, sandbox, inference provider, and network policy. | +| Blueprint lifecycle | Versioned blueprints handle sandbox creation, digest verification, and reproducible setup. | + +## Use Cases + +You can use NemoClaw for various use cases including the following. + +| Use Case | Description | +|---------------------------|----------------------------------------------------------------------------------------------| +| Always-on assistant | Run an OpenClaw assistant with controlled network access and operator-approved egress. | +| Sandboxed testing | Test agent behavior in a locked-down environment before granting broader permissions. | +| Remote GPU deployment | Deploy a sandboxed agent to a remote GPU instance for persistent operation. | + +## Next Steps + +- Ecosystem (see the `nemoclaw-user-overview` skill) to understand how OpenClaw, OpenShell, and NemoClaw relate in the wider stack, and when to use NemoClaw versus OpenShell. +- How It Works (see the `nemoclaw-user-overview` skill) to understand how NemoClaw works internally: plugin, blueprint, sandbox lifecycle. +- Quickstart (see the `nemoclaw-user-get-started` skill) to install NemoClaw and run your first agent. +- Switch Inference Providers (see the `nemoclaw-user-configure-inference` skill) to configure the inference provider. +- Approve or Deny Network Requests (see the `nemoclaw-user-manage-policy` skill) to manage egress approvals. +- Deploy to a Remote GPU Instance (see the `nemoclaw-user-deploy-remote` skill) for persistent operation. +- Monitor Sandbox Activity (see the `nemoclaw-user-monitor-sandbox` skill) to observe agent behavior. diff --git a/.agents/skills/nemoclaw-user-overview/references/release-notes.md b/.agents/skills/nemoclaw-user-overview/references/release-notes.md new file mode 100644 index 000000000..ea482162c --- /dev/null +++ b/.agents/skills/nemoclaw-user-overview/references/release-notes.md @@ -0,0 +1,10 @@ +# Release Notes + +NVIDIA NemoClaw is available in early preview starting March 16, 2026. Use the following GitHub resources to track changes. + +| Resource | Description | +|---|---| +| [Releases](https://github.com/NVIDIA/NemoClaw/releases) | Versioned release notes and downloadable assets. | +| [Release comparison](https://github.com/NVIDIA/NemoClaw/compare) | Diff between any two tags or branches. | +| [Merged pull requests](https://github.com/NVIDIA/NemoClaw/pulls?q=is%3Apr+is%3Amerged) | Individual changes with review discussion. | +| [Commit history](https://github.com/NVIDIA/NemoClaw/commits/main) | Full commit log on `main`. | diff --git a/.agents/skills/nemoclaw-user-reference/SKILL.md b/.agents/skills/nemoclaw-user-reference/SKILL.md new file mode 100644 index 000000000..ca2fd53a2 --- /dev/null +++ b/.agents/skills/nemoclaw-user-reference/SKILL.md @@ -0,0 +1,15 @@ +--- +name: "nemoclaw-user-reference" +description: "Describes how NemoClaw combines a CLI plugin with a versioned blueprint to move OpenClaw into a controlled sandbox. Use when looking up NemoClaw architecture, plugin structure, or blueprint design. Lists all slash commands and standalone NemoClaw CLI commands. Use when looking up a command, checking command syntax, or browsing the CLI reference. Documents baseline network policy, filesystem rules, and operator approval flow. Use when reviewing default network policies, understanding egress controls, or looking up the approval flow. Diagnoses and resolves common NemoClaw installation, onboarding, and runtime issues. Use when troubleshooting errors, debugging sandbox problems, or resolving setup failures." +--- + +# NemoClaw User Reference + +Describes how NemoClaw combines a CLI plugin with a versioned blueprint to move OpenClaw into a controlled sandbox. Use when looking up NemoClaw architecture, plugin structure, or blueprint design. + +## Reference + +- [NemoClaw Architecture: Plugin, Blueprint, and Sandbox Structure](references/architecture.md) +- [NemoClaw CLI Commands Reference](references/commands.md) +- [NemoClaw Network Policies: Baseline Rules and Operator Approval](references/network-policies.md) +- [NemoClaw Troubleshooting Guide](references/troubleshooting.md) diff --git a/.agents/skills/nemoclaw-user-reference/references/architecture.md b/.agents/skills/nemoclaw-user-reference/references/architecture.md new file mode 100644 index 000000000..c8bfb0721 --- /dev/null +++ b/.agents/skills/nemoclaw-user-reference/references/architecture.md @@ -0,0 +1,173 @@ +# Architecture + +NemoClaw has two main components: a TypeScript plugin that integrates with the OpenClaw CLI, and a Python blueprint that orchestrates OpenShell resources. + +## System Overview + +NVIDIA OpenShell is a general-purpose agent runtime. It provides sandbox containers, a credential-storing gateway, inference proxying, and policy enforcement, but has no opinions about what runs inside. NemoClaw is an opinionated reference stack built on OpenShell that handles what goes in the sandbox and makes the setup accessible. + +```mermaid +graph LR + classDef nemoclaw fill:#76b900,stroke:#5a8f00,color:#fff,stroke-width:2px,font-weight:bold + classDef openshell fill:#1a1a1a,stroke:#1a1a1a,color:#fff,stroke-width:2px,font-weight:bold + classDef sandbox fill:#444,stroke:#76b900,color:#fff,stroke-width:2px,font-weight:bold + classDef agent fill:#f5f5f5,stroke:#e0e0e0,color:#1a1a1a,stroke-width:1px + classDef external fill:#f5f5f5,stroke:#e0e0e0,color:#1a1a1a,stroke-width:1px + classDef user fill:#fff,stroke:#76b900,color:#1a1a1a,stroke-width:2px,font-weight:bold + + USER(["👤 User"]):::user + + subgraph EXTERNAL["External Services"] + INFERENCE["Inference Provider
NVIDIA Endpoints · OpenAI
Anthropic · Ollama · vLLM"]:::external + MSGAPI["Messaging Platforms
Telegram · Discord · Slack"]:::external + INTERNET["Internet
PyPI · npm · GitHub · APIs"]:::external + end + + subgraph HOST["Host Machine"] + + subgraph NEMOCLAW["NemoClaw"] + direction TB + NCLI["CLI + Onboarding
Guided setup · provider selection
credential validation · deploy"]:::nemoclaw + BP["Blueprint
Hardened Dockerfile
Network policies · Presets
Security configuration"]:::nemoclaw + MIGRATE["State Management
Migration snapshots
Credential stripping
Integrity verification"]:::nemoclaw + end + + subgraph OPENSHELL["OpenShell"] + direction TB + GW["Gateway
Credential store
Inference proxy
Policy engine
Device auth"]:::openshell + OSCLI["openshell CLI
provider · sandbox
gateway · policy"]:::openshell + CHMSG["Channel messaging
OpenShell-managed
Telegram · Discord · Slack"]:::openshell + + subgraph SANDBOX["Sandbox Container 🔒"] + direction TB + AGENT["Agent
OpenClaw or any
compatible agent"]:::agent + PLUG["NemoClaw Plugin
Extends agent with
managed configuration"]:::sandbox + end + end + end + + USER -->|"nemoclaw onboard
nemoclaw connect"| NCLI + USER -->|"Chat messages"| MSGAPI + + NCLI -->|"Orchestrates"| OSCLI + BP -->|"Defines sandbox
shape + policies"| SANDBOX + MIGRATE -->|"Safe state
transfer"| SANDBOX + + AGENT -->|"Inference requests
no credentials"| GW + GW -->|"Proxied with
credential injected"| INFERENCE + + MSGAPI -->|"Platform APIs"| CHMSG + CHMSG -->|"Deliver to agent"| AGENT + + AGENT -.->|"Policy-gated"| INTERNET + GW -.->|"Enforced by
gateway"| INTERNET +``` + +## NemoClaw Plugin + +The plugin is a thin TypeScript package that registers an inference provider and the `/nemoclaw` slash command. +It runs in-process with the OpenClaw gateway inside the sandbox. + +```text +nemoclaw/ +├── src/ +│ ├── index.ts Plugin entry: registers all commands +│ ├── cli.ts Commander.js subcommand wiring +│ ├── commands/ +│ │ ├── launch.ts Fresh install into OpenShell +│ │ ├── connect.ts Interactive shell into sandbox +│ │ ├── status.ts Blueprint run state + sandbox health +│ │ ├── logs.ts Stream blueprint and sandbox logs +│ │ └── slash.ts /nemoclaw chat command handler +│ └── blueprint/ +│ ├── resolve.ts Version resolution, cache management +│ ├── fetch.ts Download blueprint from OCI registry +│ ├── verify.ts Digest verification, compatibility checks +│ ├── exec.ts Subprocess execution of blueprint runner +│ └── state.ts Persistent state (run IDs) +├── openclaw.plugin.json Plugin manifest +└── package.json Commands declared under openclaw.extensions +``` + +## NemoClaw Blueprint + +The blueprint is a versioned Python artifact with its own release stream. +The plugin resolves, verifies, and executes the blueprint as a subprocess. +The blueprint drives all interactions with the OpenShell CLI. + +```text +nemoclaw-blueprint/ +├── blueprint.yaml Manifest: version, profiles, compatibility +├── policies/ +│ └── openclaw-sandbox.yaml Default network + filesystem policy +``` + +The blueprint runtime (TypeScript) lives in the plugin source tree: + +```text +nemoclaw/src/blueprint/ +├── runner.ts CLI runner: plan / apply / status / rollback +├── ssrf.ts SSRF endpoint validation (IP + DNS checks) +├── snapshot.ts Migration snapshot / restore lifecycle +├── state.ts Persistent run state management +``` + +### Blueprint Lifecycle + +```mermaid +flowchart LR + A[resolve] --> B[verify digest] + B --> C[plan] + C --> D[apply] + D --> E[status] +``` + +1. Resolve. The plugin locates the blueprint artifact and checks the version against `min_openshell_version` and `min_openclaw_version` constraints in `blueprint.yaml`. +2. Verify. The plugin checks the artifact digest against the expected value. +3. Plan. The runner determines what OpenShell resources to create or update, such as the gateway, providers, sandbox, inference route, and policy. +4. Apply. The runner executes the plan by calling `openshell` CLI commands. +5. Status. The runner reports current state. + +## Sandbox Environment + +The sandbox runs the +[`ghcr.io/nvidia/openshell-community/sandboxes/openclaw`](https://github.com/NVIDIA/OpenShell-Community) +container image. Inside the sandbox: + +- OpenClaw runs with the NemoClaw plugin pre-installed. +- Inference calls are routed through OpenShell to the configured provider. +- Network egress is restricted by the baseline policy in `openclaw-sandbox.yaml`. +- Filesystem access is confined to `/sandbox` and `/tmp` for read-write access, with system paths read-only. + +## Inference Routing + +Inference requests from the agent never leave the sandbox directly. +OpenShell intercepts them and routes to the configured provider: + +```text +Agent (sandbox) ──▶ OpenShell gateway ──▶ NVIDIA Endpoint (build.nvidia.com) +``` + +Refer to Inference Options (see the `nemoclaw-user-configure-inference` skill) for provider configuration details. + +## Host-Side State and Config + +NemoClaw keeps its operator-facing state on the host rather than inside the sandbox. + +| Path | Purpose | +|---|---| +| `~/.nemoclaw/credentials.json` | Provider credentials saved during onboarding. Stored as plaintext JSON protected by local filesystem permissions; see Credential Storage (see the `nemoclaw-user-configure-security` skill). | +| `~/.nemoclaw/sandboxes.json` | Registered sandbox metadata, including the default sandbox selection. | +| `~/.openclaw/openclaw.json` | Host OpenClaw configuration that NemoClaw snapshots or restores during migration flows. | + +The following environment variables configure optional services and local access. + +| Variable | Purpose | +|---|---| +| `TELEGRAM_BOT_TOKEN` | Telegram bot token you provide before `nemoclaw onboard`. OpenShell stores it in a provider; the sandbox receives placeholders, not the raw secret. | +| `TELEGRAM_ALLOWED_IDS` | Comma-separated Telegram user or chat IDs for allowlists when onboarding applies channel restrictions. | +| `CHAT_UI_URL` | URL for the optional chat UI endpoint. | +| `NEMOCLAW_DISABLE_DEVICE_AUTH` | Build-time-only toggle that disables gateway device pairing when set to `1` before the sandbox image is created. | + +For normal setup and reconfiguration, prefer `nemoclaw onboard` over editing these files by hand. +Do not treat `NEMOCLAW_DISABLE_DEVICE_AUTH` as a runtime setting for an already-created sandbox. diff --git a/.agents/skills/nemoclaw-user-reference/references/commands.md b/.agents/skills/nemoclaw-user-reference/references/commands.md new file mode 100644 index 000000000..5fb6dadde --- /dev/null +++ b/.agents/skills/nemoclaw-user-reference/references/commands.md @@ -0,0 +1,267 @@ +# Commands + +The `nemoclaw` CLI is the primary interface for managing NemoClaw sandboxes. It is installed when you run `npm install -g nemoclaw`. + +## `/nemoclaw` Slash Command + +The `/nemoclaw` slash command is available inside the OpenClaw chat interface for quick actions: + +| Subcommand | Description | +|---|---| +| `/nemoclaw` | Show slash-command help and host CLI pointers | +| `/nemoclaw status` | Show sandbox and inference state | +| `/nemoclaw onboard` | Show onboarding status and reconfiguration guidance | +| `/nemoclaw eject` | Show rollback instructions for returning to the host installation | + +## Standalone Host Commands + +The `nemoclaw` binary handles host-side operations that run outside the OpenClaw plugin context. + +### `nemoclaw help`, `nemoclaw --help`, `nemoclaw -h` + +Show the top-level usage summary and command groups. +Running `nemoclaw` with no arguments shows the same help output. + +```console +$ nemoclaw help +``` + +### `nemoclaw --version`, `nemoclaw -v` + +Print the installed NemoClaw CLI version. + +```console +$ nemoclaw --version +``` + +### `nemoclaw onboard` + +Run the interactive setup wizard (recommended for new installs). +The wizard creates an OpenShell gateway, registers inference providers, builds the sandbox image, and creates the sandbox. +Use this command for new installs and for recreating a sandbox after changes to policy or configuration. + +```console +$ nemoclaw onboard [--non-interactive] [--resume] [--from ] +``` + +> **Warning:** For NemoClaw-managed environments, use `nemoclaw onboard` when you need to create or recreate the OpenShell gateway or sandbox. +> Avoid `openshell self-update`, `npm update -g openshell`, `openshell gateway start --recreate`, or `openshell sandbox create` directly unless you intend to manage OpenShell separately and then rerun `nemoclaw onboard`. + +The wizard prompts for a provider first, then collects the provider credential if needed. +Supported non-experimental choices include NVIDIA Endpoints, OpenAI, Anthropic, Google Gemini, and compatible OpenAI or Anthropic endpoints. +Credentials are stored in `~/.nemoclaw/credentials.json`. For file permissions, plaintext storage behavior, and hardening guidance, see Credential Storage (see the `nemoclaw-user-configure-security` skill). +The legacy `nemoclaw setup` command is deprecated; use `nemoclaw onboard` instead. + +If you enable Brave Search during onboarding, NemoClaw currently stores the Brave API key in the sandbox's OpenClaw configuration. +That means the OpenClaw agent can read the key. +NemoClaw explores an OpenShell-hosted credential path first, but the current OpenClaw Brave runtime does not consume that path end to end yet. +Treat Brave Search as an explicit opt-in and use a dedicated low-privilege Brave key. + +For non-interactive onboarding, you must explicitly accept the third-party software notice: + +```console +$ nemoclaw onboard --non-interactive --yes-i-accept-third-party-software +``` + +or: + +```console +$ NEMOCLAW_ACCEPT_THIRD_PARTY_SOFTWARE=1 nemoclaw onboard --non-interactive +``` + +To enable Brave Search in non-interactive mode, set: + +```console +$ BRAVE_API_KEY=... \ + nemoclaw onboard --non-interactive +``` + +`BRAVE_API_KEY` enables Brave Search in non-interactive mode and also enables `web_fetch`. + +The wizard prompts for a sandbox name. +Names must follow RFC 1123 subdomain rules: lowercase alphanumeric characters and hyphens only, and must start and end with an alphanumeric character. +Uppercase letters are automatically lowercased. + +Before creating the gateway, the wizard runs preflight checks. +It verifies that Docker is reachable, warns on unsupported runtimes such as Podman, and prints host remediation guidance when prerequisites are missing. + +#### `--from ` + +Build the sandbox image from a custom Dockerfile instead of the stock NemoClaw image. +The entire parent directory of the specified file is used as the Docker build context, so any files your Dockerfile references (scripts, config, etc.) must live alongside it. + +```console +$ nemoclaw onboard --from path/to/Dockerfile +``` + +The file can have any name; if it is not already named `Dockerfile`, onboard copies it to `Dockerfile` inside the staged build context automatically. +All NemoClaw build arguments (`NEMOCLAW_MODEL`, `NEMOCLAW_PROVIDER_KEY`, `NEMOCLAW_INFERENCE_BASE_URL`, etc.) are injected as `ARG` overrides at build time, so declare them in your Dockerfile if you need to reference them. + +In non-interactive mode, the path can also be supplied via the `NEMOCLAW_FROM_DOCKERFILE` environment variable: + +```console +$ NEMOCLAW_NON_INTERACTIVE=1 NEMOCLAW_FROM_DOCKERFILE=path/to/Dockerfile nemoclaw onboard +``` + +If a `--resume` is attempted with a different `--from` path than the original session, onboarding exits with a conflict error rather than silently building from the wrong image. + +### `nemoclaw list` + +List all registered sandboxes with their model, provider, and policy presets. + +```console +$ nemoclaw list +``` + +### `nemoclaw deploy` + +> **Warning:** The `nemoclaw deploy` command is deprecated. +> Prefer provisioning the remote host separately, then running the standard NemoClaw installer and `nemoclaw onboard` on that host. + +Deploy NemoClaw to a remote GPU instance through [Brev](https://brev.nvidia.com). +This command remains as a compatibility wrapper for the older Brev-specific bootstrap flow. + +```console +$ nemoclaw deploy +``` + +### `nemoclaw connect` + +Connect to a sandbox by name. + +```console +$ nemoclaw my-assistant connect +``` + +### `nemoclaw status` + +Show sandbox status, health, and inference configuration. + +```console +$ nemoclaw my-assistant status +``` + +### `nemoclaw logs` + +View sandbox logs. +Use `--follow` to stream output in real time. + +```console +$ nemoclaw my-assistant logs [--follow] +``` + +### `nemoclaw destroy` + +Stop the NIM container and delete the sandbox. +This removes the sandbox from the registry. + +> **Warning:** Destroying a sandbox permanently deletes all files inside it, including +> workspace files (see the `nemoclaw-user-workspace` skill) (SOUL.md, USER.md, IDENTITY.md, AGENTS.md, MEMORY.md, and daily memory notes). +> Back up your workspace first by following the instructions at Back Up and Restore (see the `nemoclaw-user-workspace` skill). + +```console +$ nemoclaw my-assistant destroy +``` + +### `nemoclaw policy-add` + +Add a policy preset to a sandbox. +Presets extend the baseline network policy with additional endpoints. + +```console +$ nemoclaw my-assistant policy-add +``` + +### `nemoclaw policy-list` + +List available policy presets and show which ones are applied to the sandbox. + +```console +$ nemoclaw my-assistant policy-list +``` + +### `openshell term` + +Open the OpenShell TUI to monitor sandbox activity and approve network egress requests. +Run this on the host where the sandbox is running. + +```console +$ openshell term +``` + +For a remote Brev instance, SSH to the instance and run `openshell term` there, or use a port-forward to the gateway. + +### `nemoclaw start` + +Start optional host auxiliary services. This is the cloudflared tunnel when `cloudflared` is installed (for a public URL to the dashboard). Channel messaging (Telegram, Discord, Slack) is not started here; it is configured during `nemoclaw onboard` and runs through OpenShell-managed constructs. + +```console +$ nemoclaw start +``` + +### `nemoclaw stop` + +Stop host auxiliary services started by `nemoclaw start` (for example cloudflared). + +```console +$ nemoclaw stop +``` + +### `nemoclaw status` + +Show the sandbox list and the status of host auxiliary services (for example cloudflared). + +```console +$ nemoclaw status +``` + +### `nemoclaw setup-spark` + +> **Warning:** 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`. + +```console +$ nemoclaw setup-spark +``` + +### `nemoclaw debug` + +Collect diagnostics for bug reports. +Gathers system info, Docker state, gateway logs, and sandbox status into a summary or tarball. +Use `--sandbox ` to target a specific sandbox, `--quick` for a smaller snapshot, or `--output ` to save a tarball that you can attach to an issue. + +```console +$ nemoclaw debug [--quick] [--sandbox NAME] [--output PATH] +``` + +| Flag | Description | +|------|-------------| +| `--quick` | Collect minimal diagnostics only | +| `--sandbox NAME` | Target a specific sandbox (default: auto-detect) | +| `--output PATH` | Write diagnostics tarball to the given path | + +### `nemoclaw uninstall` + +Run `uninstall.sh` to remove NemoClaw sandboxes, gateway resources, related images and containers, and local state. +The CLI uses the local `uninstall.sh` first and falls back to the hosted script if the local file is unavailable. + +| Flag | Effect | +|---|---| +| `--yes` | Skip the confirmation prompt | +| `--keep-openshell` | Leave the `openshell` binary installed | +| `--delete-models` | Also remove NemoClaw-pulled Ollama models | + +```console +$ nemoclaw uninstall [--yes] [--keep-openshell] [--delete-models] +``` + +### Legacy `nemoclaw setup` + +Deprecated. Use `nemoclaw onboard` instead. +Running `nemoclaw setup` now delegates directly to `nemoclaw onboard`. + +```console +$ nemoclaw setup +``` diff --git a/.agents/skills/nemoclaw-user-reference/references/network-policies.md b/.agents/skills/nemoclaw-user-reference/references/network-policies.md new file mode 100644 index 000000000..7e895cf43 --- /dev/null +++ b/.agents/skills/nemoclaw-user-reference/references/network-policies.md @@ -0,0 +1,122 @@ +# Network Policies + +NemoClaw runs with a deny-by-default network policy. +The sandbox can only reach endpoints that are explicitly allowed. +Any request to an unlisted destination is intercepted by OpenShell, and the operator is prompted to approve or deny it in real time through the TUI. + +## Baseline Policy + +The baseline policy is defined in `nemoclaw-blueprint/policies/openclaw-sandbox.yaml`. + +### Filesystem + +| Path | Access | +|---|---| +| `/sandbox`, `/tmp`, `/dev/null` | Read-write | +| `/usr`, `/lib`, `/proc`, `/dev/urandom`, `/app`, `/etc`, `/var/log` | Read-only | + +The sandbox process runs as a dedicated `sandbox` user and group. +Landlock LSM enforcement applies on a best-effort basis. + +### Network Policies + +The following endpoint groups are allowed by default: + +:::{list-table} +:header-rows: 1 +:widths: 20 30 20 30 + +* - Policy + - Endpoints + - Binaries + - Rules + +* - `claude_code` + - `api.anthropic.com:443`, `statsig.anthropic.com:443`, `sentry.io:443` + - `/usr/local/bin/claude` + - All methods + +* - `nvidia` + - `integrate.api.nvidia.com:443`, `inference-api.nvidia.com:443` + - `/usr/local/bin/claude`, `/usr/local/bin/openclaw` + - All methods + +* - `github` + - `github.com:443` + - `/usr/bin/gh`, `/usr/bin/git` + - All methods, all paths + +* - `github_rest_api` + - `api.github.com:443` + - `/usr/bin/gh` + - GET, POST, PATCH, PUT, DELETE + +* - `clawhub` + - `clawhub.ai:443` + - `/usr/local/bin/openclaw`, `/usr/local/bin/node` + - GET, POST + +* - `openclaw_api` + - `openclaw.ai:443` + - `/usr/local/bin/openclaw`, `/usr/local/bin/node` + - GET, POST + +* - `openclaw_docs` + - `docs.openclaw.ai:443` + - `/usr/local/bin/openclaw` + - GET only + +* - `npm_registry` + - `registry.npmjs.org:443` + - `/usr/local/bin/openclaw`, `/usr/local/bin/npm`, `/usr/local/bin/node` + - All methods, all paths + +* - `telegram` + - `api.telegram.org:443` + - Any binary + - GET, POST on `/bot*/**` + +::: + +All endpoints use TLS termination and are enforced at port 443. + +### Inference + +The baseline policy allows only the `local` inference route. External inference +providers are reached through the OpenShell gateway, not by direct sandbox egress. + +## Operator Approval Flow + +When the agent attempts to reach an endpoint not listed in the policy, OpenShell intercepts the request and presents it in the TUI for operator review: + +1. The agent makes a network request to an unlisted host. +2. OpenShell blocks the connection and logs the attempt. +3. The TUI command `openshell term` displays the blocked request with host, port, and requesting binary. +4. The operator approves or denies the request. +5. If approved, the endpoint is added to the running policy for the session. + +To try this, run the walkthrough: + +```console +$ ./scripts/walkthrough.sh +``` + +This opens a split tmux session with the TUI on the left and the agent on the right. + +## Modifying the Policy + +### Static Changes + +Edit `nemoclaw-blueprint/policies/openclaw-sandbox.yaml` and re-run the onboard wizard: + +```console +$ nemoclaw onboard +``` + +### Dynamic Changes + +Apply policy updates to a running sandbox without restarting: + +```console +$ openshell policy set +``` diff --git a/.agents/skills/nemoclaw-user-reference/references/troubleshooting.md b/.agents/skills/nemoclaw-user-reference/references/troubleshooting.md new file mode 100644 index 000000000..118e3163e --- /dev/null +++ b/.agents/skills/nemoclaw-user-reference/references/troubleshooting.md @@ -0,0 +1,308 @@ +# Troubleshooting + +This page covers common issues you may encounter when installing, onboarding, or running NemoClaw, along with their resolution steps. + +> **Get Help:** If your issue is not listed here, join the [NemoClaw Discord channel](https://discord.gg/XFpfPv9Uvx) to ask questions and get help from the community. You can also [file an issue on GitHub](https://github.com/NVIDIA/NemoClaw/issues/new). + +## Installation + +### `nemoclaw` not found after install + +If you use nvm or fnm to manage Node.js, the installer may not update your current shell's PATH. +The `nemoclaw` binary is installed but the shell session does not know where to find it. + +Run `source ~/.bashrc` (or `source ~/.zshrc` for zsh), or open a new terminal window. + +### Installer fails on unsupported platform + +The installer checks for a supported OS and architecture before proceeding. +NemoClaw requires Linux Ubuntu 22.04 LTS or later. +If you see an unsupported platform error, verify that you are running on a supported Linux distribution. + +### Node.js version is too old + +NemoClaw requires Node.js 22.16 or later. +If the installer exits with a Node.js version error, check your current version: + +```console +$ node --version +``` + +If the version is below 22.16, install a supported release. +If you use nvm, run: + +```console +$ nvm install 22 +$ nvm use 22 +``` + +Then re-run the installer. + +### Image push fails with out-of-memory errors + +The sandbox image is approximately 2.4 GB compressed. During image push, the Docker daemon, k3s, and the OpenShell gateway run alongside the export pipeline, which buffers decompressed layers in memory. On machines with less than 8 GB of RAM, this combined usage can trigger the OOM killer. + +If you cannot add memory, configure at least 8 GB of swap to work around the issue at the cost of slower performance. + +### Docker is not running + +The installer and onboard wizard require Docker to be running. +If you see a Docker connection error, start the Docker daemon: + +```console +$ sudo systemctl start docker +``` + +On macOS with Docker Desktop, open the Docker Desktop application and wait for it to finish starting before retrying. + +### macOS first-run failures + +The two most common first-run failures on macOS are missing developer tools and Docker connection errors. + +To avoid these issues, install the prerequisites in the following order before running the NemoClaw installer: + +1. Install Xcode Command Line Tools (`xcode-select --install`). These are needed by the installer and Node.js toolchain. +2. Install and start a supported container runtime (Docker Desktop or Colima). Without a running runtime, the installer cannot connect to Docker. + +### npm install fails with permission errors + +If `npm install` fails with an `EACCES` permission error, do not run npm with `sudo`. +Instead, configure npm to use a directory you own: + +```console +$ mkdir -p ~/.npm-global +$ npm config set prefix ~/.npm-global +$ export PATH=~/.npm-global/bin:$PATH +``` + +Add the `export` line to your `~/.bashrc` or `~/.zshrc` to make it permanent, then re-run the installer. + +### Port already in use + +The NemoClaw gateway uses port `18789` by default. +If another process is already bound to this port, onboarding fails. +Identify the conflicting process, verify it is safe to stop, and terminate it: + +```console +$ sudo lsof -i :18789 +$ kill +``` + +If the process does not exit, use `kill -9 ` to force-terminate it. +Then retry onboarding. + +## Onboarding + +### Cgroup v2 errors during onboard + +Older NemoClaw releases relied on a Docker cgroup workaround on Ubuntu 24.04, DGX Spark, and WSL2. +Current OpenShell releases handle that behavior themselves, so NemoClaw no longer requires a Spark-specific setup step. + +If onboarding reports that Docker is missing or unreachable, fix Docker first and retry onboarding: + +```console +$ nemoclaw onboard +``` + +If you are using Podman, NemoClaw warns and continues, but OpenShell officially documents Docker-based runtimes only. +If onboarding or sandbox lifecycle fails, switch to Docker Desktop, Colima, or Docker Engine and rerun onboarding. + +### Invalid sandbox name + +Sandbox names must follow RFC 1123 subdomain rules: lowercase alphanumeric characters and hyphens only, and must start and end with an alphanumeric character. +Uppercase letters are automatically lowercased. + +If the name does not match these rules, the wizard exits with an error. +Choose a name such as `my-assistant` or `dev1`. + +### Sandbox creation fails on DGX + +On DGX machines, sandbox creation can fail if the gateway's DNS has not finished propagating or if a stale port forward from a previous onboard run is still active. + +Run `nemoclaw onboard` to retry. +The wizard cleans up stale port forwards and waits for gateway readiness automatically. + +### Colima socket not detected (macOS) + +Newer Colima versions use the XDG base directory (`~/.config/colima/default/docker.sock`) instead of the legacy path (`~/.colima/default/docker.sock`). +NemoClaw checks both paths. +If neither is found, verify that Colima is running: + +```console +$ colima status +``` + +### Sandbox creation killed by OOM (exit 137) + +On systems with 8 GB RAM or less and no swap configured, the sandbox image push can exhaust available memory and get killed by the Linux OOM killer (exit code 137). + +NemoClaw automatically detects low memory during onboarding and prompts to create a 4 GB swap file. +If this automatic step fails or you are using a custom setup flow, create swap manually before running `nemoclaw onboard`: + +```console +$ sudo dd if=/dev/zero of=/swapfile bs=1M count=4096 status=none +$ sudo chmod 600 /swapfile +$ sudo mkswap /swapfile +$ sudo swapon /swapfile +$ echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab +$ nemoclaw onboard +``` + +## Runtime + +### Reconnect after a host reboot + +After a host reboot, the container runtime, OpenShell gateway, and sandbox may not be running. +Follow these steps to reconnect. + +1. Start the container runtime. + + - **Linux:** start Docker if it is not already running (`sudo systemctl start docker`) + - **macOS:** open Docker Desktop or start Colima (`colima start`) + +1. Check sandbox state. + + ```console + $ openshell sandbox list + ``` + + If the sandbox shows `Ready`, skip to step 4. + +1. Restart the gateway (if needed). + + If the sandbox is not listed or the command fails, restart the OpenShell gateway: + + ```console + $ openshell gateway start --name nemoclaw + ``` + + Wait a few seconds, then re-check with `openshell sandbox list`. + +1. Reconnect. + + ```console + $ nemoclaw connect + ``` + +1. Start host auxiliary services (if needed). + + If you use the cloudflared tunnel started by `nemoclaw start`, start it again: + + ```console + $ nemoclaw start + ``` + + Telegram, Discord, and Slack are handled by OpenShell-managed channel messaging configured at onboarding, not by a separate bridge process from `nemoclaw start`. + +> **If the sandbox does not recover:** If the sandbox remains missing after restarting the gateway, run `nemoclaw onboard` to recreate it. +> The wizard prompts for confirmation before destroying an existing sandbox. If you confirm, it **destroys and recreates** the sandbox. Workspace files (SOUL.md, USER.md, IDENTITY.md, AGENTS.md, MEMORY.md, and daily memory notes) are lost. +> Back up your workspace first by following the instructions at Back Up and Restore (see the `nemoclaw-user-workspace` skill). + +### Sandbox shows as stopped + +The sandbox may have been stopped or deleted. +Run `nemoclaw onboard` to recreate the sandbox from the same blueprint and policy definitions. + +### Status shows "not running" inside the sandbox + +This is expected behavior. +When checking status inside an active sandbox, host-side sandbox state and inference configuration are not inspectable. +The status command detects the sandbox context and reports "active (inside sandbox)" instead. + +Run `openshell sandbox list` on the host to check the underlying sandbox state. + +### Inference requests time out + +Verify that the inference provider endpoint is reachable from the host. +Check the active provider and endpoint: + +```console +$ nemoclaw status +``` + +If the endpoint is correct but requests still fail, check for network policy rules that may block the connection. +Then verify the credential and base URL for the provider you selected during onboarding. + +### `NEMOCLAW_DISABLE_DEVICE_AUTH=1` does not change an existing sandbox + +This is expected behavior. +`NEMOCLAW_DISABLE_DEVICE_AUTH` is a build-time setting used when NemoClaw creates the sandbox image. +Changing or exporting it later does not rewrite the baked `openclaw.json` inside an existing sandbox. + +If you need a different device-auth setting, rerun onboarding so NemoClaw rebuilds the sandbox image with the desired configuration. +For the security trade-offs, refer to Security Best Practices (see the `nemoclaw-user-configure-security` skill). + +### Agent cannot reach an external host + +OpenShell blocks outbound connections to hosts not listed in the network policy. +Open the TUI to see blocked requests and approve them: + +```console +$ openshell term +``` + +To permanently allow an endpoint, add it to the network policy. +Refer to Customize the Network Policy (see the `nemoclaw-user-manage-policy` skill) for details. + +### Blueprint run failed + +View the error output for the failed blueprint run: + +```console +$ nemoclaw logs +``` + +Use `--follow` to stream logs in real time while debugging. + +## Podman + +### `open /dev/kmsg: operation not permitted` + +This error appears when the Podman machine is running in rootless mode. +K3s kubelet requires `/dev/kmsg` access for its OOM watcher, which is not available in rootless containers. + +Switch the Podman machine to rootful mode and restart: + +```console +$ podman machine stop +$ podman machine set --rootful +$ podman machine start +``` + +Then destroy and recreate the gateway: + +```console +$ openshell gateway destroy --name nemoclaw +$ nemoclaw onboard +``` + +### Image push timeout with Podman + +When creating a sandbox, the 1.5 GB sandbox image push into K3s may time out through Podman's API socket. +This is a known limitation of the bollard Docker client's default timeout. + +Manually push the image using the Docker CLI, which has no such timeout: + +```console +$ docker images --format '{{.Repository}}:{{.Tag}}' | grep sandbox-from +$ docker save | \ + docker exec -i openshell-cluster-nemoclaw \ + ctr -a /run/k3s/containerd/containerd.sock -n k8s.io images import - +``` + +After the import completes, create the sandbox manually: + +```console +$ openshell sandbox create --name my-assistant --from +``` + +### Podman machine resources + +The default Podman machine has 2 GB RAM, which is insufficient for the sandbox image push and K3s cluster overhead. +Allocate at least 8 GB RAM and 4 CPUs: + +```console +$ podman machine stop +$ podman machine set --cpus 6 --memory 8192 +$ podman machine start +``` diff --git a/.agents/skills/nemoclaw-user-workspace/SKILL.md b/.agents/skills/nemoclaw-user-workspace/SKILL.md new file mode 100644 index 000000000..626f59424 --- /dev/null +++ b/.agents/skills/nemoclaw-user-workspace/SKILL.md @@ -0,0 +1,169 @@ +--- +name: "nemoclaw-user-workspace" +description: "Backs up and restores OpenClaw workspace files before destructive operations. Use when backing up a sandbox, restoring workspace state, or preparing for a destructive operation. Explains what workspace files are, where they live, and how they persist across sandbox restarts. Use when asking about soul.md, identity.md, memory.md, agents.md, or sandbox file persistence." +--- + +# NemoClaw User Workspace + +Backs up and restores OpenClaw workspace files before destructive operations. Use when backing up a sandbox, restoring workspace state, or preparing for a destructive operation. + +## Context + +OpenClaw stores agent identity, behavior, and memory in a set of Markdown files inside the sandbox. +These files live at `/sandbox/.openclaw/workspace/` and are read by the agent at the start of every session. + +## File Reference + +Each file controls a distinct aspect of the agent's behavior and memory. + +| File | Purpose | Upstream Docs | +|---|---|---| +| `SOUL.md` | Core personality, tone, and behavioral rules. | [SOUL template](https://docs.openclaw.ai/reference/templates/SOUL) | +| `USER.md` | Preferences, context, and facts the agent learns about you. | [USER template](https://docs.openclaw.ai/reference/templates/USER) | +| `IDENTITY.md` | Agent name, creature type, emoji, and self-presentation. | [IDENTITY template](https://docs.openclaw.ai/reference/templates/IDENTITY) | +| `AGENTS.md` | Multi-agent coordination, memory conventions, and safety guidelines. | [AGENTS template](https://docs.openclaw.ai/reference/templates/AGENTS) | +| `MEMORY.md` | Curated long-term memory distilled from daily notes. | — | +| `memory/` | Directory of daily note files (`YYYY-MM-DD.md`) for session continuity. | — | + +## Where They Live + +All workspace files reside inside the sandbox filesystem: + +```text +/sandbox/.openclaw/workspace/ +├── AGENTS.md +├── IDENTITY.md +├── MEMORY.md +├── SOUL.md +├── USER.md +└── memory/ + ├── 2026-03-18.md + └── 2026-03-19.md +``` + +> **Note:** The workspace directory is hidden (`.openclaw`). +> The files are not at `/sandbox/SOUL.md`. Use the full path when downloading or uploading. + +## Persistence Behavior + +Understanding when these files persist and when they are lost is critical. + +| Event | Workspace files | +|---|---| +| Sandbox restart | **Preserved:** the sandbox PVC retains its data. | +| `nemoclaw destroy` | **Lost:** the sandbox and its PVC are deleted. | + +> **Warning:** Always back up your workspace files before running `nemoclaw destroy`. +> See Back Up and Restore (see the `nemoclaw-user-workspace` skill) for instructions. + +## Editing Workspace Files + +The agent reads these files at the start of every session. +You can edit them in two ways: + +1. **Let the agent do it:** Ask your agent to update its persona, memory, or user context during a session. +2. **Edit manually:** Use `openshell sandbox connect` to open a terminal inside the sandbox and edit files directly, or use `openshell sandbox upload` to push edited files from your host. + +## Prerequisites + +- A running NemoClaw sandbox (for backup) or a freshly created sandbox (for restore). +- The OpenShell CLI on your `PATH`. +- The sandbox name (shown by `nemoclaw list`). + +Workspace files define your agent's personality, memory, and user context. +They persist across sandbox restarts but are **permanently deleted** when you run `nemoclaw destroy`. + +This guide covers manual backup with CLI commands and an automated script. + +## Step 1: When to Back Up + +- Before running `nemoclaw destroy`. +- Before major NemoClaw version upgrades. +- Periodically, if you have invested time customizing your agent. + +## Step 2: Manual Backup + +Use `openshell sandbox download` to copy files from the sandbox to your host. + +```console +$ SANDBOX=my-assistant +$ BACKUP_DIR=~/.nemoclaw/backups/$(date +%Y%m%d-%H%M%S) +$ mkdir -p "$BACKUP_DIR" + +$ openshell sandbox download "$SANDBOX" /sandbox/.openclaw/workspace/SOUL.md "$BACKUP_DIR/" +$ openshell sandbox download "$SANDBOX" /sandbox/.openclaw/workspace/USER.md "$BACKUP_DIR/" +$ openshell sandbox download "$SANDBOX" /sandbox/.openclaw/workspace/IDENTITY.md "$BACKUP_DIR/" +$ openshell sandbox download "$SANDBOX" /sandbox/.openclaw/workspace/AGENTS.md "$BACKUP_DIR/" +$ openshell sandbox download "$SANDBOX" /sandbox/.openclaw/workspace/MEMORY.md "$BACKUP_DIR/" +$ openshell sandbox download "$SANDBOX" /sandbox/.openclaw/workspace/memory/ "$BACKUP_DIR/memory/" +``` + +## Step 3: Manual Restore + +Use `openshell sandbox upload` to push files back into a sandbox. + +```console +$ SANDBOX=my-assistant +$ BACKUP_DIR=~/.nemoclaw/backups/20260320-120000 # pick a timestamp + +$ openshell sandbox upload "$SANDBOX" "$BACKUP_DIR/SOUL.md" /sandbox/.openclaw/workspace/ +$ openshell sandbox upload "$SANDBOX" "$BACKUP_DIR/USER.md" /sandbox/.openclaw/workspace/ +$ openshell sandbox upload "$SANDBOX" "$BACKUP_DIR/IDENTITY.md" /sandbox/.openclaw/workspace/ +$ openshell sandbox upload "$SANDBOX" "$BACKUP_DIR/AGENTS.md" /sandbox/.openclaw/workspace/ +$ openshell sandbox upload "$SANDBOX" "$BACKUP_DIR/MEMORY.md" /sandbox/.openclaw/workspace/ +$ openshell sandbox upload "$SANDBOX" "$BACKUP_DIR/memory/" /sandbox/.openclaw/workspace/memory/ +``` + +## Step 4: Using the Backup Script + +The repository includes a convenience script at `scripts/backup-workspace.sh`. + +### Backup + +```console +$ ./scripts/backup-workspace.sh backup my-assistant +Backing up workspace from sandbox 'my-assistant'... +Backup saved to /home/user/.nemoclaw/backups/20260320-120000/ (6 items) +``` + +### Restore + +Restore from the most recent backup: + +```console +$ ./scripts/backup-workspace.sh restore my-assistant +``` + +Restore from a specific timestamp: + +```console +$ ./scripts/backup-workspace.sh restore my-assistant 20260320-120000 +``` + +## Step 5: Verifying a Backup + +List backed-up files to confirm completeness: + +```console +$ ls ~/.nemoclaw/backups/20260320-120000/ +AGENTS.md +IDENTITY.md +MEMORY.md +SOUL.md +USER.md +memory/ +``` + +## Step 6: Inspecting Files Inside the Sandbox + +Connect to the sandbox to list or view workspace files directly: + +```console +$ openshell sandbox connect my-assistant +$ ls -la /sandbox/.openclaw/workspace/ +``` + +## Related Skills + +- `nemoclaw-user-reference` — Commands reference +- `nemoclaw-user-monitor-sandbox` — Monitor Sandbox Activity diff --git a/.agents/skills/nemoclaw-user-workspace/references/workspace-files.md b/.agents/skills/nemoclaw-user-workspace/references/workspace-files.md new file mode 100644 index 000000000..3b874efb8 --- /dev/null +++ b/.agents/skills/nemoclaw-user-workspace/references/workspace-files.md @@ -0,0 +1,61 @@ +# Workspace Files + +OpenClaw stores agent identity, behavior, and memory in a set of Markdown files inside the sandbox. +These files live at `/sandbox/.openclaw/workspace/` and are read by the agent at the start of every session. + +## File Reference + +Each file controls a distinct aspect of the agent's behavior and memory. + +| File | Purpose | Upstream Docs | +|---|---|---| +| `SOUL.md` | Core personality, tone, and behavioral rules. | [SOUL template](https://docs.openclaw.ai/reference/templates/SOUL) | +| `USER.md` | Preferences, context, and facts the agent learns about you. | [USER template](https://docs.openclaw.ai/reference/templates/USER) | +| `IDENTITY.md` | Agent name, creature type, emoji, and self-presentation. | [IDENTITY template](https://docs.openclaw.ai/reference/templates/IDENTITY) | +| `AGENTS.md` | Multi-agent coordination, memory conventions, and safety guidelines. | [AGENTS template](https://docs.openclaw.ai/reference/templates/AGENTS) | +| `MEMORY.md` | Curated long-term memory distilled from daily notes. | — | +| `memory/` | Directory of daily note files (`YYYY-MM-DD.md`) for session continuity. | — | + +## Where They Live + +All workspace files reside inside the sandbox filesystem: + +```text +/sandbox/.openclaw/workspace/ +├── AGENTS.md +├── IDENTITY.md +├── MEMORY.md +├── SOUL.md +├── USER.md +└── memory/ + ├── 2026-03-18.md + └── 2026-03-19.md +``` + +> **Note:** The workspace directory is hidden (`.openclaw`). +> The files are not at `/sandbox/SOUL.md`. Use the full path when downloading or uploading. + +## Persistence Behavior + +Understanding when these files persist and when they are lost is critical. + +| Event | Workspace files | +|---|---| +| Sandbox restart | **Preserved:** the sandbox PVC retains its data. | +| `nemoclaw destroy` | **Lost:** the sandbox and its PVC are deleted. | + +> **Warning:** Always back up your workspace files before running `nemoclaw destroy`. +> See Back Up and Restore (see the `nemoclaw-user-workspace` skill) for instructions. + +## Editing Workspace Files + +The agent reads these files at the start of every session. +You can edit them in two ways: + +1. **Let the agent do it:** Ask your agent to update its persona, memory, or user context during a session. +2. **Edit manually:** Use `openshell sandbox connect` to open a terminal inside the sandbox and edit files directly, or use `openshell sandbox upload` to push edited files from your host. + +## Next Steps + +- Back Up and Restore workspace files (see the `nemoclaw-user-workspace` skill) +- Commands reference (see the `nemoclaw-user-reference` skill) diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index a9107f39e..878b273f2 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -37,7 +37,7 @@ ### Doc Changes -- [ ] Follows the [style guide](https://github.com/NVIDIA/NemoClaw/blob/main/docs/CONTRIBUTING.md). Try running the `update-docs` agent skill to draft changes while complying with the style guide. For example, prompt your agent with "`/update-docs` catch up the docs for the new changes I made in this PR." +- [ ] Follows the [style guide](https://github.com/NVIDIA/NemoClaw/blob/main/docs/CONTRIBUTING.md). Try running the `nemoclaw-contributor-update-docs` agent skill to draft changes while complying with the style guide. For example, prompt your agent with "`/nemoclaw-contributor-update-docs` catch up the docs for the new changes I made in this PR." - [ ] New pages include SPDX license header and frontmatter, if creating a new page. - [ ] Cross-references and links verified. diff --git a/AGENTS.md b/AGENTS.md index 9668357a5..7289ed531 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,20 +1,47 @@ -# AGENTS.md +# Agent Instructions -## Project Context +## Project Overview -NVIDIA NemoClaw runs OpenClaw AI assistants inside hardened OpenShell sandboxes with NVIDIA Nemotron inference. This file provides agent-specific guidance for working on this codebase. +NVIDIA NemoClaw is an open-source reference stack for running [OpenClaw](https://openclaw.ai) always-on assistants inside [NVIDIA OpenShell](https://github.com/NVIDIA/OpenShell) sandboxes more safely. It provides CLI tooling, a blueprint for sandbox orchestration, and security hardening. + +**Status:** Alpha (March 2026+). Interfaces may change without notice. + +## Agent Skills + +This repo ships agent skills under `.agents/skills/`, organized into three audience buckets: `nemoclaw-user-*` (end users), `nemoclaw-maintainer-*` (project maintainers), and `nemoclaw-contributor-*` (codebase contributors). Load the `nemoclaw-skills-guide` skill for a full catalog and quick decision guide mapping tasks to skills. + +## Architecture + +| Path | Language | Purpose | +|------|----------|---------| +| `bin/` | JavaScript (CJS) | CLI entry point (`nemoclaw.js`) and library modules | +| `bin/lib/` | JavaScript (CJS) | Core CLI logic: onboard, credentials, inference, policies, preflight, runner | +| `nemoclaw/` | TypeScript | Plugin project (Commander CLI extension for OpenClaw) | +| `nemoclaw/src/blueprint/` | TypeScript | Runner, snapshot, SSRF validation, state management | +| `nemoclaw/src/commands/` | TypeScript | Slash commands, migration state | +| `nemoclaw/src/onboard/` | TypeScript | Onboarding config | +| `nemoclaw-blueprint/` | YAML | Blueprint definition and network policies | +| `scripts/` | Bash/JS/TS | Install helpers, setup, automation, E2E tooling | +| `test/` | JavaScript (ESM) | Root-level integration tests (Vitest) | +| `test/e2e/` | Bash/JS | End-to-end tests (Brev cloud instances) | +| `docs/` | Markdown (MyST) | User-facing docs (Sphinx) | +| `k8s/` | YAML | Kubernetes deployment manifests | ## Quick Reference | Task | Command | |------|---------| | Install all deps | `npm install && cd nemoclaw && npm install && npm run build && cd .. && cd nemoclaw-blueprint && uv sync && cd ..` | +| Build plugin | `cd nemoclaw && npm run build` | +| Watch mode | `cd nemoclaw && npm run dev` | | Run all tests | `npm test` | | Run plugin tests | `cd nemoclaw && npm test` | | Run all linters | `make check` | +| Run all hooks manually | `npx prek run --all-files` | | Type-check CLI | `npm run typecheck:cli` | -| Build plugin | `cd nemoclaw && npm run build` | +| Auto-format | `make format` | | Build docs | `make docs` | +| Serve docs locally | `make docs-live` | ## Key Architecture Decisions @@ -53,6 +80,63 @@ NemoClaw isolates agents inside OpenShell sandboxes with: Security-sensitive code paths require extra test coverage. +## Code Style and Conventions + +### Commit Messages + +Conventional Commits required. Enforced by commitlint via prek `commit-msg` hook. + +```text +(): +``` + +Types: `feat`, `fix`, `docs`, `chore`, `refactor`, `test`, `ci`, `perf`, `merge` + +### SPDX Headers + +Every source file must include an SPDX license header. The pre-commit hook auto-inserts them: + +```javascript +// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +// SPDX-License-Identifier: Apache-2.0 +``` + +For shell scripts use `#` comments. For Markdown use HTML comments. + +### JavaScript + +- `bin/` and `scripts/`: **CommonJS** (`require`/`module.exports`), Node.js 22.16+ +- `test/`: **ESM** (`import`/`export`) +- ESLint config in `eslint.config.mjs` +- Cyclomatic complexity limit: 20 (ratcheting down to 15) +- Unused vars pattern: prefix with `_` + +### TypeScript + +- Plugin code in `nemoclaw/src/` with its own ESLint config +- CLI type-checking via `tsconfig.cli.json` +- Plugin type-checking via `nemoclaw/tsconfig.json` + +### Shell Scripts + +- ShellCheck enforced (`.shellcheckrc` at root) +- `shfmt` for formatting +- All scripts must have shebangs and be executable + +### No External Project Links + +Do not add links to third-party code repositories, community collections, or unofficial resources. Links to official tool documentation (Node.js, Python, uv) are acceptable. + +## Git Hooks (prek) + +All hooks managed by [prek](https://prek.j178.dev/) (installed via `npm install`): + +| Hook | What runs | +|------|-----------| +| **pre-commit** | File fixers, formatters, linters, Vitest (plugin) | +| **commit-msg** | commitlint (Conventional Commits) | +| **pre-push** | TypeScript type check (tsc --noEmit for plugin, JS, CLI) | + ## Working with This Repo ### Before Making Changes @@ -80,12 +164,6 @@ Security-sensitive code paths require extra test coverage. - Add YAML to `nemoclaw-blueprint/policies/presets/` - Follow existing preset structure (see `slack.yaml`, `discord.yaml`) -**Updating docs:** - -- Edit under `docs/` (never `.agents/skills/nemoclaw-*/*.md`) -- Regenerate skills: `python scripts/docs-to-skills.py docs/ .agents/skills/ --prefix nemoclaw` -- Preview: `make docs-live` - ### Gotchas - `npm install` at root triggers `prek install` which sets up git hooks. If hooks fail, check that `core.hooksPath` is unset: `git config --unset core.hooksPath` @@ -93,3 +171,24 @@ Security-sensitive code paths require extra test coverage. - SPDX headers are auto-inserted by pre-commit hooks; don't worry about adding them manually - Coverage thresholds are ratcheted in `ci/coverage-threshold-*.json` — new code should not decrease CLI or plugin coverage - The `.claude/skills` symlink points to `.agents/skills` — both paths resolve to the same content + +## Documentation + +- Source of truth: `docs/` directory +- `.agents/skills/nemoclaw-user-*/*.md` is **autogenerated** — never edit directly +- After changing docs, regenerate skills: + + ```bash + python3 scripts/docs-to-skills.py docs/ .agents/skills/ --prefix nemoclaw-user + ``` + +- Follow style guide in `docs/CONTRIBUTING.md` + +## PR Requirements + +- Create feature branch from `main` +- Run `make check` and `npm test` before submitting +- Follow PR template (`.github/PULL_REQUEST_TEMPLATE.md`) +- Update docs for any user-facing behavior changes +- No secrets, API keys, or credentials committed +- Limit open PRs to fewer than 10 diff --git a/CLAUDE.md b/CLAUDE.md deleted file mode 100644 index 1ed3ff8d8..000000000 --- a/CLAUDE.md +++ /dev/null @@ -1,139 +0,0 @@ -# CLAUDE.md - -## Project Overview - -NVIDIA NemoClaw is an open-source reference stack for running [OpenClaw](https://openclaw.ai) always-on assistants inside [NVIDIA OpenShell](https://github.com/NVIDIA/OpenShell) sandboxes with NVIDIA inference (Nemotron). It provides CLI tooling, a blueprint for sandbox orchestration, and security hardening. - -**Status:** Alpha (March 2026+). Interfaces may change without notice. - -## Architecture - -| Path | Language | Purpose | -|------|----------|---------| -| `bin/` | JavaScript (CJS) | CLI entry point (`nemoclaw.js`) and library modules | -| `bin/lib/` | JavaScript (CJS) | Core CLI logic: onboard, credentials, inference, policies, preflight, runner | -| `nemoclaw/` | TypeScript | Plugin project (Commander CLI extension for OpenClaw) | -| `nemoclaw/src/blueprint/` | TypeScript | Runner, snapshot, SSRF validation, state management | -| `nemoclaw/src/commands/` | TypeScript | Slash commands, migration state | -| `nemoclaw/src/onboard/` | TypeScript | Onboarding config | -| `nemoclaw-blueprint/` | YAML | Blueprint definition and network policies | -| `scripts/` | Bash/JS/TS | Install helpers, setup, automation, E2E tooling | -| `test/` | JavaScript (ESM) | Root-level integration tests (Vitest) | -| `test/e2e/` | Bash/JS | End-to-end tests (Brev cloud instances) | -| `docs/` | Markdown (MyST) | User-facing docs (Sphinx) | -| `k8s/` | YAML | Kubernetes deployment manifests | - -## Development Commands - -```bash -# Install dependencies -npm install # root deps (OpenClaw + CLI) -cd nemoclaw && npm install && npm run build && cd .. # TypeScript plugin -cd nemoclaw-blueprint && uv sync && cd .. # Python deps - -# Build -cd nemoclaw && npm run build # compile TypeScript plugin -cd nemoclaw && npm run dev # watch mode - -# Test -npm test # root-level tests (Vitest) -cd nemoclaw && npm test # plugin unit tests (Vitest) - -# Lint / check -make check # all linters via prek (pre-commit hooks) -npx prek run --all-files # same as make check -npm run typecheck:cli # type-check CLI (bin/, scripts/) - -# Format -make format # auto-format TypeScript - -# Docs -make docs # build docs (Sphinx/MyST) -make docs-live # serve locally with auto-rebuild -``` - -## Test Structure - -- **Root tests** (`test/*.test.js`): Integration tests run via Vitest (ESM) -- **Plugin tests** (`nemoclaw/src/**/*.test.ts`): Unit tests co-located with source -- **E2E tests** (`test/e2e/`): Cloud-based E2E on Brev instances, triggered only when `BREV_API_TOKEN` is set - -Vitest config (`vitest.config.ts`) defines three projects: `cli`, `plugin`, and `e2e-brev`. - -## Code Style and Conventions - -### Commit Messages - -Conventional Commits required. Enforced by commitlint via prek `commit-msg` hook. - -```text -(): -``` - -Types: `feat`, `fix`, `docs`, `chore`, `refactor`, `test`, `ci`, `perf`, `merge` - -### SPDX Headers - -Every source file must include an SPDX license header. The pre-commit hook auto-inserts them: - -```javascript -// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. -// SPDX-License-Identifier: Apache-2.0 -``` - -For shell scripts use `#` comments. For Markdown use HTML comments. - -### JavaScript - -- `bin/` and `scripts/`: **CommonJS** (`require`/`module.exports`), Node.js 22.16+ -- `test/`: **ESM** (`import`/`export`) -- ESLint config in `eslint.config.mjs` -- Cyclomatic complexity limit: 20 (ratcheting down to 15) -- Unused vars pattern: prefix with `_` - -### TypeScript - -- Plugin code in `nemoclaw/src/` with its own ESLint config -- CLI type-checking via `tsconfig.cli.json` -- Plugin type-checking via `nemoclaw/tsconfig.json` - -### Shell Scripts - -- ShellCheck enforced (`.shellcheckrc` at root) -- `shfmt` for formatting -- All scripts must have shebangs and be executable - -### No External Project Links - -Do not add links to third-party code repositories, community collections, or unofficial resources. Links to official tool documentation (Node.js, Python, uv) are acceptable. - -## Git Hooks (prek) - -All hooks managed by [prek](https://prek.j178.dev/) (installed via `npm install`): - -| Hook | What runs | -|------|-----------| -| **pre-commit** | File fixers, formatters, linters, Vitest (plugin) | -| **commit-msg** | commitlint (Conventional Commits) | -| **pre-push** | TypeScript type check (tsc --noEmit for plugin, JS, CLI) | - -## Documentation - -- Source of truth: `docs/` directory -- `.agents/skills/nemoclaw-*/*.md` is **autogenerated** — never edit directly -- After changing docs, regenerate skills: - - ```bash - python3 scripts/docs-to-skills.py docs/ .agents/skills/ --prefix nemoclaw - ``` - -- Follow style guide in `docs/CONTRIBUTING.md` - -## PR Requirements - -- Create feature branch from `main` -- Run `make check` and `npm test` before submitting -- Follow PR template (`.github/PULL_REQUEST_TEMPLATE.md`) -- Update docs for any user-facing behavior changes -- No secrets, API keys, or credentials committed -- Limit open PRs to fewer than 10 diff --git a/CLAUDE.md b/CLAUDE.md new file mode 120000 index 000000000..47dc3e3d8 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1 @@ +AGENTS.md \ No newline at end of file diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 4116933b2..9aaacfc99 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -108,7 +108,7 @@ Shell scripts (`scripts/*.sh`) must pass ShellCheck and use `shfmt` formatting. If your change affects user-facing behavior (new commands, changed defaults, new features, bug fixes that contradict existing docs), update the relevant pages under `docs/` in the same PR. -If you use an AI coding agent (Cursor, Claude Code, Codex, etc.), the repo includes the `/update-docs` skill that drafts doc updates. Use them before writing from scratch and follow the style guide in [docs/CONTRIBUTING.md](docs/CONTRIBUTING.md). +If you use an AI coding agent (Cursor, Claude Code, Codex, etc.), the repo includes the `nemoclaw-contributor-update-docs` skill that drafts doc updates. Use it before writing from scratch and follow the style guide in [docs/CONTRIBUTING.md](docs/CONTRIBUTING.md). To build and preview docs locally: @@ -126,22 +126,22 @@ The script `scripts/docs-to-skills.py` converts doc pages into agent skills unde These generated skills let AI agents answer user questions and walk through procedures without reading raw doc pages. Always edit pages in `docs/`. -Never edit generated skill files under `.agents/skills/nemoclaw-*/` — your changes will be overwritten on the next run. +Never edit generated skill files under `.agents/skills/nemoclaw-user-*/` — your changes will be overwritten on the next run. A pre-commit hook regenerates skills automatically whenever you commit changes to `docs/**/*.md` files. The hook runs `scripts/docs-to-skills.py` and stages the updated skills so they are included in the same commit. No manual step is needed for normal workflows. To regenerate skills manually (for example, after rebasing or outside of a commit), run from the repo root: ```bash -python scripts/docs-to-skills.py docs/ .agents/skills/ --prefix nemoclaw +python scripts/docs-to-skills.py docs/ .agents/skills/ --prefix nemoclaw-user ``` -Always use this exact output path (`.agents/skills/`) and prefix (`nemoclaw`) so skill names and locations stay consistent. +Always use this exact output path (`.agents/skills/`) and prefix (`nemoclaw-user`) so skill names and locations stay consistent. Preview what would change before writing files: ```bash -python scripts/docs-to-skills.py docs/ .agents/skills/ --prefix nemoclaw --dry-run +python scripts/docs-to-skills.py docs/ .agents/skills/ --prefix nemoclaw-user --dry-run ``` Other useful flags: diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index de38ba517..78ced5ade 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -14,14 +14,14 @@ Update documentation when your change: ## Update Docs with Agent Skills -If you use an AI coding agent (Cursor, Claude Code, Codex, etc.), the repo includes the `update-docs` skill that automates doc work. +If you use an AI coding agent (Cursor, Claude Code, Codex, etc.), the repo includes the `nemoclaw-contributor-update-docs` skill that automates doc work. Use it before writing from scratch. The skill scans recent commits for user-facing changes and drafts doc updates. Run it after landing features, before a release, or to find doc gaps. -For example, ask your agent to "catch up the docs for everything merged since v0.2.0". +For example, ask your agent to "catch up the docs for the changes I made in this PR". -The skill lives in `.agents/skills/update-docs/` and follows the style guide below automatically. +The skill lives in `.agents/skills/nemoclaw-contributor-update-docs/` and follows the style guide below automatically. ## Doc-to-Skills Pipeline @@ -30,7 +30,7 @@ The script `scripts/docs-to-skills.py` converts doc pages into agent skills unde These generated skills let AI agents walk users through NemoClaw tasks (installation, inference configuration, policy management, monitoring, and more) without reading raw doc pages. Always edit pages in `docs/`. -Never edit generated skill files under `.agents/skills/nemoclaw-*/`. Your changes will be overwritten on the next run. +Never edit generated skill files under `.agents/skills/nemoclaw-user-*/`. Your changes will be overwritten on the next run. ### Generated skills @@ -38,13 +38,13 @@ The current generated skills and their source pages are: | Skill | Source docs | |---|---| -| `nemoclaw-overview` | `docs/about/overview.md`, `docs/about/ecosystem.md`, `docs/about/how-it-works.md`, `docs/about/release-notes.md` | -| `nemoclaw-get-started` | `docs/get-started/quickstart.md` | -| `nemoclaw-configure-inference` | `docs/inference/inference-options.md`, `docs/inference/use-local-inference.md`, `docs/inference/switch-inference-providers.md` | -| `nemoclaw-manage-policy` | `docs/network-policy/customize-network-policy.md`, `docs/network-policy/approve-network-requests.md` | -| `nemoclaw-monitor-sandbox` | `docs/monitoring/monitor-sandbox-activity.md` | -| `nemoclaw-deploy-remote` | `docs/deployment/deploy-to-remote-gpu.md`, `docs/deployment/set-up-telegram-bridge.md` | -| `nemoclaw-reference` | `docs/reference/architecture.md`, `docs/reference/commands.md`, `docs/reference/network-policies.md`, `docs/reference/troubleshooting.md` | +| `nemoclaw-user-overview` | `docs/about/overview.md`, `docs/about/ecosystem.md`, `docs/about/how-it-works.md`, `docs/about/release-notes.md` | +| `nemoclaw-user-get-started` | `docs/get-started/quickstart.md` | +| `nemoclaw-user-configure-inference` | `docs/inference/inference-options.md`, `docs/inference/use-local-inference.md`, `docs/inference/switch-inference-providers.md` | +| `nemoclaw-user-manage-policy` | `docs/network-policy/customize-network-policy.md`, `docs/network-policy/approve-network-requests.md` | +| `nemoclaw-user-monitor-sandbox` | `docs/monitoring/monitor-sandbox-activity.md` | +| `nemoclaw-user-deploy-remote` | `docs/deployment/deploy-to-remote-gpu.md`, `docs/deployment/set-up-telegram-bridge.md` | +| `nemoclaw-user-reference` | `docs/reference/architecture.md`, `docs/reference/commands.md`, `docs/reference/network-policies.md`, `docs/reference/troubleshooting.md` | ### Regenerating skills after doc changes @@ -55,15 +55,15 @@ No manual step is needed for normal workflows. To regenerate skills manually (for example, after rebasing or outside of a commit), run from the repo root: ```bash -python scripts/docs-to-skills.py docs/ .agents/skills/ --prefix nemoclaw +python scripts/docs-to-skills.py docs/ .agents/skills/ --prefix nemoclaw-user ``` -Always use this exact output path (`.agents/skills/`) and prefix (`nemoclaw`) so skill names and locations stay consistent. +Always use this exact output path (`.agents/skills/`) and prefix (`nemoclaw-user`) so skill names and locations stay consistent. Preview what would change before writing files: ```bash -python scripts/docs-to-skills.py docs/ .agents/skills/ --prefix nemoclaw --dry-run +python scripts/docs-to-skills.py docs/ .agents/skills/ --prefix nemoclaw-user --dry-run ``` Other useful flags: diff --git a/scripts/docs-to-skills.py b/scripts/docs-to-skills.py index 1c49505f5..f3f95f450 100755 --- a/scripts/docs-to-skills.py +++ b/scripts/docs-to-skills.py @@ -11,7 +11,7 @@ Make sure to run this script using the following command to generate the skills and keep the locations and names consistent. ```bash -python3 scripts/docs-to-skills.py docs/ .agents/skills/ --prefix nemoclaw +python3 scripts/docs-to-skills.py docs/ .agents/skills/ --prefix nemoclaw-user ``` What it does: @@ -34,17 +34,17 @@ Naming: Use --prefix to keep skill names consistent across the project. The prefix - is prepended to every generated skill name (e.g. --prefix nemoclaw produces - nemoclaw-get-started, nemoclaw-manage-policy). Action verbs are derived + is prepended to every generated skill name (e.g. --prefix nemoclaw-user produces + nemoclaw-user-get-started, nemoclaw-user-manage-policy). Action verbs are derived automatically from page titles and content types. Use --name-map to override specific names when the heuristic doesn't produce the right result. Usage: - python3 scripts/docs-to-skills.py docs/ .agents/skills/ --prefix nemoclaw - python3 scripts/docs-to-skills.py docs/ .agents/skills/ --prefix nemoclaw --dry-run - python3 scripts/docs-to-skills.py docs/ .agents/skills/ --strategy individual --prefix nemoclaw - python3 scripts/docs-to-skills.py docs/ .agents/skills/ --prefix nemoclaw --name-map about=overview - python3 scripts/docs-to-skills.py docs/ .agents/skills/ --prefix nemoclaw --exclude "release-notes.md" + python3 scripts/docs-to-skills.py docs/ .agents/skills/ --prefix nemoclaw-user + python3 scripts/docs-to-skills.py docs/ .agents/skills/ --prefix nemoclaw-user --dry-run + python3 scripts/docs-to-skills.py docs/ .agents/skills/ --strategy individual --prefix nemoclaw-user + python3 scripts/docs-to-skills.py docs/ .agents/skills/ --prefix nemoclaw-user --name-map about=overview + python3 scripts/docs-to-skills.py docs/ .agents/skills/ --prefix nemoclaw-user --exclude "release-notes.md" """ from __future__ import annotations @@ -1194,10 +1194,10 @@ def main(): smart Group by directory, merge concept pages as context Examples: - %(prog)s docs/ .agents/skills/ --prefix nemoclaw - %(prog)s docs/ .agents/skills/ --strategy individual --prefix nemoclaw - %(prog)s docs/ .agents/skills/ --prefix nemoclaw --name-map about=overview - %(prog)s docs/ .agents/skills/ --prefix nemoclaw --dry-run + %(prog)s docs/ .agents/skills/ --prefix nemoclaw-user + %(prog)s docs/ .agents/skills/ --strategy individual --prefix nemoclaw-user + %(prog)s docs/ .agents/skills/ --prefix nemoclaw-user --name-map about=overview + %(prog)s docs/ .agents/skills/ --prefix nemoclaw-user --dry-run """), ) parser.add_argument(