diff --git a/.agents/skills/nemoclaw-user-configure-inference/SKILL.md b/.agents/skills/nemoclaw-user-configure-inference/SKILL.md index 8a5094cb320..fed9575e340 100644 --- a/.agents/skills/nemoclaw-user-configure-inference/SKILL.md +++ b/.agents/skills/nemoclaw-user-configure-inference/SKILL.md @@ -38,6 +38,7 @@ $ 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. +If the selected model declares that it does not support tool calling, onboarding stops with guidance to choose a model whose `ollama show ` capabilities include `tools`. On WSL, if you choose the Windows-host Ollama path, NemoClaw uses `host.docker.internal:11434` and pulls missing models through the Ollama HTTP API instead of requiring the `ollama` CLI inside WSL. ### WSL with Windows-Host Ollama @@ -56,9 +57,10 @@ If both WSL and Windows-host Ollama are running, pick the intended menu entry du ### Authenticated Reverse Proxy On non-WSL hosts, NemoClaw keeps Ollama bound to `127.0.0.1:11434` and starts a token-gated reverse proxy on `0.0.0.0:11435`. +The native install/start paths also reset NemoClaw-managed systemd launches to the loopback binding. Containers and other hosts on the local network reach Ollama only through the proxy, which validates a Bearer token before forwarding requests. -Ollama itself is never exposed without authentication. +On that native path, NemoClaw never exposes Ollama without authentication. WSL Ollama paths do not use this proxy. Windows-host Ollama uses the Windows daemon through `host.docker.internal`. diff --git a/.agents/skills/nemoclaw-user-configure-inference/references/inference-options.md b/.agents/skills/nemoclaw-user-configure-inference/references/inference-options.md index 73bb4db9812..4a1591824d8 100644 --- a/.agents/skills/nemoclaw-user-configure-inference/references/inference-options.md +++ b/.agents/skills/nemoclaw-user-configure-inference/references/inference-options.md @@ -49,6 +49,7 @@ Experimental local vLLM appears when you opt in and NemoClaw detects either a ru | 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 (use the `nemoclaw-user-configure-inference` skill). | +| Model Router | Starts a host-side router on port `4000`, registers it as an OpenAI-compatible provider, and keeps the sandbox pointed at `inference.local`. Set `NEMOCLAW_PROVIDER=routed` for non-interactive setup. | The router pool defines the model names. | ## Choosing the Right Option for Nemotron @@ -64,6 +65,20 @@ NVIDIA Nemotron models expose OpenAI-compatible APIs across every supported depl For Option 3, the API key environment variable is `COMPATIBLE_API_KEY`. Set it to whatever credential your endpoint expects, or any non-empty placeholder if your endpoint does not require auth. +## Model Router + +The Model Router option uses the `routed` inference profile in `nemoclaw-blueprint/blueprint.yaml`. +When you select it, NemoClaw starts the router proxy on the host, waits for its health endpoint, registers the `nvidia-router` provider with OpenShell, and creates the sandbox with the same `inference.local` route the agent uses for other providers. +The sandbox does not call the router port directly. + +The router model pool lives in `nemoclaw-blueprint/router/pool-config.yaml`. +The default pool routes between NVIDIA-hosted Nemotron models and uses the `tolerance` value to choose the lowest-cost model whose predicted quality stays within the configured threshold. +To use the router in scripted setup, set: + +```console +$ NEMOCLAW_PROVIDER=routed NVIDIA_API_KEY= nemoclaw onboard --non-interactive +``` + ## Experimental Options The following local inference options require `NEMOCLAW_EXPERIMENTAL=1` and, when prerequisites are met, appear in the onboarding selection list. @@ -79,6 +94,7 @@ For setup instructions, refer to Use a Local Inference Server (use the `nemoclaw NemoClaw validates the selected provider and model before creating the sandbox. If credential validation fails, the wizard asks whether to re-enter the API key, choose a different provider, retry, or exit. +Transient upstream validation failures are retried before the wizard reports a provider failure. The `nvapi-` prefix check applies only to `NVIDIA_API_KEY`. Other provider credentials, such as `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `GEMINI_API_KEY`, and compatible endpoint keys, use provider-aware validation during retry. diff --git a/.agents/skills/nemoclaw-user-configure-inference/references/set-up-sub-agent.md b/.agents/skills/nemoclaw-user-configure-inference/references/set-up-sub-agent.md index ec73667338f..c88799775ae 100644 --- a/.agents/skills/nemoclaw-user-configure-inference/references/set-up-sub-agent.md +++ b/.agents/skills/nemoclaw-user-configure-inference/references/set-up-sub-agent.md @@ -15,7 +15,7 @@ When adapting an OpenClaw sub-agent setup, use these paths inside the sandbox: | Path | Purpose | |---|---| | `/sandbox/.openclaw/openclaw.json` | OpenClaw config, including `models.providers`, `agents.defaults`, and `agents.list`. | -| `/sandbox/.openclaw/.config-hash` | Hash for `openclaw.json`. Keep it in sync after manual config edits; it becomes a startup-enforced trust anchor only after `shields up` locks it root-owned and read-only. | +| `/sandbox/.openclaw/.config-hash` | Hash for `openclaw.json`. Keep it in sync after manual config edits; it becomes a startup-enforced trust anchor only after the file is root-owned and read-only. | | `/sandbox/.openclaw/agents//agent/auth-profiles.json` | Per-agent provider credentials. Use this when a sub-agent calls an auxiliary provider directly. | | `/sandbox/.openclaw/workspace/` | Writable shared workspace path for files the primary agent passes to the sub-agent. | | `/tmp/gateway.log` | OpenClaw gateway log. Use it to confirm config reloads and diagnose sub-agent failures. | @@ -54,7 +54,7 @@ Create `/tmp/openclaw.updated.json` with the OpenClaw sub-agent config. For the Omni example, the demo provides `vlm-demo/vlm-subagent/openclaw-patch.py`. Upload the patched config and refresh the hash. -In the default mutable state, this keeps the local hash consistent but does not make it tamper-proof; run `nemoclaw shields up` afterward if the sandbox should enforce config integrity at startup. +In the default mutable state, this keeps the local hash consistent but does not make it tamper-proof; lock the config root-owned and read-only afterward if the sandbox should enforce config integrity at startup. ```console $ docker exec "$DOCKER_CTR" kubectl exec -n openshell "$SANDBOX" -c agent -- chmod 644 /sandbox/.openclaw/openclaw.json diff --git a/.agents/skills/nemoclaw-user-configure-security/references/best-practices.md b/.agents/skills/nemoclaw-user-configure-security/references/best-practices.md index a8429a4d5a9..ae4aa6e80b5 100644 --- a/.agents/skills/nemoclaw-user-configure-security/references/best-practices.md +++ b/.agents/skills/nemoclaw-user-configure-security/references/best-practices.md @@ -181,6 +181,7 @@ NemoClaw ships preset policy files in `nemoclaw-blueprint/policies/presets/` for | `github` | GitHub and GitHub REST API. | Gives agent read/write access to repositories and issues via `gh` and `git`. | | `huggingface` | Hugging Face Hub (download-only) and inference router. | Allows downloading arbitrary models and datasets. POST is restricted to the inference router only. | | `jira` | Atlassian Jira API. | Gives agent read/write access to project issues and comments. | +| `local-inference` | Local Ollama and vLLM through the host gateway. | Allows sandbox access to host-side local inference ports covered by the preset. | | `npm` | npm and Yarn registries via L4 pass-through. | Allows installing arbitrary npm packages, which may contain malicious code. OpenShell still gates by host, port, and binary, but does not inspect HTTP method, path, or body for this preset. | | `outlook` | Microsoft 365, Outlook. | Gives agent access to email. | | `pypi` | Python Package Index (GET and HEAD only). | Allows installing arbitrary Python packages, which may contain malicious code. Publishing is blocked. | @@ -216,19 +217,18 @@ In root mode, the gateway process still runs as the separate `gateway` user, but Writable agent state such as plugins, skills, hooks, and workspace metadata lives directly under `/sandbox/.openclaw`. By default, this directory starts writable so the agent can manage its own config, install skills, and write to standard home-directory paths natively. -Operators can opt into immutability by running `nemoclaw shields up`, which locks the config and writable state entry points until `shields down` restores the default writable state. +For sensitive workloads, use a reviewed host-side immutability workflow after initial setup so config and writable state entry points cannot be changed by the sandbox user. - **DAC permissions (default).** The sandbox user owns `/sandbox/.openclaw` with mode `700` and `openclaw.json` with mode `600`, so the agent can read and write config directly. -- **Config integrity hash.** The image includes a SHA256 hash of `openclaw.json`. In the default mutable state, `.config-hash` is sandbox-owned and is not a tamper-proof trust anchor, so startup does not fail closed on that hash. After `nemoclaw shields up` locks the hash root-owned and read-only, startup enforces it and refuses to start if the hash does not match. -- **Gateway token environment.** The gateway exports `OPENCLAW_GATEWAY_TOKEN` and writes it to `/tmp/nemoclaw-proxy-env.sh` for interactive sandbox sessions. Keep this in mind when deciding whether a workload should run with mutable config or with Shields UP. -- **Shields UP (opt-in).** `nemoclaw shields up` applies root-owned read-only permissions and best-effort immutable bits to sensitive config files, and locks writable state directories such as workspace, memory, skills, hooks, cron, agents, and extensions. +- **Config integrity hash.** The image includes a SHA256 hash of `openclaw.json`. In the default mutable state, `.config-hash` is sandbox-owned and is not a tamper-proof trust anchor, so startup does not fail closed on that hash. When the hash is root-owned and read-only, startup enforces it and refuses to start if the hash does not match. +- **Gateway token environment.** The gateway exports `OPENCLAW_GATEWAY_TOKEN` and writes it to `/tmp/nemoclaw-proxy-env.sh` for interactive sandbox sessions. Keep this in mind when deciding whether a workload should run with mutable config or an immutable config posture. | Aspect | Detail | |---|---| | Default | The sandbox keeps `/sandbox/.openclaw` writable (`700 sandbox:sandbox`), sets `openclaw.json` to `600 sandbox:sandbox`, lets the agent manage state directly, and has the gateway place `OPENCLAW_GATEWAY_TOKEN` in `/tmp/nemoclaw-proxy-env.sh` for interactive shells. | -| What you can change | Run `nemoclaw shields up` to lock config and state directories with DAC permissions and the immutable flag where available. Run `shields down` to return to the writable default. | +| What you can change | Apply a reviewed host-side immutability workflow to lock config and state directories with DAC permissions and the immutable flag where available. | | Risk of default | A writable `.openclaw` directory lets the agent modify its own gateway config: disabling CORS or redirecting inference to an attacker-controlled endpoint. | -| Recommendation | For always-on assistants handling sensitive workloads, use `shields up` to lock config after initial setup. For development workflows, the writable default is appropriate. | +| Recommendation | For always-on assistants handling sensitive workloads, lock config after initial setup. For development workflows, the writable default is appropriate. | ### Writable Paths @@ -516,7 +516,7 @@ The following patterns weaken security without providing meaningful benefit. | Omitting `protocol: rest` on REST API endpoints without a compatibility reason | Endpoints without a `protocol` field use L4-only enforcement. The proxy allows the TCP stream through after checking host, port, and binary, but cannot see or filter individual HTTP requests. | Add `protocol: rest` with explicit `rules` to enable per-request method and path control on REST APIs. Use L4 pass-through only for documented cases such as npm/Yarn on Node 22, where the client requires a CONNECT tunnel that L7 inspection would break. | | Adding endpoints to the baseline policy for one-off requests | Adding an endpoint to the baseline policy makes it permanently reachable across all sandbox instances. | Use operator approval. Approved endpoints persist within the sandbox instance but reset when you destroy and recreate the sandbox. | | Relying solely on the entrypoint for capability drops | The entrypoint drops dangerous capabilities using `capsh`, but this is best-effort. If `capsh` is unavailable or `CAP_SETPCAP` is not in the bounding set, the container runs with the default capability set. | Pass `--cap-drop=ALL` at the container runtime level as defense-in-depth. | -| Leaving `/sandbox/.openclaw` writable on sensitive workloads | This directory contains the OpenClaw gateway configuration. A writable `.openclaw` lets the agent disable CORS, redirect inference routing, or weaken gateway protections. | Run `nemoclaw shields up` to lock config for always-on assistants handling sensitive data. | +| Leaving `/sandbox/.openclaw` writable on sensitive workloads | This directory contains the OpenClaw gateway configuration. A writable `.openclaw` lets the agent disable CORS, redirect inference routing, or weaken gateway protections. | Lock config for always-on assistants handling sensitive data. | | Adding inference provider hosts to the network policy | Direct network access to an inference host bypasses credential isolation and usage tracking. | Use OpenShell inference routing instead of adding hosts like `api.openai.com` or `api.anthropic.com` to the network policy. | | Disabling device auth for remote deployments | Without device auth, any device on the network can connect to the gateway without pairing. Combined with a cloudflared tunnel, this makes the dashboard publicly accessible and unauthenticated. | Keep `NEMOCLAW_DISABLE_DEVICE_AUTH` at its default (`0`). Only set it to `1` for local headless or development environments. | diff --git a/.agents/skills/nemoclaw-user-deploy-remote/references/sandbox-hardening.md b/.agents/skills/nemoclaw-user-deploy-remote/references/sandbox-hardening.md index b8d6269b50b..10f149cbcfe 100644 --- a/.agents/skills/nemoclaw-user-deploy-remote/references/sandbox-hardening.md +++ b/.agents/skills/nemoclaw-user-deploy-remote/references/sandbox-hardening.md @@ -70,7 +70,7 @@ The agent's home directory (`/sandbox`) is writable by default: | Path | Access | Purpose | |------|--------|---------| | `/sandbox` | read-write | Home directory — agents can create files and use standard home paths | -| `/sandbox/.openclaw` | read-write | Agent config, state, workspace, plugins (lockable via `shields up`) | +| `/sandbox/.openclaw` | read-write | Agent config, state, workspace, plugins | | `/sandbox/.nemoclaw` | read-write | Plugin state and config; blueprints within are DAC-protected (root-owned) | | `/tmp` | read-write | Temporary files and logs | diff --git a/.agents/skills/nemoclaw-user-get-started/SKILL.md b/.agents/skills/nemoclaw-user-get-started/SKILL.md index f74db20f6b3..512f1981129 100644 --- a/.agents/skills/nemoclaw-user-get-started/SKILL.md +++ b/.agents/skills/nemoclaw-user-get-started/SKILL.md @@ -53,12 +53,14 @@ The inference provider prompt presents a numbered list. 5) Other Anthropic-compatible endpoint 6) Google Gemini 7) Local Ollama (localhost:11434) + 8) Model Router (complexity-based routing) Choose [1]: ``` Pick the option that matches where you want inference traffic to go, then expand the matching helper below for the follow-up prompts and the API key environment variable to set. For the full list of providers and validation behavior, refer to Inference Options (use the `nemoclaw-user-configure-inference` skill). Local Ollama appears when NemoClaw detects a usable local Ollama path or can offer an install or start action for your platform. +The Model Router option appears when the blueprint router profile is enabled. > **Tip:** Export the API key before launching the installer so the wizard does not have to ask for it. > For example, run `export NVIDIA_API_KEY=` before `curl ... | bash`. @@ -178,6 +180,31 @@ For setup details, including GPU recommendations and starter model choices, refe ::: +:::{dropdown} Option 8: Model Router +:icon: git-compare + +Starts a host-side model router and routes sandbox inference through OpenShell to that router. +The router chooses from the model pool in `nemoclaw-blueprint/router/pool-config.yaml` for each request. + +Use `NVIDIA_API_KEY` for the model pool credentials. + +Respond to the wizard as follows. + +1. At the `Choose [1]:` prompt, type `8` to select **Model Router (complexity-based routing)**. +2. At the `NVIDIA_API_KEY:` prompt, paste your key if it is not already exported. +3. Review the configuration summary and continue with the sandbox build. + +For scripted setup, set: + +```console +$ NEMOCLAW_PROVIDER=routed NVIDIA_API_KEY= nemoclaw onboard --non-interactive +``` + +The router listens on the host at port `4000`. +The sandbox still calls `https://inference.local/v1`, so do not point in-sandbox tools at the host router port directly. + +::: + :::{dropdown} Experimental: Local NIM and Local vLLM :icon: beaker @@ -235,6 +262,8 @@ The preset selector lets you include more destinations, such as GitHub, Jira, Sl Press `r` to toggle a selected preset between read-only and read-write when the preset supports both modes. When the install completes, a summary confirms the running environment. +Before printing the summary, NemoClaw verifies that the sandbox gateway and dashboard port forward are reachable. +Inference route and messaging bridge checks are reported as warnings when they need more time or additional configuration. The `Model` and provider line reflects the inference option you picked during onboarding. The example below shows the result if you picked an OpenAI-compatible endpoint during onboarding. @@ -251,7 +280,7 @@ Logs: nemoclaw my-gpt-claw logs --follow [INFO] === Installation complete === ``` -If you picked a different option, the `Model` line shows that provider's model and label instead. For example, you might see `gpt-5.4 (OpenAI)`, `claude-sonnet-4-6 (Anthropic)`, `gemini-2.5-flash (Google Gemini)`, `llama3.1:8b (Local Ollama)`, or ` (Other OpenAI-compatible endpoint)`. +If you picked a different option, the `Model` line shows that provider's model and label instead. For example, you might see `gpt-5.4 (OpenAI)`, `claude-sonnet-4-6 (Anthropic)`, `gemini-2.5-flash (Google Gemini)`, `llama3.1:8b (Local Ollama)`, `nvidia-routed (Model Router)`, or ` (Other OpenAI-compatible endpoint)`. ## Step 2: Run Your First Agent Prompt diff --git a/.agents/skills/nemoclaw-user-get-started/references/quickstart-hermes.md b/.agents/skills/nemoclaw-user-get-started/references/quickstart-hermes.md index 165bc19cfa1..62729769898 100644 --- a/.agents/skills/nemoclaw-user-get-started/references/quickstart-hermes.md +++ b/.agents/skills/nemoclaw-user-get-started/references/quickstart-hermes.md @@ -50,6 +50,8 @@ NemoClaw writes Hermes configuration into `/sandbox/.hermes`, routes model traff The Hermes image includes runtime dependencies for the supported NemoClaw messaging integrations, API service, and health endpoint. The base image does not include unsupported Hermes integrations. +> **Note:** Hermes uses an agent-specific baseline policy that allows the Hermes binary and Python runtime to reach the required Nous Research service endpoints, PyPI, NVIDIA inference endpoints, and selected messaging APIs. + ## Use Non-Interactive Setup For CI or scripted installs, set the required environment variables before running the installer. diff --git a/.agents/skills/nemoclaw-user-manage-policy/SKILL.md b/.agents/skills/nemoclaw-user-manage-policy/SKILL.md index b732b633dfd..0be9a81cae8 100644 --- a/.agents/skills/nemoclaw-user-manage-policy/SKILL.md +++ b/.agents/skills/nemoclaw-user-manage-policy/SKILL.md @@ -1,6 +1,6 @@ --- name: "nemoclaw-user-manage-policy" -description: "Adds, removes, or modifies allowed endpoints in the sandbox policy. Use when customizing network policy, changing egress rules, or configuring sandbox endpoint access. Trigger keywords - customize nemoclaw network policy, sandbox egress policy configuration, nemoclaw approve network requests, sandbox egress approval tui." +description: "Adds, removes, or modifies allowed endpoints in the sandbox policy. Use when customizing network policy, changing egress rules, or configuring sandbox endpoint access. Trigger keywords - customize nemoclaw network policy, sandbox egress policy configuration, nemoclaw integration policy examples, post-install policy setup, openshell approval workflow, policy preset, nemoclaw approve network requests, sandbox egress approval tui." --- @@ -157,6 +157,7 @@ This is useful when you want to test a destination before deciding whether it be 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. +For guided post-install examples, see Common Integration Policy Examples (use the `nemoclaw-user-manage-policy` skill). During onboarding, the policy tier (use the `nemoclaw-user-reference` skill) you select determines which presets are enabled by default. You can add or remove individual presets in the interactive preset screen that follows tier selection. @@ -171,6 +172,7 @@ Available presets: | `github` | GitHub and GitHub REST API | | `huggingface` | Hugging Face Hub (download-only) and inference router | | `jira` | Atlassian Jira API | +| `local-inference` | Local Ollama and vLLM through the host gateway | | `npm` | npm and Yarn registries | | `outlook` | Microsoft 365 and Outlook | | `pypi` | Python Package Index | @@ -278,6 +280,7 @@ $ nemoclaw my-assistant policy-remove my-internal-api --yes ## References +- **[references/integration-policy-examples.md](references/integration-policy-examples.md)** — Guides users through common post-install integration policy setup for maintained NemoClaw policy presets, including Outlook, messaging channels, GitHub, Jira, Brave Search, package managers, Hugging Face, local inference, and OpenShell approval workflows. - **Load [references/approve-network-requests.md](references/approve-network-requests.md)** when approving or denying sandbox egress requests, managing blocked network calls, or using the approval TUI. Reviews and approves blocked agent network requests in the TUI. ## Related Skills diff --git a/.agents/skills/nemoclaw-user-manage-policy/references/integration-policy-examples.md b/.agents/skills/nemoclaw-user-manage-policy/references/integration-policy-examples.md new file mode 100644 index 00000000000..02a3afc85b4 --- /dev/null +++ b/.agents/skills/nemoclaw-user-manage-policy/references/integration-policy-examples.md @@ -0,0 +1,259 @@ + + +# Common NemoClaw Integration Policy Examples + +Use these examples when a sandbox is already installed and an integration needs network access. +This page covers only integrations that NemoClaw currently ships as maintained policy preset YAML under `nemoclaw-blueprint/policies/presets/`. +Integration setup usually has two separate parts: + +- Configure the integration itself, such as a bot token, OAuth credential, or agent plugin setting. +- Allow the sandbox to reach the integration's network endpoints through NemoClaw and OpenShell policy. + +Prefer NemoClaw commands for policy changes that should be tracked with the sandbox. +Use OpenShell directly when you need to inspect blocked requests or approve a one-off request in the TUI. + +## Before You Start + +Replace `my-assistant` with your sandbox name in the examples. + +Check the current policy state first: + +```console +$ nemoclaw my-assistant policy-list +``` + +For a live view of blocked requests, open the OpenShell TUI in a separate host terminal: + +```console +$ openshell term +``` + +When the agent reaches an endpoint that is not in policy, the TUI shows the host, port, requesting binary, method, and path when available. +Approve a request only when you understand why the integration needs it. +An approval updates the running policy, but it does not create a NemoClaw preset entry that can be reviewed and replayed like `policy-add`. + +## Supported Integration Presets + +NemoClaw ships maintained policy presets for common services in `nemoclaw-blueprint/policies/presets/`. + +| Workflow | Preset | +|----------|--------| +| Brave Search | `brave` | +| Homebrew packages | `brew` | +| Discord messaging | `discord` | +| GitHub and GitHub API | `github` | +| Hugging Face Hub and Inference API | `huggingface` | +| Jira and Atlassian Cloud | `jira` | +| Local Ollama or vLLM through the host gateway | `local-inference` | +| npm and Yarn packages | `npm` | +| Microsoft 365, Outlook, and Graph API | `outlook` | +| Python Package Index | `pypi` | +| Slack messaging | `slack` | +| Telegram Bot API | `telegram` | + +Preview the endpoints before applying: + +```console +$ nemoclaw my-assistant policy-add outlook --dry-run +``` + +Apply the preset: + +```console +$ nemoclaw my-assistant policy-add outlook --yes +``` + +Remove it later if the sandbox no longer needs that access: + +```console +$ nemoclaw my-assistant policy-remove outlook --yes +``` + +## Email and Calendar With Microsoft 365 + +Use the `outlook` preset for Microsoft 365 email and calendar workflows that use Microsoft Graph or Outlook endpoints. +The preset allows `graph.microsoft.com`, Microsoft login, and Outlook service endpoints. + +```console +$ nemoclaw my-assistant policy-add outlook --dry-run +$ nemoclaw my-assistant policy-add outlook --yes +``` + +Then configure the email or calendar tool credentials through the integration you are running in the sandbox. +Keep OAuth client secrets and refresh tokens out of policy files. + +If the tool still fails, run `openshell term`, trigger the workflow again, and inspect the blocked request. +If the blocked endpoint is not covered by the maintained `outlook` preset, treat it as a separate policy review instead of assuming it is part of the supported preset. + +## Telegram Bot Messaging + +Telegram needs both channel configuration and egress policy. +If you already enabled Telegram during onboarding but did not include the preset, add it to the running sandbox: + +```console +$ nemoclaw my-assistant policy-add telegram --yes +``` + +To add Telegram after onboarding, set the token on the host, add the channel, rebuild so the image picks up the channel config, and make sure the policy preset is applied: + +```console +$ export TELEGRAM_BOT_TOKEN= +$ NEMOCLAW_NON_INTERACTIVE=1 nemoclaw my-assistant channels add telegram +$ nemoclaw my-assistant rebuild +$ nemoclaw my-assistant policy-add telegram --yes +``` + +If delivery fails, open the TUI and send a test message to the bot: + +```console +$ openshell term +``` + +The matching preset for each supported messaging channel is the channel name (`telegram`, `discord`, or `slack`). + +## Slack or Discord Messaging + +Slack and Discord also need both channel configuration and egress policy. +Use the matching policy preset after you configure the channel credentials. + +For Slack: + +```console +$ export SLACK_BOT_TOKEN= +$ export SLACK_APP_TOKEN= +$ NEMOCLAW_NON_INTERACTIVE=1 nemoclaw my-assistant channels add slack +$ nemoclaw my-assistant rebuild +$ nemoclaw my-assistant policy-add slack --yes +``` + +For Discord: + +```console +$ export DISCORD_BOT_TOKEN= +$ export DISCORD_SERVER_ID= +$ NEMOCLAW_NON_INTERACTIVE=1 nemoclaw my-assistant channels add discord +$ nemoclaw my-assistant rebuild +$ nemoclaw my-assistant policy-add discord --yes +``` + +If you enabled Slack or Discord during onboarding, apply only the matching preset: + +```console +$ nemoclaw my-assistant policy-add slack --yes +$ nemoclaw my-assistant policy-add discord --yes +``` + +## GitHub and Jira + +Use `github` when the agent needs GitHub API, Git, or `gh` access. +Use `jira` when the agent needs Atlassian Jira access. + +Preview first: + +```console +$ nemoclaw my-assistant policy-add github --dry-run +$ nemoclaw my-assistant policy-add jira --dry-run +``` + +Apply the preset that matches the workflow: + +```console +$ nemoclaw my-assistant policy-add github --yes +$ nemoclaw my-assistant policy-add jira --yes +``` + +Remove access when the task is done: + +```console +$ nemoclaw my-assistant policy-remove github --yes +$ nemoclaw my-assistant policy-remove jira --yes +``` + +## Brave Search + +The default Balanced policy tier includes `brave`. +If you chose Restricted during onboarding or removed the preset later, add it before enabling Brave Search workflows: + +```console +$ nemoclaw my-assistant policy-add brave --dry-run +$ nemoclaw my-assistant policy-add brave --yes +``` + +The Brave Search API key is still configured separately during onboarding or through the web search setup flow. + +## Package and Model Tooling + +Use these presets when an agent workflow installs packages or downloads model assets: + +| Workflow | Preset | +|----------|--------| +| npm or Yarn packages | `npm` | +| Python packages from PyPI | `pypi` | +| Homebrew packages | `brew` | +| Hugging Face model or dataset access | `huggingface` | + +Add only the preset required for the task: + +```console +$ nemoclaw my-assistant policy-add npm --yes +$ nemoclaw my-assistant policy-add pypi --yes +$ nemoclaw my-assistant policy-add brew --yes +$ nemoclaw my-assistant policy-add huggingface --yes +``` + +Remove package access after a one-time setup task if the sandbox no longer needs it: + +```console +$ nemoclaw my-assistant policy-remove npm --yes +$ nemoclaw my-assistant policy-remove pypi --yes +$ nemoclaw my-assistant policy-remove brew --yes +$ nemoclaw my-assistant policy-remove huggingface --yes +``` + +## Local Inference + +Use `local-inference` when the sandbox needs access to host-side local inference services such as Ollama or vLLM through the OpenShell host gateway. +Onboarding auto-suggests this preset when you choose a local provider. +If you need to add it after onboarding: + +```console +$ nemoclaw my-assistant policy-add local-inference --dry-run +$ nemoclaw my-assistant policy-add local-inference --yes +``` + +Then verify the sandbox status: + +```console +$ nemoclaw my-assistant status +``` + +## Inspect or Replace the Live Policy + +Use `policy-list` for normal preset state: + +```console +$ nemoclaw my-assistant policy-list +``` + +Use OpenShell when you need the full enforced YAML: + +```console +$ openshell policy get --full my-assistant > live-policy.yaml +``` + +If you must replace the live policy, edit the full policy file and set it back: + +```console +$ openshell policy set --policy live-policy.yaml my-assistant --wait +``` + +`openshell policy set` replaces the live policy with the file you provide. +It does not accept a preset file that starts with a `preset:` block, and it does not merge a single endpoint into the existing policy. +Use `nemoclaw my-assistant policy-add` for maintained NemoClaw presets. + +## Next Steps + +- Approve or Deny Agent Network Requests (use the `nemoclaw-user-manage-policy` skill) for the interactive OpenShell TUI flow. +- Customize the Sandbox Network Policy (use the `nemoclaw-user-manage-policy` skill) for static policy edits and raw OpenShell policy files. +- Messaging Channels (use the `nemoclaw-user-manage-sandboxes` skill) for Telegram, Discord, and Slack channel configuration. +- Commands (use the `nemoclaw-user-reference` skill) for the full `policy-add`, `policy-list`, `policy-remove`, and `channels` command reference. diff --git a/.agents/skills/nemoclaw-user-manage-sandboxes/references/messaging-channels.md b/.agents/skills/nemoclaw-user-manage-sandboxes/references/messaging-channels.md index 6cb63b9fc9d..a9f77addb6b 100644 --- a/.agents/skills/nemoclaw-user-manage-sandboxes/references/messaging-channels.md +++ b/.agents/skills/nemoclaw-user-manage-sandboxes/references/messaging-channels.md @@ -146,7 +146,7 @@ Stopping the in-sandbox gateway stops Telegram, Discord, and Slack polling for t After the sandbox is running, send a message to the configured bot or app. If delivery fails, use `openshell term` on the host, check gateway logs, and verify network policy allows the channel API. -Use the matching policy preset (`telegram`, `discord`, or `slack`) or review Customize the Network Policy (use the `nemoclaw-user-manage-policy` skill). +Use the matching policy preset (`telegram`, `discord`, or `slack`) or review Common Integration Policy Examples (use the `nemoclaw-user-manage-policy` skill). ## Tunnel Command diff --git a/.agents/skills/nemoclaw-user-overview/references/ecosystem.md b/.agents/skills/nemoclaw-user-overview/references/ecosystem.md index e499c6ad95c..2d7505f5993 100644 --- a/.agents/skills/nemoclaw-user-overview/references/ecosystem.md +++ b/.agents/skills/nemoclaw-user-overview/references/ecosystem.md @@ -66,7 +66,7 @@ The following table compares the two paths. | Sandbox isolation | Yes. OpenShell applies seccomp filters, Landlock filesystem restrictions, privilege dropping, network namespace isolation, and no-new-privileges enforcement. The community sandbox bundles its own policy tailored for OpenClaw. | Yes. NemoClaw applies these through the blueprint and layers a more restrictive policy on top (see rows below). | | Credential handling | OpenShell's provider system replaces real credentials with placeholder tokens in the sandbox environment. The L7 proxy resolves placeholders to real values at egress. You create providers manually with `openshell provider create`. | NemoClaw creates OpenShell providers automatically during onboarding. It also filters sensitive host environment variables (provider API keys, `DISCORD_BOT_TOKEN`, `SLACK_BOT_TOKEN`, `TELEGRAM_BOT_TOKEN`) from the sandbox creation command to prevent accidental leakage through build args. | | Image hardening | The community image includes standard system tools for general-purpose use. | NemoClaw strips build toolchains (`gcc`, `g++`, `make`) and network probes (`netcat`) from the runtime image to reduce attack surface. | -| Filesystem policy | The community sandbox bundles a policy for OpenClaw. | NemoClaw defines a targeted read-only and read-write layout. System paths (`/usr`, `/lib`, `/etc`) are read-only. The agent's home directory (`/sandbox`) and config directory (`/sandbox/.openclaw`) are writable by default so the agent can manage config, install skills, and write to standard paths natively. Operators can opt into config immutability with `nemoclaw shields up`. | +| Filesystem policy | The community sandbox bundles a policy for OpenClaw. | NemoClaw defines a targeted read-only and read-write layout. System paths (`/usr`, `/lib`, `/etc`) are read-only. The agent's home directory (`/sandbox`) and config directory (`/sandbox/.openclaw`) are writable by default so the agent can manage config, install skills, and write to standard paths natively. | | Inference setup | The community sandbox includes an `openclaw-start` script that runs OpenClaw's onboarding wizard inside the sandbox. You can also create providers and configure OpenShell inference routing manually from the host. | NemoClaw's onboarding wizard validates your credential from the host, lets you select a provider (NVIDIA Endpoints, OpenAI, Anthropic, Google Gemini, Ollama, and compatible endpoints), and configures OpenShell's inference routing automatically. Credentials stay on the host and are delivered through OpenShell's provider system. | | Channel messaging | OpenShell provides the credential provider system and L7 proxy that delivers channel tokens securely (including path-based resolution for Telegram's `/bot/` URL pattern). You create providers and configure OpenClaw's channel settings manually. | NemoClaw automates channel setup during onboarding: it collects bot tokens, registers them as OpenShell providers, and bakes OpenClaw channel config with placeholder tokens that OpenShell's proxy resolves at egress. No separate bridge process runs on the host. | | Blueprint versioning | No blueprint. The community sandbox uses whatever image version is currently published. | NemoClaw downloads the blueprint artifact, checks version compatibility, and verifies its digest before applying. Running `nemoclaw onboard` on different machines produces the same sandbox. | diff --git a/.agents/skills/nemoclaw-user-overview/references/how-it-works.md b/.agents/skills/nemoclaw-user-overview/references/how-it-works.md index bb29a2c2050..b4e9cc2e4e5 100644 --- a/.agents/skills/nemoclaw-user-overview/references/how-it-works.md +++ b/.agents/skills/nemoclaw-user-overview/references/how-it-works.md @@ -107,6 +107,7 @@ 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. +If you select the Model Router provider, `inference.local` routes to a host-side router that chooses from the configured NVIDIA model pool for each request. ## Protection Layers diff --git a/.agents/skills/nemoclaw-user-overview/references/overview.md b/.agents/skills/nemoclaw-user-overview/references/overview.md index eed4cf62ecb..087384fa79f 100644 --- a/.agents/skills/nemoclaw-user-overview/references/overview.md +++ b/.agents/skills/nemoclaw-user-overview/references/overview.md @@ -26,7 +26,7 @@ NemoClaw provides the following product capabilities. | 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. | +| Routed inference | Provider-routed model calls through the OpenShell gateway, transparent to the agent. Supports NVIDIA Endpoints, OpenAI, Anthropic, Google Gemini, compatible endpoints, local Ollama, local vLLM, and the Model Router. | | Layered protection | Network, filesystem, process, and inference controls that can be hot-reloaded or locked at creation. | ## Challenge diff --git a/.agents/skills/nemoclaw-user-reference/references/architecture.md b/.agents/skills/nemoclaw-user-reference/references/architecture.md index a015579027d..94958bcc928 100644 --- a/.agents/skills/nemoclaw-user-reference/references/architecture.md +++ b/.agents/skills/nemoclaw-user-reference/references/architecture.md @@ -20,7 +20,7 @@ graph LR USER(["👤 User"]):::user subgraph EXTERNAL["External Services"] - INFERENCE["Inference Provider
NVIDIA Endpoints · OpenAI
Anthropic · Ollama · vLLM"]:::external + INFERENCE["Inference Provider
NVIDIA Endpoints · OpenAI
Anthropic · Ollama · vLLM · Model Router"]:::external MSGAPI["Messaging Platforms
Telegram · Discord · Slack"]:::external INTERNET["Internet
PyPI · npm · GitHub · APIs"]:::external end @@ -106,7 +106,7 @@ graph TB end end - INFER["Inference provider
NVIDIA Endpoints · OpenAI
Anthropic · Ollama · vLLM"]:::external + INFER["Inference provider
NVIDIA Endpoints · OpenAI
Anthropic · Ollama · vLLM · Model Router"]:::external CLI -->|"openshell CLI
(orchestrates)"| GWCON AGENT -->|"inference requests
placeholder credentials"| PROXY @@ -175,6 +175,8 @@ The blueprint drives all interactions with the OpenShell CLI. ```text nemoclaw-blueprint/ ├── blueprint.yaml Manifest: version, profiles, compatibility +├── model-specific-setup/ Agent-scoped model/provider compatibility manifests +├── router/ Model Router config and routing engine ├── policies/ │ └── openclaw-sandbox.yaml Default network + filesystem policy ``` @@ -226,6 +228,12 @@ OpenShell intercepts them and routes to the configured provider: Agent (sandbox) ──▶ OpenShell gateway ──▶ NVIDIA Endpoint (build.nvidia.com) ``` +When you select the Model Router provider, the OpenShell gateway routes to a host-side router process instead of a single upstream model. +The router selects from the configured pool, then calls the upstream NVIDIA endpoint with the credential held outside the sandbox. + +Some model and provider combinations need agent-specific compatibility setup. +NemoClaw keeps those declarations under `nemoclaw-blueprint/model-specific-setup//` so OpenClaw and Hermes fixes can be tested and reviewed independently. + Refer to Inference Options (use the `nemoclaw-user-configure-inference` skill) for provider configuration details. ## Provider Credential Storage diff --git a/.agents/skills/nemoclaw-user-reference/references/commands.md b/.agents/skills/nemoclaw-user-reference/references/commands.md index 7c7f24725a1..bee135454e7 100644 --- a/.agents/skills/nemoclaw-user-reference/references/commands.md +++ b/.agents/skills/nemoclaw-user-reference/references/commands.md @@ -45,7 +45,7 @@ The wizard creates an OpenShell gateway, registers inference providers, builds t Use this command for new installs and for recreating a sandbox after changes to policy or configuration. ```console -$ nemoclaw onboard [--non-interactive] [--resume] [--recreate-sandbox] [--gpu | --no-gpu] [--from ] [--name ] [--agent ] [--control-ui-port ] [--yes-i-accept-third-party-software] +$ nemoclaw onboard [--non-interactive] [--resume | --fresh] [--recreate-sandbox] [--gpu | --no-gpu] [--from ] [--name ] [--agent ] [--control-ui-port ] [--yes-i-accept-third-party-software] ``` > **Warning:** For NemoClaw-managed environments, use `nemoclaw onboard` when you need to create or recreate the OpenShell gateway or sandbox. @@ -211,6 +211,7 @@ $ nemoclaw onboard --non-interactive --name my-build --from path/to/Dockerfile ``` The flag wins over `NEMOCLAW_SANDBOX_NAME`. +When prompting is possible, `NEMOCLAW_SANDBOX_NAME` fills the interactive default so you can press Enter to accept it. When prompting is impossible (no TTY or `--non-interactive`), the env var is also honoured so existing CI scripts keep working. Combining `--from ` with non-interactive onboarding requires one of `--name` or `NEMOCLAW_SANDBOX_NAME`; otherwise onboarding exits rather than silently defaulting to `my-assistant` and clobbering the default sandbox. @@ -314,6 +315,7 @@ Remote providers (NVIDIA Endpoints, OpenAI, Anthropic, Gemini) use a lightweight No API keys are sent. For cloud-only providers, the output omits the NIM status line unless a NIM container is registered or an unexpected NIM container is running. If the sandbox or gateway cannot be verified, the command exits non-zero instead of reporting healthy inference from stale registry state. +Gateway and dashboard health checks treat HTTP `401` from device auth as a live service, not as an offline gateway. A `Connected` line reports whether the sandbox has any active SSH sessions and, if so, how many. The sandbox list in the status output includes the dashboard port suffix for sandboxes with a recorded dashboard port. diff --git a/.agents/skills/nemoclaw-user-reference/references/network-policies.md b/.agents/skills/nemoclaw-user-reference/references/network-policies.md index 53fd0f935d3..f0eaf764d01 100644 --- a/.agents/skills/nemoclaw-user-reference/references/network-policies.md +++ b/.agents/skills/nemoclaw-user-reference/references/network-policies.md @@ -10,6 +10,8 @@ Any request to an unlisted destination is intercepted by OpenShell, and the oper The baseline policy is defined in `nemoclaw-blueprint/policies/openclaw-sandbox.yaml`. +> **Note:** Hermes sandboxes use an agent-specific baseline policy in `agents/hermes/policy-additions.yaml` so Hermes runtime binaries can reach the service endpoints they need while keeping the same deny-by-default model. + ### Filesystem | Path | Access | diff --git a/.agents/skills/nemoclaw-user-reference/references/troubleshooting.md b/.agents/skills/nemoclaw-user-reference/references/troubleshooting.md index 6bea6d7395b..ac1ae9091db 100644 --- a/.agents/skills/nemoclaw-user-reference/references/troubleshooting.md +++ b/.agents/skills/nemoclaw-user-reference/references/troubleshooting.md @@ -640,7 +640,7 @@ For advanced live edits, use the host-side config command instead of running `op $ nemoclaw config set --key --value '' --restart ``` -Host-side `config set` validates any HTTP or HTTPS URLs in the new value, including URLs nested inside JSON objects or arrays. NemoClaw rejects loopback, private, reserved, and internal hosts; DNS names must resolve successfully and must not resolve to private/internal addresses. HTTP URLs are written with the validated IP address pinned to reduce DNS-rebinding risk. Avoid putting credentials in config values; rotate provider credentials with `nemoclaw config rotate-token` instead. +Host-side `config set` validates any HTTP or HTTPS URLs in the new value, including URLs nested inside JSON objects or arrays. NemoClaw rejects loopback, private, reserved, and internal hosts; DNS names must resolve successfully and must not resolve to private/internal addresses. HTTP URLs are written with the validated IP address pinned to reduce DNS-rebinding risk. Avoid putting credentials in config values; rotate provider credentials with the credential-management commands instead. ### `openclaw doctor --fix` cannot repair Discord channel config inside the sandbox diff --git a/docs/about/ecosystem.md b/docs/about/ecosystem.md index a2f929f71b7..ad7ca6a50cb 100644 --- a/docs/about/ecosystem.md +++ b/docs/about/ecosystem.md @@ -86,7 +86,7 @@ The following table compares the two paths. | Sandbox isolation | Yes. OpenShell applies seccomp filters, Landlock filesystem restrictions, privilege dropping, network namespace isolation, and no-new-privileges enforcement. The community sandbox bundles its own policy tailored for OpenClaw. | Yes. NemoClaw applies these through the blueprint and layers a more restrictive policy on top (see rows below). | | Credential handling | OpenShell's provider system replaces real credentials with placeholder tokens in the sandbox environment. The L7 proxy resolves placeholders to real values at egress. You create providers manually with `openshell provider create`. | NemoClaw creates OpenShell providers automatically during onboarding. It also filters sensitive host environment variables (provider API keys, `DISCORD_BOT_TOKEN`, `SLACK_BOT_TOKEN`, `TELEGRAM_BOT_TOKEN`) from the sandbox creation command to prevent accidental leakage through build args. | | Image hardening | The community image includes standard system tools for general-purpose use. | NemoClaw strips build toolchains (`gcc`, `g++`, `make`) and network probes (`netcat`) from the runtime image to reduce attack surface. | -| Filesystem policy | The community sandbox bundles a policy for OpenClaw. | NemoClaw defines a targeted read-only and read-write layout. System paths (`/usr`, `/lib`, `/etc`) are read-only. The agent's home directory (`/sandbox`) and config directory (`/sandbox/.openclaw`) are writable by default so the agent can manage config, install skills, and write to standard paths natively. Operators can opt into config immutability with `nemoclaw shields up`. | +| Filesystem policy | The community sandbox bundles a policy for OpenClaw. | NemoClaw defines a targeted read-only and read-write layout. System paths (`/usr`, `/lib`, `/etc`) are read-only. The agent's home directory (`/sandbox`) and config directory (`/sandbox/.openclaw`) are writable by default so the agent can manage config, install skills, and write to standard paths natively. | | Inference setup | The community sandbox includes an `openclaw-start` script that runs OpenClaw's onboarding wizard inside the sandbox. You can also create providers and configure OpenShell inference routing manually from the host. | NemoClaw's onboarding wizard validates your credential from the host, lets you select a provider (NVIDIA Endpoints, OpenAI, Anthropic, Google Gemini, Ollama, and compatible endpoints), and configures OpenShell's inference routing automatically. Credentials stay on the host and are delivered through OpenShell's provider system. | | Channel messaging | OpenShell provides the credential provider system and L7 proxy that delivers channel tokens securely (including path-based resolution for Telegram's `/bot/` URL pattern). You create providers and configure OpenClaw's channel settings manually. | NemoClaw automates channel setup during onboarding: it collects bot tokens, registers them as OpenShell providers, and bakes OpenClaw channel config with placeholder tokens that OpenShell's proxy resolves at egress. No separate bridge process runs on the host. | | Blueprint versioning | No blueprint. The community sandbox uses whatever image version is currently published. | NemoClaw downloads the blueprint artifact, checks version compatibility, and verifies its digest before applying. Running `nemoclaw onboard` on different machines produces the same sandbox. | diff --git a/docs/about/how-it-works.md b/docs/about/how-it-works.md index 080c7544ec9..2870aa68777 100644 --- a/docs/about/how-it-works.md +++ b/docs/about/how-it-works.md @@ -127,6 +127,7 @@ 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. +If you select the Model Router provider, `inference.local` routes to a host-side router that chooses from the configured NVIDIA model pool for each request. ## Protection Layers diff --git a/docs/about/overview.md b/docs/about/overview.md index a2563064c9e..4b1482141ee 100644 --- a/docs/about/overview.md +++ b/docs/about/overview.md @@ -46,7 +46,7 @@ NemoClaw provides the following product capabilities. | 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. | +| Routed inference | Provider-routed model calls through the OpenShell gateway, transparent to the agent. Supports NVIDIA Endpoints, OpenAI, Anthropic, Google Gemini, compatible endpoints, local Ollama, local vLLM, and the Model Router. | | Layered protection | Network, filesystem, process, and inference controls that can be hot-reloaded or locked at creation. | ## Challenge diff --git a/docs/deployment/sandbox-hardening.md b/docs/deployment/sandbox-hardening.md index c45faa6ba7a..7d1bfbfb5a4 100644 --- a/docs/deployment/sandbox-hardening.md +++ b/docs/deployment/sandbox-hardening.md @@ -90,7 +90,7 @@ The agent's home directory (`/sandbox`) is writable by default: | Path | Access | Purpose | |------|--------|---------| | `/sandbox` | read-write | Home directory — agents can create files and use standard home paths | -| `/sandbox/.openclaw` | read-write | Agent config, state, workspace, plugins (lockable via `shields up`) | +| `/sandbox/.openclaw` | read-write | Agent config, state, workspace, plugins | | `/sandbox/.nemoclaw` | read-write | Plugin state and config; blueprints within are DAC-protected (root-owned) | | `/tmp` | read-write | Temporary files and logs | diff --git a/docs/get-started/quickstart-hermes.md b/docs/get-started/quickstart-hermes.md index 5949fc0a739..7e4f074998f 100644 --- a/docs/get-started/quickstart-hermes.md +++ b/docs/get-started/quickstart-hermes.md @@ -74,6 +74,10 @@ NemoClaw writes Hermes configuration into `/sandbox/.hermes`, routes model traff The Hermes image includes runtime dependencies for the supported NemoClaw messaging integrations, API service, and health endpoint. The base image does not include unsupported Hermes integrations. +:::{note} +Hermes uses an agent-specific baseline policy that allows the Hermes binary and Python runtime to reach the required Nous Research service endpoints, PyPI, NVIDIA inference endpoints, and selected messaging APIs. +::: + ## Use Non-Interactive Setup For CI or scripted installs, set the required environment variables before running the installer. diff --git a/docs/get-started/quickstart.md b/docs/get-started/quickstart.md index b593978af43..f70b3abd4f2 100644 --- a/docs/get-started/quickstart.md +++ b/docs/get-started/quickstart.md @@ -75,12 +75,14 @@ The inference provider prompt presents a numbered list. 5) Other Anthropic-compatible endpoint 6) Google Gemini 7) Local Ollama (localhost:11434) + 8) Model Router (complexity-based routing) Choose [1]: ``` Pick the option that matches where you want inference traffic to go, then expand the matching helper below for the follow-up prompts and the API key environment variable to set. For the full list of providers and validation behavior, refer to [Inference Options](../inference/inference-options.md). Local Ollama appears when NemoClaw detects a usable local Ollama path or can offer an install or start action for your platform. +The Model Router option appears when the blueprint router profile is enabled. :::{tip} Export the API key before launching the installer so the wizard does not have to ask for it. @@ -206,6 +208,31 @@ For setup details, including GPU recommendations and starter model choices, refe ::: +:::{dropdown} Option 8: Model Router +:icon: git-compare + +Starts a host-side model router and routes sandbox inference through OpenShell to that router. +The router chooses from the model pool in `nemoclaw-blueprint/router/pool-config.yaml` for each request. + +Use `NVIDIA_API_KEY` for the model pool credentials. + +Respond to the wizard as follows. + +1. At the `Choose [1]:` prompt, type `8` to select **Model Router (complexity-based routing)**. +2. At the `NVIDIA_API_KEY:` prompt, paste your key if it is not already exported. +3. Review the configuration summary and continue with the sandbox build. + +For scripted setup, set: + +```console +$ NEMOCLAW_PROVIDER=routed NVIDIA_API_KEY= nemoclaw onboard --non-interactive +``` + +The router listens on the host at port `4000`. +The sandbox still calls `https://inference.local/v1`, so do not point in-sandbox tools at the host router port directly. + +::: + :::{dropdown} Experimental: Local NIM and Local vLLM :icon: beaker @@ -263,6 +290,8 @@ The preset selector lets you include more destinations, such as GitHub, Jira, Sl Press `r` to toggle a selected preset between read-only and read-write when the preset supports both modes. When the install completes, a summary confirms the running environment. +Before printing the summary, NemoClaw verifies that the sandbox gateway and dashboard port forward are reachable. +Inference route and messaging bridge checks are reported as warnings when they need more time or additional configuration. The `Model` and provider line reflects the inference option you picked during onboarding. The example below shows the result if you picked an OpenAI-compatible endpoint during onboarding. @@ -279,7 +308,7 @@ Logs: nemoclaw my-gpt-claw logs --follow [INFO] === Installation complete === ``` -If you picked a different option, the `Model` line shows that provider's model and label instead. For example, you might see `gpt-5.4 (OpenAI)`, `claude-sonnet-4-6 (Anthropic)`, `gemini-2.5-flash (Google Gemini)`, `llama3.1:8b (Local Ollama)`, or ` (Other OpenAI-compatible endpoint)`. +If you picked a different option, the `Model` line shows that provider's model and label instead. For example, you might see `gpt-5.4 (OpenAI)`, `claude-sonnet-4-6 (Anthropic)`, `gemini-2.5-flash (Google Gemini)`, `llama3.1:8b (Local Ollama)`, `nvidia-routed (Model Router)`, or ` (Other OpenAI-compatible endpoint)`. ## Run Your First Agent Prompt diff --git a/docs/inference/inference-options.md b/docs/inference/inference-options.md index 0f86de8282c..9fdf757acca 100644 --- a/docs/inference/inference-options.md +++ b/docs/inference/inference-options.md @@ -69,6 +69,7 @@ Experimental local vLLM appears when you opt in and NemoClaw detects either a ru | 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](use-local-inference.md). | +| Model Router | Starts a host-side router on port `4000`, registers it as an OpenAI-compatible provider, and keeps the sandbox pointed at `inference.local`. Set `NEMOCLAW_PROVIDER=routed` for non-interactive setup. | The router pool defines the model names. | ## Choosing the Right Option for Nemotron @@ -84,6 +85,20 @@ NVIDIA Nemotron models expose OpenAI-compatible APIs across every supported depl For Option 3, the API key environment variable is `COMPATIBLE_API_KEY`. Set it to whatever credential your endpoint expects, or any non-empty placeholder if your endpoint does not require auth. +## Model Router + +The Model Router option uses the `routed` inference profile in `nemoclaw-blueprint/blueprint.yaml`. +When you select it, NemoClaw starts the router proxy on the host, waits for its health endpoint, registers the `nvidia-router` provider with OpenShell, and creates the sandbox with the same `inference.local` route the agent uses for other providers. +The sandbox does not call the router port directly. + +The router model pool lives in `nemoclaw-blueprint/router/pool-config.yaml`. +The default pool routes between NVIDIA-hosted Nemotron models and uses the `tolerance` value to choose the lowest-cost model whose predicted quality stays within the configured threshold. +To use the router in scripted setup, set: + +```console +$ NEMOCLAW_PROVIDER=routed NVIDIA_API_KEY= nemoclaw onboard --non-interactive +``` + ## Experimental Options The following local inference options require `NEMOCLAW_EXPERIMENTAL=1` and, when prerequisites are met, appear in the onboarding selection list. @@ -99,6 +114,7 @@ For setup instructions, refer to [Use a Local Inference Server](use-local-infere NemoClaw validates the selected provider and model before creating the sandbox. If credential validation fails, the wizard asks whether to re-enter the API key, choose a different provider, retry, or exit. +Transient upstream validation failures are retried before the wizard reports a provider failure. The `nvapi-` prefix check applies only to `NVIDIA_API_KEY`. Other provider credentials, such as `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `GEMINI_API_KEY`, and compatible endpoint keys, use provider-aware validation during retry. diff --git a/docs/inference/set-up-sub-agent.md b/docs/inference/set-up-sub-agent.md index f6413f5ba9b..9c0876ae770 100644 --- a/docs/inference/set-up-sub-agent.md +++ b/docs/inference/set-up-sub-agent.md @@ -37,7 +37,7 @@ When adapting an OpenClaw sub-agent setup, use these paths inside the sandbox: | Path | Purpose | |---|---| | `/sandbox/.openclaw/openclaw.json` | OpenClaw config, including `models.providers`, `agents.defaults`, and `agents.list`. | -| `/sandbox/.openclaw/.config-hash` | Hash for `openclaw.json`. Keep it in sync after manual config edits; it becomes a startup-enforced trust anchor only after `shields up` locks it root-owned and read-only. | +| `/sandbox/.openclaw/.config-hash` | Hash for `openclaw.json`. Keep it in sync after manual config edits; it becomes a startup-enforced trust anchor only after the file is root-owned and read-only. | | `/sandbox/.openclaw/agents//agent/auth-profiles.json` | Per-agent provider credentials. Use this when a sub-agent calls an auxiliary provider directly. | | `/sandbox/.openclaw/workspace/` | Writable shared workspace path for files the primary agent passes to the sub-agent. | | `/tmp/gateway.log` | OpenClaw gateway log. Use it to confirm config reloads and diagnose sub-agent failures. | @@ -76,7 +76,7 @@ Create `/tmp/openclaw.updated.json` with the OpenClaw sub-agent config. For the Omni example, the demo provides `vlm-demo/vlm-subagent/openclaw-patch.py`. Upload the patched config and refresh the hash. -In the default mutable state, this keeps the local hash consistent but does not make it tamper-proof; run `nemoclaw shields up` afterward if the sandbox should enforce config integrity at startup. +In the default mutable state, this keeps the local hash consistent but does not make it tamper-proof; lock the config root-owned and read-only afterward if the sandbox should enforce config integrity at startup. ```console $ docker exec "$DOCKER_CTR" kubectl exec -n openshell "$SANDBOX" -c agent -- chmod 644 /sandbox/.openclaw/openclaw.json diff --git a/docs/inference/use-local-inference.md b/docs/inference/use-local-inference.md index 3eae942a61d..426218ac25b 100644 --- a/docs/inference/use-local-inference.md +++ b/docs/inference/use-local-inference.md @@ -55,6 +55,7 @@ $ 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. +If the selected model declares that it does not support tool calling, onboarding stops with guidance to choose a model whose `ollama show ` capabilities include `tools`. On WSL, if you choose the Windows-host Ollama path, NemoClaw uses `host.docker.internal:11434` and pulls missing models through the Ollama HTTP API instead of requiring the `ollama` CLI inside WSL. ### WSL with Windows-Host Ollama diff --git a/docs/project.json b/docs/project.json index 1293e3033de..1bf89f19eaf 100644 --- a/docs/project.json +++ b/docs/project.json @@ -1 +1 @@ -{"name": "nemoclaw", "version": "0.0.35"} +{"name": "nemoclaw", "version": "0.0.36"} diff --git a/docs/reference/architecture.md b/docs/reference/architecture.md index 19b497c6e0e..ff0136946fd 100644 --- a/docs/reference/architecture.md +++ b/docs/reference/architecture.md @@ -40,7 +40,7 @@ graph LR USER(["👤 User"]):::user subgraph EXTERNAL["External Services"] - INFERENCE["Inference Provider
NVIDIA Endpoints · OpenAI
Anthropic · Ollama · vLLM"]:::external + INFERENCE["Inference Provider
NVIDIA Endpoints · OpenAI
Anthropic · Ollama · vLLM · Model Router"]:::external MSGAPI["Messaging Platforms
Telegram · Discord · Slack"]:::external INTERNET["Internet
PyPI · npm · GitHub · APIs"]:::external end @@ -126,7 +126,7 @@ graph TB end end - INFER["Inference provider
NVIDIA Endpoints · OpenAI
Anthropic · Ollama · vLLM"]:::external + INFER["Inference provider
NVIDIA Endpoints · OpenAI
Anthropic · Ollama · vLLM · Model Router"]:::external CLI -->|"openshell CLI
(orchestrates)"| GWCON AGENT -->|"inference requests
placeholder credentials"| PROXY @@ -195,6 +195,8 @@ The blueprint drives all interactions with the OpenShell CLI. ```text nemoclaw-blueprint/ ├── blueprint.yaml Manifest: version, profiles, compatibility +├── model-specific-setup/ Agent-scoped model/provider compatibility manifests +├── router/ Model Router config and routing engine ├── policies/ │ └── openclaw-sandbox.yaml Default network + filesystem policy ``` @@ -246,6 +248,12 @@ OpenShell intercepts them and routes to the configured provider: Agent (sandbox) ──▶ OpenShell gateway ──▶ NVIDIA Endpoint (build.nvidia.com) ``` +When you select the Model Router provider, the OpenShell gateway routes to a host-side router process instead of a single upstream model. +The router selects from the configured pool, then calls the upstream NVIDIA endpoint with the credential held outside the sandbox. + +Some model and provider combinations need agent-specific compatibility setup. +NemoClaw keeps those declarations under `nemoclaw-blueprint/model-specific-setup//` so OpenClaw and Hermes fixes can be tested and reviewed independently. + Refer to [Inference Options](../inference/inference-options.md) for provider configuration details. ## Provider Credential Storage diff --git a/docs/reference/commands.md b/docs/reference/commands.md index 1ace4533c88..825f81f92ce 100644 --- a/docs/reference/commands.md +++ b/docs/reference/commands.md @@ -233,6 +233,7 @@ $ nemoclaw onboard --non-interactive --name my-build --from path/to/Dockerfile ``` The flag wins over `NEMOCLAW_SANDBOX_NAME`. +When prompting is possible, `NEMOCLAW_SANDBOX_NAME` fills the interactive default so you can press Enter to accept it. When prompting is impossible (no TTY or `--non-interactive`), the env var is also honoured so existing CI scripts keep working. Combining `--from ` with non-interactive onboarding requires one of `--name` or `NEMOCLAW_SANDBOX_NAME`; otherwise onboarding exits rather than silently defaulting to `my-assistant` and clobbering the default sandbox. @@ -338,6 +339,7 @@ Remote providers (NVIDIA Endpoints, OpenAI, Anthropic, Gemini) use a lightweight No API keys are sent. For cloud-only providers, the output omits the NIM status line unless a NIM container is registered or an unexpected NIM container is running. If the sandbox or gateway cannot be verified, the command exits non-zero instead of reporting healthy inference from stale registry state. +Gateway and dashboard health checks treat HTTP `401` from device auth as a live service, not as an offline gateway. A `Connected` line reports whether the sandbox has any active SSH sessions and, if so, how many. The sandbox list in the status output includes the dashboard port suffix for sandboxes with a recorded dashboard port. diff --git a/docs/reference/network-policies.md b/docs/reference/network-policies.md index 0824f145aab..da8d43be365 100644 --- a/docs/reference/network-policies.md +++ b/docs/reference/network-policies.md @@ -30,6 +30,10 @@ Any request to an unlisted destination is intercepted by OpenShell, and the oper The baseline policy is defined in `nemoclaw-blueprint/policies/openclaw-sandbox.yaml`. +:::{note} +Hermes sandboxes use an agent-specific baseline policy in `agents/hermes/policy-additions.yaml` so Hermes runtime binaries can reach the service endpoints they need while keeping the same deny-by-default model. +::: + ### Filesystem | Path | Access | diff --git a/docs/reference/troubleshooting.md b/docs/reference/troubleshooting.md index cec2a60f132..65a150609d0 100644 --- a/docs/reference/troubleshooting.md +++ b/docs/reference/troubleshooting.md @@ -670,7 +670,7 @@ For advanced live edits, use the host-side config command instead of running `op $ nemoclaw config set --key --value '' --restart ``` -Host-side `config set` validates any HTTP or HTTPS URLs in the new value, including URLs nested inside JSON objects or arrays. NemoClaw rejects loopback, private, reserved, and internal hosts; DNS names must resolve successfully and must not resolve to private/internal addresses. HTTP URLs are written with the validated IP address pinned to reduce DNS-rebinding risk. Avoid putting credentials in config values; rotate provider credentials with `nemoclaw config rotate-token` instead. +Host-side `config set` validates any HTTP or HTTPS URLs in the new value, including URLs nested inside JSON objects or arrays. NemoClaw rejects loopback, private, reserved, and internal hosts; DNS names must resolve successfully and must not resolve to private/internal addresses. HTTP URLs are written with the validated IP address pinned to reduce DNS-rebinding risk. Avoid putting credentials in config values; rotate provider credentials with the credential-management commands instead. ### `openclaw doctor --fix` cannot repair Discord channel config inside the sandbox diff --git a/docs/security/best-practices.md b/docs/security/best-practices.md index 823a9e243b3..8952b1deeee 100644 --- a/docs/security/best-practices.md +++ b/docs/security/best-practices.md @@ -237,19 +237,18 @@ In root mode, the gateway process still runs as the separate `gateway` user, but Writable agent state such as plugins, skills, hooks, and workspace metadata lives directly under `/sandbox/.openclaw`. By default, this directory starts writable so the agent can manage its own config, install skills, and write to standard home-directory paths natively. -Operators can opt into immutability by running `nemoclaw shields up`, which locks the config and writable state entry points until `shields down` restores the default writable state. +For sensitive workloads, use a reviewed host-side immutability workflow after initial setup so config and writable state entry points cannot be changed by the sandbox user. - **DAC permissions (default).** The sandbox user owns `/sandbox/.openclaw` with mode `700` and `openclaw.json` with mode `600`, so the agent can read and write config directly. -- **Config integrity hash.** The image includes a SHA256 hash of `openclaw.json`. In the default mutable state, `.config-hash` is sandbox-owned and is not a tamper-proof trust anchor, so startup does not fail closed on that hash. After `nemoclaw shields up` locks the hash root-owned and read-only, startup enforces it and refuses to start if the hash does not match. -- **Gateway token environment.** The gateway exports `OPENCLAW_GATEWAY_TOKEN` and writes it to `/tmp/nemoclaw-proxy-env.sh` for interactive sandbox sessions. Keep this in mind when deciding whether a workload should run with mutable config or with Shields UP. -- **Shields UP (opt-in).** `nemoclaw shields up` applies root-owned read-only permissions and best-effort immutable bits to sensitive config files, and locks writable state directories such as workspace, memory, skills, hooks, cron, agents, and extensions. +- **Config integrity hash.** The image includes a SHA256 hash of `openclaw.json`. In the default mutable state, `.config-hash` is sandbox-owned and is not a tamper-proof trust anchor, so startup does not fail closed on that hash. When the hash is root-owned and read-only, startup enforces it and refuses to start if the hash does not match. +- **Gateway token environment.** The gateway exports `OPENCLAW_GATEWAY_TOKEN` and writes it to `/tmp/nemoclaw-proxy-env.sh` for interactive sandbox sessions. Keep this in mind when deciding whether a workload should run with mutable config or an immutable config posture. | Aspect | Detail | |---|---| | Default | The sandbox keeps `/sandbox/.openclaw` writable (`700 sandbox:sandbox`), sets `openclaw.json` to `600 sandbox:sandbox`, lets the agent manage state directly, and has the gateway place `OPENCLAW_GATEWAY_TOKEN` in `/tmp/nemoclaw-proxy-env.sh` for interactive shells. | -| What you can change | Run `nemoclaw shields up` to lock config and state directories with DAC permissions and the immutable flag where available. Run `shields down` to return to the writable default. | +| What you can change | Apply a reviewed host-side immutability workflow to lock config and state directories with DAC permissions and the immutable flag where available. | | Risk of default | A writable `.openclaw` directory lets the agent modify its own gateway config: disabling CORS or redirecting inference to an attacker-controlled endpoint. | -| Recommendation | For always-on assistants handling sensitive workloads, use `shields up` to lock config after initial setup. For development workflows, the writable default is appropriate. | +| Recommendation | For always-on assistants handling sensitive workloads, lock config after initial setup. For development workflows, the writable default is appropriate. | ### Writable Paths @@ -537,7 +536,7 @@ The following patterns weaken security without providing meaningful benefit. | Omitting `protocol: rest` on REST API endpoints without a compatibility reason | Endpoints without a `protocol` field use L4-only enforcement. The proxy allows the TCP stream through after checking host, port, and binary, but cannot see or filter individual HTTP requests. | Add `protocol: rest` with explicit `rules` to enable per-request method and path control on REST APIs. Use L4 pass-through only for documented cases such as npm/Yarn on Node 22, where the client requires a CONNECT tunnel that L7 inspection would break. | | Adding endpoints to the baseline policy for one-off requests | Adding an endpoint to the baseline policy makes it permanently reachable across all sandbox instances. | Use operator approval. Approved endpoints persist within the sandbox instance but reset when you destroy and recreate the sandbox. | | Relying solely on the entrypoint for capability drops | The entrypoint drops dangerous capabilities using `capsh`, but this is best-effort. If `capsh` is unavailable or `CAP_SETPCAP` is not in the bounding set, the container runs with the default capability set. | Pass `--cap-drop=ALL` at the container runtime level as defense-in-depth. | -| Leaving `/sandbox/.openclaw` writable on sensitive workloads | This directory contains the OpenClaw gateway configuration. A writable `.openclaw` lets the agent disable CORS, redirect inference routing, or weaken gateway protections. | Run `nemoclaw shields up` to lock config for always-on assistants handling sensitive data. | +| Leaving `/sandbox/.openclaw` writable on sensitive workloads | This directory contains the OpenClaw gateway configuration. A writable `.openclaw` lets the agent disable CORS, redirect inference routing, or weaken gateway protections. | Lock config for always-on assistants handling sensitive data. | | Adding inference provider hosts to the network policy | Direct network access to an inference host bypasses credential isolation and usage tracking. | Use OpenShell inference routing instead of adding hosts like `api.openai.com` or `api.anthropic.com` to the network policy. | | Disabling device auth for remote deployments | Without device auth, any device on the network can connect to the gateway without pairing. Combined with a cloudflared tunnel, this makes the dashboard publicly accessible and unauthenticated. | Keep `NEMOCLAW_DISABLE_DEVICE_AUTH` at its default (`0`). Only set it to `1` for local headless or development environments. | diff --git a/docs/versions1.json b/docs/versions1.json index 9cc79138964..ee12d5eda37 100644 --- a/docs/versions1.json +++ b/docs/versions1.json @@ -1,6 +1,10 @@ [ { "preferred": true, + "version": "0.0.36", + "url": "https://docs.nvidia.com/nemoclaw/0.0.36/" + }, + { "version": "0.0.35", "url": "https://docs.nvidia.com/nemoclaw/0.0.35/" },