kenaug74/NemoClaw
1
0
Fork 0
mirror of https://github.com/NVIDIA/NemoClaw.git synced 2026-07-03 03:37:16 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 135

chore: retire docs-to-skills and make single compact user skill (#5699)

Browse source 
<!-- markdownlint-disable MD041 -->
## Summary
This PR retires the generated docs-to-skills pipeline and replaces the
expanded generated user skill catalog with one compact
`nemoclaw-user-guide` skill. The guide routes AI agents to canonical
NemoClaw documentation through the docs MCP server, `llms.txt`, and
variant-specific Markdown pages while keeping contributor and maintainer
skills intact.

## Changes
- Remove `scripts/docs-to-skills.py`, the generated
`.agents/skills/nemoclaw-user-*` trees, generated root
`skills/nemoclaw-user-*` exports, and generated catalog metadata.
- Add `nemoclaw-user-guide` as the single customer-facing user skill
under `.agents/skills/`, with matching evals and a hard-copy root
`skills/nemoclaw-user-guide` catalog publication copy.
- Refresh the root catalog copy through NVSkills signing and document
the hard-copy catalog refresh flow.
- Update the AI Agent Docs page with the starter prompt button, the
NemoClaw docs MCP server URL, Claude Code/Cursor setup guidance,
`llms.txt`, and specific `.md` docs routes without the deprecated
`llms-full.txt` path.
- Update agent guides, contributor docs, PR/issue guidance, catalog
signing notes, and CI/static checks to reference Markdown/MCP docs
routing instead of generated user-skill refreshes.
- Retarget the skill frontmatter test to validate checked-in `SKILL.md`
files, guard the single root `skills/` catalog surface, and verify the
catalog copy matches the `.agents/skills/nemoclaw-user-guide` source
files while allowing NVSkills signing artifacts.

## Type of Change

- [ ] Code change (feature, bug fix, or refactor)
- [x] Code change with doc updates
- [ ] Doc only (prose changes, no code sample modifications)
- [ ] Doc only (includes code sample changes)

## Verification
<!-- Check each item you ran and confirmed. Leave unchecked items you
skipped. Doc-only changes do not require npm test unless you ran it. -->
- [ ] PR description includes the DCO sign-off declaration and every
commit appears as `Verified` in GitHub
- [x] Git hooks passed during commit and push, or `npx prek run
--from-ref main --to-ref HEAD` passes
- [x] Targeted tests pass for changed behavior
- [ ] Full `npm test` passes (broad runtime changes only)
- [x] Tests added or updated for new or changed behavior
- [x] No secrets, API keys, or credentials committed
- [x] Docs updated for user-facing behavior changes
- [ ] `npm run docs` builds without warnings (doc changes only)
- [x] Doc pages follow the [style
guide](https://github.com/NVIDIA/NemoClaw/blob/main/docs/CONTRIBUTING.md)
(doc changes only)
- [ ] New doc pages include SPDX header and frontmatter (new pages only)

---
<!-- DCO sign-off is required in this PR description, and every commit
must appear as Verified in GitHub. Run: git config user.name && git
config user.email -->
Signed-off-by: Miyoung Choi <miyoungc@nvidia.com>

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

* **New Features**
* Introduced `nemoclaw-user-guide` for consolidated AI-agent
documentation routing via an MCP docs server, with fallback to Markdown
indexing.
* **Documentation**
* Updated terminology from “Agent Skills” to “AI Agent Docs” across
user-facing materials.
* Refreshed docs refresh/release workflow and the Verified Skills
catalog publishing guidance.
* **Deprecations/Removals**
* Removed several user-focused skills and their related
documentation/evaluation content, consolidating guidance into the user
guide.
* **Refactor**
* Streamlined the workflow to prioritize canonical Markdown docs
sources.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

---------

Signed-off-by: nvskills-svc-account <svc-nvskills-signing@nvidia.com>
Co-authored-by: nvskills-svc-account <svc-nvskills-signing@nvidia.com>
This commit is contained in:
Miyoung Choi 2026-06-23 18:44:50 -07:00 • committed by GitHub
parent f07083eee3
commit 1aa03d6257
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
164 changed files with 493 additions and 25349 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
.agents/skills/nemoclaw-contributor-create-pr/SKILL.md
View file

@ -49,7 +49,7 @@ Use the checks that match the diff and the verification you already have.
If the commits were created normally and the branch was pushed normally, count the installed hooks as verification:
- `pre-commit` runs file fixers, formatters, linters, docs-to-skills dry-run validation, and changed-surface Vitest hooks.
- `pre-commit` runs file fixers, formatters, linters, skill frontmatter validation, and changed-surface Vitest hooks.
- `commit-msg` runs commitlint.
- `pre-push` runs TypeScript build and type-check gates.

25
.agents/skills/nemoclaw-contributor-update-docs/SKILL.md
View file

@ -1,6 +1,6 @@
---
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 and refresh generated user skills for release prep. Use when docs have fallen behind code changes, after a batch of features lands, during daily release prep, 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, release prep docs, refresh user skills.
description: Scan recent git commits for changes that affect user-facing behavior, then draft or update the corresponding documentation pages for release prep. Use when docs have fallen behind code changes, after a batch of features lands, during daily release prep, 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, release prep docs.
---
# Update Docs from Commits
@ -167,7 +167,7 @@ When updating an existing page:
- For each release-note bullet that corresponds to a deeper doc page, end the bullet with `For more information, refer to [DOC PAGE](/doc/path).`
- Link to the most specific existing page that explains the behavior, command, setup flow, or troubleshooting path.
- Do not add a link when no deeper page exists or when the only possible target is unrelated or too broad.
- Keep the source docs link as a normal MDX link. The docs-to-skills generator will convert it to the appropriate generated skill reference where needed.
- Keep the source docs link as a normal MDX link so Fern can publish both rendered and Markdown routes.
When creating a new page:
@ -203,15 +203,7 @@ Skip this step when the user only asked for ordinary doc catch-up and no release
If the user invoked this skill for release prep, finish the release-specific doc work before verification:
1. Determine the documented release version `n` from the user's request. For post-release documentation refreshes, label the PR with the next patch release label, not the documented release label. Release labels use `vX.Y.Z` format. For example, a docs refresh for release `0.0.63` uses label `v0.0.64`. Increment only the patch component; if the version is nonstandard or pre-release, ask before choosing a label. If the user did not provide a release version, ask for it before opening the release-prep PR.
2. Refresh the NemoClaw user skills:
```bash
python3 scripts/docs-to-skills.py docs/ .agents/skills/ --prefix nemoclaw-user --doc-platform fern-mdx
```
Do not include the root `skills/` directory as an output target. That
directory is refreshed by a separate process and must not be updated by this
skill.
2. Update `.agents/skills/nemoclaw-user-guide/SKILL.md` only if the release changes the AI-agent documentation entry points or routing guidance.
## Step 9: Build and Verify
@ -226,7 +218,7 @@ Check for:
- Build warnings or errors.
- Broken cross-references.
- Correct rendering of new content.
- Generated skill changes that do not correspond to source doc changes.
- Markdown documentation routes and navigation still match the changed source pages.
## Step 10: Open the Docs PR
@ -236,8 +228,9 @@ Commit changes and open a pull request with a concise summary of the doc updates
- #<doc-impacting-PR-number> -> `docs/path.mdx`: Description of the doc change reflecting the source code changes in the PR.
```
Apply the `area: docs`, `area: skills`, and next-patch release label so reviewers can identify doc-only changes for the next train and generated skill updates.
When creating the PR with `gh pr create`, pass all labels, for example a post-release docs refresh for `0.0.63` uses `--label "area: docs" --label "area: skills" --label v0.0.64`.
Apply the `area: docs` and next-patch release label so reviewers can identify doc-only changes for the next train.
Add `area: skills` only if the PR changes a file under `.agents/skills/`.
When creating the PR with `gh pr create`, pass the labels, for example a post-release docs refresh for `0.0.63` uses `--label "area: docs" --label v0.0.64`.
If the release label does not exist, report that instead of substituting another label.
Follow `nemoclaw-contributor-create-pr` for the PR mechanics, including [Git and GitHub Access Hard Stop](../_shared/git-github-hard-stop.md) and [PR CI and Automated Review Follow-Up](../_shared/pr-follow-up.md).
@ -261,10 +254,10 @@ User says: "Catch up the docs for everything merged since v0.1.0."
6. Draft doc updates reflecting the source code changes in the commits following the style guide.
7. **Release prep only:** Determine the next-patch release label from the user-requested documented release version.
For a post-release docs refresh for `0.0.63`, use label `v0.0.64`.
8. **Release prep only:** Run `python3 scripts/docs-to-skills.py docs/ .agents/skills/ --prefix nemoclaw-user --doc-platform fern-mdx`. Do not update root `skills/`.
8. **Release prep only:** Update `.agents/skills/nemoclaw-user-guide/SKILL.md` only if the AI-agent documentation entry points or routing guidance changed.
9. Present the summary.
10. Build with `npm run docs` to verify.
11. **Release prep only:** Commit changes and open a pull request with the `area: docs`, `area: skills`, and next-patch release label. Include a concise summary of the doc updates and a source summary that links each identified merged PR to its matching doc page. Include the PR number, affected doc page, links, and description of the doc change in this shape:
11. **Release prep only:** Commit changes and open a pull request with the `area: docs` and next-patch release label. Include `area: skills` only if the PR changes `.agents/skills/`. Include a concise summary of the doc updates and a source summary that links each identified merged PR to its matching doc page. Include the PR number, affected doc page, links, and description of the doc change in this shape:
```markdown
- #<doc-impacting-PR-number> -> `docs/path.mdx`: Description of the doc change reflecting the source code changes in the PR.

3
.agents/skills/nemoclaw-maintainer-day/SKILL.md
View file

@ -64,7 +64,8 @@ node --experimental-strip-types --no-warnings .agents/skills/nemoclaw-maintainer
## Commit Hygiene
The prek "Regenerate agent skills from docs" hook auto-stages `.agents/skills/` files. Before every `git add` and `git commit` on a PR branch, run `git reset HEAD .agents/skills/nemoclaw-maintainer-*` to unstage them. Only commit skill files in dedicated skill PRs.
Only commit skill files when the task intentionally changes agent guidance.
Keep unrelated `.agents/skills/` changes out of ordinary code or docs PRs.
## Stop and Ask When

23
.agents/skills/nemoclaw-skills-guide/SKILL.md
View file

@ -17,10 +17,10 @@ Load the specific skill you need after identifying it here.
Skills are grouped into three buckets by audience.
The prefix in each skill name indicates who it is for.
### `nemoclaw-user-*` (10 skills)
### `nemoclaw-user-*` (1 skill)
For end users operating a NemoClaw sandbox.
Covers installation, inference configuration, network policy management, monitoring, remote deployment, security configuration, workspace management, and reference material.
Covers routing human users' AI agents to the canonical NemoClaw Markdown documentation.
### `nemoclaw-maintainer-*` (13 skills)
@ -39,16 +39,7 @@ Covers creating pull requests that follow the project template, monitoring CI an
<!-- user-skills-table:begin -->
| 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-manage-sandboxes` | Manage day-two sandbox operations, including status, logs, diagnostics, rebuilds, upgrades, messaging channels, workspace files, backup, and restore. |
| `nemoclaw-user-reference` | CLI command reference, plugin and blueprint architecture, baseline network policies, and troubleshooting guide. |
| `nemoclaw-user-agent-skills` | Describes the agent skills shipped with NemoClaw and how to access them by cloning the repository. |
| `nemoclaw-user-guide` | Route human users' AI agents to `llms.txt` and the relevant NemoClaw Markdown docs for installation, configuration, operation, security, and troubleshooting. |
<!-- user-skills-table:end -->
### Maintainer Skills
@ -75,7 +66,7 @@ Covers creating pull requests that follow the project template, monitoring CI an
|-------|---------|
| `nemoclaw-contributor-create-pr` | Create GitHub pull requests that follow the NemoClaw PR template, including pre-PR checks, conventional commit titles, DCO sign-off, post-push CI monitoring, and CodeRabbit/PR Review Advisor follow-up. |
| `nemoclaw-contributor-onboard-messaging-channel` | Add or review a new messaging channel with manifest-first implementation, upstream source analysis, plugin install confirmation, reachability checks, policies, docs, and tests. |
| `nemoclaw-contributor-update-docs` | Scan recent git commits for user-facing changes, draft or update documentation pages, and refresh generated user skills during release prep. |
| `nemoclaw-contributor-update-docs` | Scan recent git commits for user-facing changes and draft or update documentation pages during release prep. |
## Getting Started
@ -89,8 +80,8 @@ Skills are cumulative. Each role includes the skills from the roles above it:
| Role | Skills included | Count | Start with |
|------|----------------|-------|------------|
| User | `nemoclaw-user-*` | 10 | `nemoclaw-user-get-started` |
| Contributor | `nemoclaw-user-*` + `nemoclaw-contributor-*` | 13 | `nemoclaw-user-overview` |
| Maintainer | All skills | 26 | `nemoclaw-maintainer-morning` |
| User | `nemoclaw-user-*` | 1 | `nemoclaw-user-guide` |
| Contributor | `nemoclaw-user-*` + `nemoclaw-contributor-*` | 4 | `nemoclaw-user-guide` |
| Maintainer | All skills | 17 | `nemoclaw-maintainer-morning` |
After identifying the role, present the applicable skills from the Skill Catalog above and recommend the starting skill.

89
.agents/skills/nemoclaw-user-agent-skills/SKILL.md
View file

@ -1,89 +0,0 @@
---
name: "nemoclaw-user-agent-skills"
description: "Describes the agent skills shipped with NemoClaw and how to access them by cloning the repository. Use when users ask about AI agent support, coding assistant integration, or the .agents/skills/ directory. Trigger keywords - nemoclaw agent skills, ai coding assistant, cursor, claude code, copilot."
license: "Apache-2.0"
---
# NemoClaw Agent Skills for Your AI Coding Assistant
NemoClaw ships agent skills that are generated directly from this documentation.
Each skill is a converted version of one or more doc pages, structured so AI coding assistants can consume it as context.
This means you can interact with the full NemoClaw documentation as skills inside your agent chat session, instead of reading the docs separately.
Ask your assistant a question about NemoClaw and it responds with the same guidance found in these docs, adapted to your current situation.
Skills cover installation, inference configuration, network policy management, monitoring, deployment, security, workspace management, and the CLI reference.
**Note:**
If you are a contributor and have cloned the full NemoClaw repository, the full set of skills including contributor and maintainer skills are already available at the project root.
Open the `NemoClaw` directory in your coding assistant and the skills load automatically.
This page is for users who installed NemoClaw with the installer and do not have a local clone.
## Get the Skills
Fetch only the skills from the NemoClaw repository without downloading the full source tree.
```bash
git clone --filter=blob:none --no-checkout https://github.com/NVIDIA/NemoClaw.git
cd NemoClaw
git sparse-checkout set --no-cone '/.agents/skills/nemoclaw-user-*/**' '/.agents/skills/nemoclaw-skills-guide/**' '/.claude/**' '/AGENTS.md' '/CLAUDE.md'
git checkout
```
Open the `NemoClaw` directory in your AI coding assistant.
The assistant discovers the skills in `.agents/skills/` and uses them to answer NemoClaw questions with project-specific guidance.
You can keep the skills inside the cloned directory or copy `.agents/skills/` to a global location (such as `~/.cursor/skills/` or `~/.claude/skills/`) so they are available across all your projects.
The choice depends on whether you want NemoClaw skills scoped to one workspace or accessible everywhere.
## Update the Skills
The sparse checkout filter is saved, so `git pull` fetches only updated skills without downloading the full source tree.
Run `git pull` after each NemoClaw release to pick up new and updated skills.
## Available Skills
The following user skills ship with NemoClaw.
| Skill | Summary |
|-------|---------|
| `nemoclaw-user-overview` | What NemoClaw is, ecosystem placement (OpenClaw + OpenShell + NemoClaw), how it works internally, and release notes. |
| `nemoclaw-user-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-manage-sandboxes` | Manage day-two sandbox operations, including status, logs, diagnostics, rebuilds, upgrades, messaging channels, workspace files, backup, and restore. |
| `nemoclaw-user-reference` | CLI command reference, plugin and blueprint architecture, baseline network policies, and troubleshooting guide. |
## Example Questions and Triggered Skills
After opening the cloned repository in your coding assistant, ask a NemoClaw question in natural language.
The assistant matches your question to the relevant skill and follows the guidance it contains.
Examples of questions your assistant can answer with these skills:
| Question | Skill triggered |
|----------|-----------------|
| "How do I install NemoClaw?" | `nemoclaw-user-get-started` |
| "Switch my inference provider to Ollama." | `nemoclaw-user-configure-inference` |
| "A network request was blocked. How do I approve it?" | `nemoclaw-user-manage-policy` |
| "Show me the sandbox logs." | `nemoclaw-user-monitor-sandbox` |
| "How do I deploy NemoClaw to a remote GPU?" | `nemoclaw-user-deploy-remote` |
| "What security controls can I configure?" | `nemoclaw-user-configure-security` |
| "Back up my agent workspace files." | `nemoclaw-user-manage-sandboxes` |
| "What CLI commands are available?" | `nemoclaw-user-reference` |
You can also reference a skill directly by name if you know which one you need.
## AI Coding Assistants that You Can Use with NemoClaw Skills
The NemoClaw agent skills follow the [Agent Skills best practices](https://agentskills.io/skill-creation/best-practices) and the [Claude Skills best practices](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices).
The following table shows how each AI coding assistant can use the NemoClaw skills.
| Assistant | Skill discovery |
|-----------|----------------|
| Cursor | Reads `AGENTS.md` at the project root, which references `.agents/skills/`. |
| Claude Code | Follows the `.claude/skills/` symlink, which points to `.agents/skills/`. |
| Other assistants | Point the assistant to `.agents/skills/` if it supports project-level skill loading. |

11
.agents/skills/nemoclaw-user-agent-skills/evals/evals.json
View file

@ -1,11 +0,0 @@
[
{
"id": "docs-resources-agent-skills-001",
"question": "I'm looking at NemoClaw agent skills. Help me find a skill that can guide installation, policy, inference, or operations so I can delegate the right workflow to my AI coding assistant.",
"expected_skill": "nemoclaw-user-agent-skills",
"ground_truth": "A NemoClaw-specific answer that helps the user find a skill that can guide installation, policy, inference, or operations and gives enough concrete guidance, decision criteria, verification steps, or risk framing to delegate the right workflow to my AI coding assistant.",
"expected_behavior": [
"Uses the expected_skill and does not make up answers if it cannot find the answer from the skill."
]
}
]

257
.agents/skills/nemoclaw-user-configure-inference/SKILL.md
View file

@ -1,257 +0,0 @@
---
name: "nemoclaw-user-configure-inference"
description: "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. Trigger keywords - nemoclaw local inference, ollama nemoclaw, vllm nemoclaw, local model server, openai compatible endpoint, switch nemoclaw inference model, change inference runtime, nemoclaw additional model, nemoclaw sub-agent model, openclaw sub-agent, agents.list, sessions_spawn, vlm-demo, nemoclaw inference options, nemoclaw onboarding providers, nemoclaw inference routing, nemoclaw tool calling, ollama tool calls, vllm tool-call-parser, raw json in tui."
license: "Apache-2.0"
---
# Use a Local Inference Server
## Gotchas
- Ollama is convenient for local chat, but some model/template combinations can return tool calls as plain text under realistic agent load.
## Prerequisites
<AgentOnly variant="openclaw">
- NemoClaw installed. Refer to the Quickstart (use the `nemoclaw-user-get-started` skill) if you have not installed yet.
- NemoClaw installed. Refer to Quickstart with Hermes (use the `nemoclaw-user-get-started` skill) if you have not installed yet.
- A local model server running, or a supported Ollama, vLLM, or NIM setup that the NemoClaw onboard wizard can use, start, or install.
import { AgentOnly } from "../_components/AgentGuide";
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 experimental managed 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.
## Ollama
Ollama is the default local inference option.
The onboard wizard detects Ollama automatically when you have installed it or started it on the host.
If you installed Ollama but have not started it, NemoClaw starts it for you.
On macOS and Linux, the wizard can also offer to install Ollama when it is not present.
When the host Ollama is below the minimum version NemoClaw expects for its starter models (currently `0.7.0`), the wizard surfaces an explicit **Upgrade Ollama** entry in the provider menu instead of silently reusing the older daemon, and the express setup path resolves to that entry.
The wizard inspects both the CLI binary (`ollama --version`) and the locally running daemon (`/api/version` on `:11434`) so the upgrade entry still appears when only one side is stale, for example a fresh user-local binary paired with the original system daemon.
The gate skips Windows-host Ollama reached from WSL through `host.docker.internal`.
The separate **Use / Start / Install Ollama on Windows host** entries handle that case and run their own actions on the Windows side.
On macOS, the wizard runs the platform install or upgrade path with `brew upgrade ollama`.
On Linux, the wizard runs the official `https://ollama.com/install.sh` path.
Upgrades on Linux always take the sudo-driven system path because the sudo-free user-local fallback would leave the existing system daemon on `:11434` serving the stale binary.
If sudo is not available in a non-interactive run, NemoClaw refuses to silently downgrade the path and asks you to rerun interactively or upgrade Ollama manually.
After an upgrade finishes, NemoClaw re-probes the running daemon's `/api/version` and fails the run if the daemon still reports below the minimum.
Fresh installs skip this re-probe because the bundled installers ship a daemon at or above the minimum.
On WSL, the wizard can use, start, restart, or install Ollama on the Windows host through PowerShell interop.
### Linux Install Modes
On native Linux, the install path picks between a system install (under `/usr/local`, using the official `https://ollama.com/install.sh`) and a sudo-free user-local install (under `${HOME}/.local`).
NemoClaw selects the mode automatically:
- Running as root or with passwordless sudo (`sudo -n true` returns 0) selects the system install.
- A non-interactive run (`NEMOCLAW_NON_INTERACTIVE=1` or no TTY on stdin) without passwordless sudo selects the user-local install.
This is the path that lets headless hosts complete onboarding without prompting for a sudo password.
- An interactive shell without passwordless sudo selects the system install and lets the official installer prompt for the password as usual.
Override the detection with `NEMOCLAW_OLLAMA_INSTALL_MODE=system` or `NEMOCLAW_OLLAMA_INSTALL_MODE=user`.
The user-local install replicates only the binary extraction step of the official installer.
It downloads the release tarball, extracts it to `${HOME}/.local`, and launches `${HOME}/.local/bin/ollama serve` one time.
It does not configure a systemd service, does not create the `ollama` system user, and does not install CUDA drivers, so you must relaunch the daemon manually after a reboot.
NemoClaw also prints a one-line `PATH` hint if `${HOME}/.local/bin` is not already on your `PATH`; you can add `export PATH="${HOME}/.local/bin:$PATH"` to your shell profile to invoke `ollama` directly.
Both modes rely on `zstd` for archive extraction. On Debian and Ubuntu, the system path uses `sudo apt-get` to install `zstd` automatically and explains the prompt before continuing.
The user-local path cannot bootstrap system packages without elevation.
If `zstd` is missing, it prints per-distro install hints and exits.
Install `zstd` manually, then rerun onboarding.
Run the onboard wizard.
```bash
nemoclaw onboard
```
Select **Local Ollama** from the provider list.
NemoClaw lists installed models or offers starter models if you have not installed any.
On hosts where the larger starter models fit the currently available GPU memory, the starter list includes `qwen3.6:35b` and selects it by default.
When another GPU workload is using most of the memory at onboard time, NemoClaw downgrades the menu to the largest model that still fits.
It pulls the selected model, loads it into memory, and validates it before continuing.
When Ollama reports a loaded-model context length, NemoClaw uses that value for the `contextWindow` baked into `openclaw.json` unless you set `NEMOCLAW_CONTEXT_WINDOW` yourself.
If the selected model declares that it does not support tool calling, onboarding stops with guidance to choose a model whose `ollama show <model>` capabilities include `tools`.
The validation also requires structured chat-completions tool calls.
If the model leaks tool-call JSON as plain message text, onboarding stops so you can choose a model that returns tool calls in the expected response field.
If a host-side validation probe times out, NemoClaw retries the Ollama tool-call validation with a larger timeout before failing the setup.
On WSL, if you choose the Windows-host Ollama path, NemoClaw uses `host.docker.internal:11434` and pulls missing models through the Ollama HTTP API instead of requiring the `ollama` CLI inside WSL.
### WSL with Windows-Host Ollama
When NemoClaw runs inside WSL, the provider menu can include Windows-host Ollama actions:
- Use Ollama on Windows host when the Windows daemon is already reachable.
- Restart Ollama on Windows host when you installed the daemon but bound it only to Windows loopback.
- Start Ollama on Windows host when you installed Ollama but have not started it.
- Install Ollama on Windows host when Windows does not have Ollama installed.
The install and restart paths set `OLLAMA_HOST=0.0.0.0:11434` on the Windows side so Docker and WSL can reach the daemon through `host.docker.internal`.
After an install or restart action, NemoClaw relaunches Ollama from the detected Windows tray app or verified `ollama.exe` path and waits until `host.docker.internal:11434` responds.
If the HTTP endpoint is not reachable yet, NemoClaw also checks for the Windows `ollama.exe` process through PowerShell interop so it can offer a start or restart action instead of hiding the Windows-host path.
If the daemon does not become reachable, onboarding prints PowerShell commands you can run to inspect the Windows-side process and port state. Use one Ollama instance on port `11434` at a time.
If both WSL and Windows-host Ollama are running, pick the intended menu entry during onboarding so NemoClaw validates and pulls models against the right daemon.
Windows-host Ollama requires Docker Desktop WSL integration because the sandbox reaches the Windows daemon through Docker Desktop's WSL routing path.
If NemoClaw detects native Docker Engine inside WSL, the provider menu labels Windows-host Ollama actions as requiring Docker Desktop integration.
Selecting one of those actions in the unsupported native Docker topology exits early with a remediation message instead of trying to start or install Ollama on Windows.
<AgentOnly variant="openclaw">
**Warning:**
Ollama is convenient for local chat, but some model/template combinations can
return tool calls as plain text under realistic agent load. If the TUI shows raw
JSON such as `{"name":"memory_search","arguments":{...}}` instead of running a
tool, switch to vLLM with `--enable-auto-tool-choice` and the correct
`--tool-call-parser`. See [Tool-Calling Reliability](references/tool-calling-reliability.md).
</AgentOnly>
### 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.
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`.
For non-WSL Ollama setups, the onboard wizard manages the proxy automatically:
- Generates a random 24-byte token on first run and stores it in
`~/.nemoclaw/ollama-proxy-token` with `0600` permissions.
- Starts the proxy after Ollama and verifies it before continuing.
- Cleans up stale proxy processes from previous runs.
- Probes the sandbox Docker network path to the proxy before committing the inference route.
- Stops matching proxy processes during uninstall before deleting NemoClaw state.
- Reuses the persisted token after a host reboot so you do not need to re-run
onboard.
On native Linux hosts, a firewall can allow the host proxy health check while still blocking sandbox containers on the OpenShell Docker bridge.
When the sandbox-side proxy probe fails with a TCP error, onboarding exits before it saves the inference route and prints a command like:
```bash
sudo ufw allow from <openshell-docker-subnet> to any port 11435 proto tcp
nemoclaw onboard
```
If the probe cannot run, for example because Docker Desktop or WSL uses a different host routing model, onboarding continues and relies on the regular proxy health check.
NemoClaw configures the sandbox provider to use proxy port `11435` with the generated token as its `OPENAI_API_KEY` credential.
OpenShell's L7 proxy injects the token at egress, so the agent inside the sandbox never sees the token directly.
All proxy endpoints require the Bearer token, including `GET /api/tags`.
Internal health and reachability checks run through the proxy treat any HTTP response, including `401`, as proof the proxy is alive.
They fail only when nothing answers at all.
If Ollama is already running on a non-loopback address when you start onboard,
the wizard restarts it on `127.0.0.1:11434` so the proxy is the only network
path to the model server.
### GPU Memory Cleanup
When you switch away from Ollama, stop host services, or destroy an Ollama-backed sandbox, NemoClaw asks Ollama to unload currently loaded models from GPU memory.
The cleanup sends `keep_alive: 0` for each model reported by Ollama and runs on a best-effort basis, so shutdown continues if Ollama is already stopped.
This does not delete downloaded model files.
### Non-Interactive Setup
```bash
NEMOCLAW_PROVIDER=ollama \
NEMOCLAW_MODEL=qwen3.5:9b \
nemoclaw onboard --non-interactive --yes
```
If `NEMOCLAW_MODEL` is not set, NemoClaw selects a default model based on available memory.
If `NEMOCLAW_MODEL` names a known bootstrap model (for example `qwen3.6:35b`) that does not fit the host's currently available GPU memory, NemoClaw warns and falls back to the largest known model that does fit.
Unknown or custom tags (any value the bootstrap registry has not seen) are still passed through; the Ollama runner validates the choice itself.
In interactive onboarding, registry-known installed tags that do not fit current GPU memory are filtered out of the installed-model menu.
If none of the installed registry-known tags fit, NemoClaw shows the starter-model choices and warns when even the smallest bootstrap tag may not fit.
After a selected model fails validation, NemoClaw excludes that tag from the next installed-model menu so pressing Enter cannot select the same failing model repeatedly.
When Ollama reports a loaded-model context length below `16384` and `NEMOCLAW_CONTEXT_WINDOW` is unset, NemoClaw raises the baked `contextWindow` to `16384` so the agent prompt and tool definitions fit better than the stock daemon default.
If the initial Ollama validation probe times out during a cold load, NemoClaw retries once with a 300-second probe budget.
This applies beyond DGX Spark, including tight-VRAM dGPU hosts where warm-up can spill from GPU to CPU.
`--yes` (or `NEMOCLAW_YES=1`) authorizes the Ollama model download without an interactive confirmation prompt.
Under `--non-interactive`, include `--yes` (or `NEMOCLAW_YES=1`) to authorize the download.
Onboard exits otherwise because it cannot prompt.
Run onboard without `--non-interactive` to get the interactive `[y/N]` prompt that shows the model size before downloading.
| Variable | Purpose |
|---|---|
| `NEMOCLAW_PROVIDER` | Set to `ollama`. |
| `NEMOCLAW_MODEL` | Ollama model tag to use. Optional. |
| `NEMOCLAW_YES` | Set to `1` to auto-accept the model-download confirmation prompt. Optional. |
## Compatible Local Servers
Use **Other OpenAI-compatible endpoint** for vLLM, TensorRT-LLM, llama.cpp, LocalAI, NIM, SGLang, or another server that implements `/v1/chat/completions`.
For compatible endpoints, NemoClaw uses `/v1/chat/completions` by default because some local backends accept `/v1/responses` but drop system prompts or tool definitions.
Set `NEMOCLAW_PREFERRED_API=openai-responses` only after you have verified that the backend streams the events OpenClaw requires.
For the full compatible-endpoint prompt flow, non-interactive variables, API-path controls, managed vLLM profiles, NIM setup, and timeout settings, refer to [Inference Options](references/inference-options.md#setup-details-for-local-and-compatible-providers).
## Managed vLLM and NIM
NemoClaw can use an already-running vLLM server on `localhost:8000`, start managed vLLM on supported NVIDIA GPU hosts, or manage a local NIM container when `NEMOCLAW_EXPERIMENTAL=1` is set.
Managed vLLM records the model returned by `/v1/models` and uses runtime metadata such as `max_model_len` when available.
In interactive managed vLLM setup, the wizard lists validated model choices for your host profile before it pulls weights.
Press **Enter** to accept the profile default, or choose a numbered model from the list.
For scripted runs, set `NEMOCLAW_VLLM_MODEL=<slug>` to choose a registry model without prompting.
If the host reboots and the `nemoclaw-vllm` container is stopped, NemoClaw restarts the managed vLLM container during recovery instead of requiring a fresh onboarding run.
NIM uses the same chat-completions API path restriction as vLLM.
On Linux Docker-driver GPU sandboxes, NemoClaw keeps local inference on the OpenShell bridge route and verifies `https://inference.local/v1/models` from inside the sandbox runtime after the sandbox reaches ready.
It treats only a 2xx response as success because that path includes the proxy authentication rewrite the agent uses.
If the runtime route fails, onboarding reports the endpoint and recovery steps before the first agent prompt.
For registry slugs, Hugging Face token requirements, NGC login behavior, and non-interactive examples, refer to [Inference Options](references/inference-options.md#setup-details-for-local-and-compatible-providers).
## Verify the Configuration
After onboarding completes, confirm the active provider and model.
```bash
nemoclaw <name> status
```
The output shows the provider label (for example, "Local vLLM" or "Other OpenAI-compatible endpoint") and the active model.
For Local Ollama, status also checks the authenticated proxy when a proxy token is available.
If `Inference` is healthy but `Inference (auth proxy)` is not, rerun onboarding to repair the proxy path that sandbox requests use.
## Switch Models at Runtime
You can change the model without re-running onboard.
Refer to [Switch Inference Models](references/switch-inference-providers.md) for the full procedure.
For compatible endpoints, the command is:
```bash
nemoclaw inference set --provider compatible-endpoint --model <model-name>
```
If the provider itself needs to change (for example, switching from vLLM to a cloud API), pass the new provider to `nemoclaw inference set`.
## References
- **Load [references/switch-inference-providers.md](references/switch-inference-providers.md)** when switching inference providers, changing the model runtime, or reconfiguring inference routing. Changes the active inference model without restarting the sandbox.
- **Load [references/set-up-sub-agent.md](references/set-up-sub-agent.md)** when users ask how to add a second model, configure a sub-agent model, use Omni for vision tasks, configure agents.list, or use sessions_spawn in NemoClaw. Shows the NemoClaw-specific file paths and update flow for adding an auxiliary OpenClaw sub-agent model.
- **Load [references/inference-options.md](references/inference-options.md)** when explaining which providers are available, what the onboard wizard presents, or how inference routing works. Lists all inference providers offered during NemoClaw onboarding.
- **[references/tool-calling-reliability.md](references/tool-calling-reliability.md)** — Explains Ollama tool-call leak symptoms, when to use vLLM with a tool-call parser, and how to repoint NemoClaw to a parser-aware local endpoint.
## Related Skills
- [Inference Options](references/inference-options.md) for the full list of providers available during onboarding.
- [Tool-Calling Reliability](references/tool-calling-reliability.md) for diagnosing raw JSON tool-call output with local models.
- [Switch Inference Models](references/switch-inference-providers.md) for runtime model switching.
- `nemoclaw-user-get-started` — Quickstart (use the `nemoclaw-user-get-started` skill) for first-time installation

11
.agents/skills/nemoclaw-user-configure-inference/evals/evals.json
View file

@ -1,11 +0,0 @@
[
{
"id": "docs-inference-inference-options-001",
"question": "I'm choosing an inference option during onboarding. Help me compare hosted providers, local servers, and compatible endpoints so I can select a model path that fits my privacy, cost, and reliability needs.",
"expected_skill": "nemoclaw-user-configure-inference",
"ground_truth": "A NemoClaw-specific answer that helps the user compare hosted providers, local servers, and compatible endpoints and gives enough concrete guidance, decision criteria, verification steps, or risk framing to select a model path that fits my privacy, cost, and reliability needs.",
"expected_behavior": [
"Uses the expected_skill and does not make up answers if it cannot find the answer from the skill."
]
}
]

454
.agents/skills/nemoclaw-user-configure-inference/references/inference-options.md
View file

@ -1,454 +0,0 @@
# NemoClaw Inference Options
import { AgentOnly } from "../_components/AgentGuide";
NemoClaw supports multiple inference providers.
During onboarding, the NemoClaw onboarding wizard presents a numbered list of providers to choose from.
Your selection determines where NemoClaw routes the agent's inference traffic.
<AgentOnly variant="openclaw">
For OpenClaw onboarding, use `nemoclaw onboard`.
The provider flow is the same, with the NVIDIA Endpoints route available for OpenClaw Agent.
</AgentOnly>
<AgentOnly variant="hermes">
For Hermes onboarding, use `nemoclaw onboard`.
The provider flow is the same, with the Hermes Provider route available for Hermes Agent.
</AgentOnly>
## 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.
Local Ollama and local vLLM do not require your host `OPENAI_API_KEY`.
NemoClaw uses provider-specific local tokens for those routes, and rebuilds of legacy local-inference sandboxes migrate away from stale OpenAI credential requirements.
## Provider Status
| Provider | Status | Endpoint type | Notes |
|----------|--------|---------------|-------|
| NVIDIA Endpoints | Tested | OpenAI-compatible | Hosted models on integrate.api.nvidia.com |
| OpenAI | Tested | Native OpenAI-compatible | Uses OpenAI model IDs |
| Other OpenAI-compatible endpoint | Tested | Custom OpenAI-compatible | For compatible proxies and gateways |
| Anthropic | Tested | Native Anthropic | Uses anthropic-messages |
| Other Anthropic-compatible endpoint | Tested | Custom Anthropic-compatible | For Claude proxies and compatible gateways |
| Google Gemini | Tested | OpenAI-compatible | Uses Google's OpenAI-compatible endpoint |
| Hermes Provider | Hermes only | OpenAI-compatible route | Available when onboarding Hermes Agent through `nemohermes` |
| Local Ollama | Caveated | Local Ollama API | Available when Ollama is installed or running on the host |
| Local NVIDIA NIM | Experimental | Local OpenAI-compatible | Requires `NEMOCLAW_EXPERIMENTAL=1` and a NIM-capable GPU |
| Local vLLM (already running) | Caveated | Local OpenAI-compatible | Appears in the onboarding menu when NemoClaw detects a server already on `localhost:8000`. No flag required. |
| Local vLLM (managed install/start) | Caveated | Local OpenAI-compatible | Appears by default on DGX Spark and DGX Station. Generic Linux NVIDIA GPU hosts require `NEMOCLAW_EXPERIMENTAL=1` or `NEMOCLAW_PROVIDER=install-vllm`. NemoClaw pulls/starts a vLLM container on a supported NVIDIA GPU host. |
## Provider Options
The onboard wizard presents the following provider options by default.
The first six are always available.
Ollama appears when you have installed or started it on the host.
Local vLLM appears when NemoClaw detects a running vLLM server.
The managed install/start vLLM entry appears by default on DGX Spark and DGX Station, and appears on generic Linux NVIDIA GPU hosts after opt-in.
| 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_INFERENCE_API_KEY`. | Nemotron 3 Super 120B, Nemotron 3 Ultra 550B, GLM-5.1, MiniMax M2.7, GPT-OSS 120B, DeepSeek V4 Pro |
| 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`. NemoClaw uses `/v1/chat/completions` at runtime by default; set `NEMOCLAW_PREFERRED_API=openai-responses` to allow `/v1/responses` for proxies that implement it, such as some llama.cpp builds. The wizard prompts for a base URL and model name. Works with OpenRouter, LocalAI, llama.cpp, or any compatible proxy. When you enable Telegram messaging, onboarding also runs a bounded sandbox-side smoke check through `https://inference.local/v1/chat/completions`. 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 chat-completions endpoint. NemoClaw skips the Responses-API probe because Gemini does not support `/v1/responses`. Set `GEMINI_API_KEY`. | `gemini-3.1-pro-preview`, `gemini-3.1-flash-lite-preview`, `gemini-3-flash-preview`, `gemini-2.5-pro`, `gemini-2.5-flash`, `gemini-2.5-flash-lite` |
| Hermes Provider | Routes Hermes Agent through the host OpenShell provider registered by NemoClaw when onboarding Hermes Agent. | Curated Hermes Provider models such as `moonshotai/kimi-k2.6`, `openai/gpt-5.4-mini`, and `z-ai/glm-5.1`. |
| Local Ollama | Routes to a local Ollama instance on `localhost:11434`. NemoClaw detects installed models, offers starter models if none are present, pulls and warms the selected model, and validates it. | Selected during onboarding. For more information, refer to [Use a Local Inference Server](../SKILL.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
NVIDIA Nemotron models expose OpenAI-compatible APIs across every supported deployment surface, so two onboarding options can route to Nemotron.
| Nemotron Host | Onboard Wizard Option | Why |
|---|---|---|
| `build.nvidia.com` (NVIDIA-hosted) | **Option 1: NVIDIA Endpoints** | NemoClaw sets the base URL to `https://integrate.api.nvidia.com/v1` for you and validates the model against the build catalog. |
| Self-hosted NIM container | **Option 3: Other OpenAI-compatible endpoint** | NIM exposes an OpenAI-compatible `/v1/chat/completions` route. Point the base URL at your NIM service and enter the Nemotron model ID. |
| Enterprise NVIDIA AI Enterprise gateway | **Option 3: Other OpenAI-compatible endpoint** | Enterprise gateways front Nemotron with the same OpenAI-compatible contract. Use the gateway's base URL and your enterprise token. |
| vLLM, SGLang, or TRT-LLM serving Nemotron weights | **Option 3: Other OpenAI-compatible endpoint** | Each runtime exposes Nemotron through `/v1/chat/completions`. Use the runtime's base URL and the model ID it reports. |
| Local NIM started by the wizard | **Local NVIDIA NIM** (experimental) | Requires `NEMOCLAW_EXPERIMENTAL=1` and a NIM-capable GPU. NemoClaw pulls and manages the container for you. |
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`.
Edit that file to define which models the router can choose from.
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.
```yaml
routing:
method: prefill
checkpoint: llm-router/checkpoints/prefill_router_qwen08b.pt
tolerance: 0.20
encoder: Qwen/Qwen3.5-0.8B
models:
- name: nano
litellm_model: "openai/nvidia/nvidia/Nemotron-3-Nano-30B-A3B"
cost_per_m_input_tokens: 0.05
api_base: "https://integrate.api.nvidia.com"
- name: super
litellm_model: "openai/nvidia/nemotron-3-super-120b-a12b"
cost_per_m_input_tokens: 0.10
api_base: "https://integrate.api.nvidia.com"
```
The `tolerance` parameter controls the accuracy-cost tradeoff.
| Value | Behavior |
|-------|----------|
| `0.0` | Always pick the most accurate model. |
| `0.20` | Allow up to 20 percentage points below the best for a cheaper model (default). |
| `1.0` | Always pick the cheapest model. |
The router runs on the host, not inside the sandbox.
```text
Sandbox (agent) ──> OpenShell Gateway (L7 proxy) ──> Model Router (:4000) ──> NVIDIA API
└── PrefillRouter selects model
```
Credentials flow through the OpenShell provider system.
The sandbox never sees raw API keys.
To use the router in scripted setup, set:
```bash
NEMOCLAW_PROVIDER=routed NVIDIA_INFERENCE_API_KEY=<your-key> nemoclaw onboard --non-interactive
```
### Host Python Requirement
The Model Router runs in a host-side virtual environment that NemoClaw creates during onboarding.
NemoClaw probes `python3.13`, `python3.12`, `python3.11`, `python3.10`, and bare `python3`, and adopts the first interpreter that satisfies both of:
- Version inside `[3.10, 3.14)`.
- `ensurepip`, `pyexpat`, `ssl`, and `venv` all import without error.
If no candidate qualifies, onboarding aborts and prints the real failure for each candidate.
This surfaces issues like Homebrew `python@3.14` whose `pyexpat` extension fails to dlopen against the older system `libexpat` on macOS.
To pin a specific interpreter, set `NEMOCLAW_MODEL_ROUTER_PYTHON` to its absolute path before running `nemoclaw onboard`:
```bash
NEMOCLAW_MODEL_ROUTER_PYTHON=/opt/homebrew/bin/python3.12 nemoclaw onboard
```
The pin is strict.
NemoClaw probes only that interpreter and aborts with the failure reason if it does not qualify, rather than silently falling back to a different python on `PATH`.
NemoClaw rejects relative command names such as `python3.12`.
Use `command -v python3.12` to find the absolute path.
If `python -m venv` itself fails for a probe-clean interpreter (for example, a corrupt ensurepip seed), NemoClaw retries with the next healthy candidate when no pin is set; with a pin set, the failure stops onboarding so you can fix or repoint the pinned python.
## Caveated Local Options
The following local inference options have caveats.
Local NIM and generic Linux managed vLLM install/start require `NEMOCLAW_EXPERIMENTAL=1`; DGX Spark and DGX Station managed vLLM entries appear by default.
An already-running vLLM server appears directly 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`, or a supported DGX Spark, DGX Station, or Linux NVIDIA GPU profile | Auto-detects the loaded model when vLLM is already running. Can install or start a managed vLLM container by default on DGX Spark/Station and after opt-in on generic Linux NVIDIA GPU hosts. |
For setup instructions, refer to [Use a Local Inference Server](../SKILL.md).
## Validation
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.
The wizard retries transient upstream validation failures before it reports a provider failure.
The `nvapi-` prefix check applies only to `NVIDIA_INFERENCE_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.
| Provider type | Validation method |
|---|---|
| OpenAI | Tries `/responses` first, then `/chat/completions`. |
| NVIDIA Endpoints | Validates through `/v1/chat/completions` only; NemoClaw skips the `/v1/responses` probe because NVIDIA Build does not expose `/v1/responses` (returns 404 for every model). |
| Google Gemini | Validates through Gemini's OpenAI-compatible chat-completions path only; NemoClaw skips the `/v1/responses` probe because Gemini does not support the Responses API. |
| Other OpenAI-compatible endpoint | Tries `/v1/responses` first with a tool-calling probe; falls back to `/v1/chat/completions`. Selected runtime API defaults to `/v1/chat/completions`; set `NEMOCLAW_PREFERRED_API=openai-responses` to allow `/v1/responses` at runtime when validation succeeds. |
| 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 tries `/v1/responses` first then falls back to `/v1/chat/completions`; the selected runtime API defaults to `/v1/chat/completions`. Set `NEMOCLAW_PREFERRED_API=openai-responses` to allow `/v1/responses` at runtime when validation succeeds. |
| Local NVIDIA NIM | Validates through `/v1/chat/completions` only; NemoClaw skips the `/v1/responses` probe (same as NVIDIA Endpoints). |
## Setup Details for Local and Compatible Providers
The sections below collect the detailed setup prompts and environment variables for local and compatible inference providers.
Use them when the quickstart or local inference guide points you here for exact command shapes.
## OpenAI-Compatible Server
This option works with any server that implements `/v1/chat/completions`, including vLLM, TensorRT-LLM, llama.cpp, LocalAI, and others.
For compatible endpoints, NemoClaw uses `/v1/chat/completions` by default.
This avoids a class of failures where local backends accept `/v1/responses` requests but silently drop the system prompt and tool definitions.
To opt in to `/v1/responses`, set `NEMOCLAW_PREFERRED_API=openai-responses` before running onboard.
Start your model server.
The examples below use vLLM, but any OpenAI-compatible server works.
```bash
vllm serve meta-llama/Llama-3.1-8B-Instruct --port 8000
```
Run the onboard wizard.
```bash
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.
The wizard probes `/v1/chat/completions` by default for the compatible-endpoint provider.
If you set `NEMOCLAW_PREFERRED_API=openai-responses`, NemoClaw probes `/v1/responses` instead and only selects it when the response includes the streaming events OpenClaw requires.
If a reasoning model returns only reasoning content before producing a final answer, NemoClaw retries the smoke request with a larger response budget.
Route, configuration, and authentication failures still fail immediately.
### Non-Interactive Setup
Set the following environment variables for scripted or CI/CD deployments.
```bash
NEMOCLAW_PROVIDER=custom \
NEMOCLAW_ENDPOINT_URL=http://localhost:8000/v1 \
NEMOCLAW_MODEL=meta-llama/Llama-3.1-8B-Instruct \
COMPATIBLE_API_KEY=dummy \
nemoclaw onboard --non-interactive
```
| 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. |
### Selecting the API Path
For the compatible-endpoint provider, `/v1/chat/completions` is the default.
NemoClaw tests streaming events during onboarding and uses chat completions
without probing the Responses API.
To opt in to `/v1/responses`, set `NEMOCLAW_PREFERRED_API` before running onboard:
```bash
NEMOCLAW_PREFERRED_API=openai-responses nemoclaw onboard
```
The wizard then probes `/v1/responses` and only selects it when streaming
support is complete.
If the probe fails, the wizard falls back to `/v1/chat/completions`
automatically.
You can use this variable in both interactive and non-interactive mode.
| Variable | Values | Default |
|---|---|---|
| `NEMOCLAW_PREFERRED_API` | `openai-completions`, `openai-responses` | `openai-completions` for compatible endpoints |
If you already onboarded and the sandbox is failing at runtime, re-run `nemoclaw onboard` to re-probe the endpoint and bake the correct API path
into the image.
Refer to [Switch Inference Models](switch-inference-providers.md) for more information.
## Anthropic-Compatible Server
If your local server implements the Anthropic Messages API (`/v1/messages`), choose **Other Anthropic-compatible endpoint** during onboarding instead.
```bash
nemoclaw onboard
```
For non-interactive setup, use `NEMOCLAW_PROVIDER=anthropicCompatible` and set `COMPATIBLE_ANTHROPIC_API_KEY`.
```bash
NEMOCLAW_PROVIDER=anthropicCompatible \
NEMOCLAW_ENDPOINT_URL=http://localhost:8080 \
NEMOCLAW_MODEL=my-model \
COMPATIBLE_ANTHROPIC_API_KEY=dummy \
nemoclaw onboard --non-interactive
```
## vLLM
When vLLM is already running on `localhost:8000`, NemoClaw can detect it automatically and query the `/v1/models` endpoint to determine the loaded model.
On supported Linux hosts with NVIDIA GPUs, the onboard wizard can also install or start a managed vLLM container for you.
For an already-running vLLM server, run `nemoclaw onboard` and select **Local vLLM [experimental]** from the provider list.
If vLLM is already running, NemoClaw detects the running model and validates the endpoint.
When vLLM exposes runtime metadata such as `max_model_len`, NemoClaw uses that value for the `contextWindow` baked into `openclaw.json` unless you set `NEMOCLAW_CONTEXT_WINDOW` yourself.
If vLLM is not running and your host matches a DGX Spark or DGX Station managed profile, NemoClaw shows the **Install vLLM** or **Start vLLM** entry by default.
Generic Linux NVIDIA GPU hosts still require `NEMOCLAW_EXPERIMENTAL=1` or `NEMOCLAW_PROVIDER=install-vllm` before the managed entry appears.
In interactive runs, the managed vLLM path lists the supported registry models for your host profile before it pulls weights.
Press **Enter** to use the default model, or choose a numbered entry to serve another validated model with its matching `vllm serve` flags.
NemoClaw pulls the vLLM image, downloads model weights into `~/.cache/huggingface`, starts the `nemoclaw-vllm` container on `localhost:8000`, streams Hugging Face download progress, and polls `/v1/models` until the model is ready.
Managed DGX Spark and DGX Station profiles use the stable NGC `nvcr.io/nvidia/vllm:26.05.post1-py3` container image.
If Docker pull output stops making progress, a watchdog stops the stalled pull instead of failing slow but active downloads on a fixed wall-clock timeout.
If vLLM never becomes ready, NemoClaw prints a short tail of the vLLM container logs before exiting.
The first run can take 10 to 30 minutes.
Later runs reuse the cached image and model weights.
Managed vLLM uses these profiles:
| Host profile | Default model |
|---|---|
| DGX Spark | `nvidia/Qwen3.6-35B-A3B-NVFP4` |
| DGX Station | `Qwen/Qwen3.6-27B-FP8` |
| Linux with an NVIDIA GPU | `nvidia/NVIDIA-Nemotron-3-Nano-4B-FP8` |
**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
Use an already-running vLLM server:
```bash
NEMOCLAW_PROVIDER=vllm \
nemoclaw onboard --non-interactive
```
Install or start managed vLLM when NemoClaw detects a supported profile.
On DGX Spark and DGX Station, `NEMOCLAW_PROVIDER=install-vllm` is enough for non-interactive runs; add `NEMOCLAW_EXPERIMENTAL=1` on generic Linux NVIDIA GPU hosts.
Non-interactive runs use the profile default unless you set `NEMOCLAW_VLLM_MODEL`.
```bash
NEMOCLAW_PROVIDER=install-vllm \
nemoclaw onboard --non-interactive
```
NemoClaw records the model returned by vLLM's `/v1/models` endpoint.
Start vLLM with the model you want before onboarding if you manage the server yourself.
### Override the Managed-vLLM Model
Managed vLLM serves the profile default unless you choose a different registry entry in the interactive picker or set an override for automation.
Export `NEMOCLAW_VLLM_MODEL=<slug>` before invoking the installer to choose a different model without prompting.
NemoClaw uses the matching `vllm serve` flags, including the reasoning parser, tool-call parser, and `--max-model-len`.
Recognized slugs are:
| Slug | Hugging Face model | Notes |
|---|---|---|
| `qwen3.6-27b` | `Qwen/Qwen3.6-27B-FP8` | Default on the DGX Station profile |
| `qwen3.6-35b-a3b-nvfp4` | `nvidia/Qwen3.6-35B-A3B-NVFP4` | Default on the DGX Spark profile |
| `nemotron-3-nano-4b` | `nvidia/NVIDIA-Nemotron-3-Nano-4B-FP8` | Default on the generic Linux + NVIDIA GPU profile |
| `deepseek-v4-flash` | `deepseek-ai/DeepSeek-V4-Flash` | Supported override |
| `deepseek-r1-distill-70b` | `deepseek-ai/DeepSeek-R1-Distill-Llama-70B` | Gated. Requires Hugging Face license acceptance |
The slug is case-insensitive; the full Hugging Face id is also accepted.
An unrecognized value fails fast with a list of valid slugs.
Gated models require a Hugging Face token; export it before onboarding so NemoClaw can forward it into the managed vLLM container:
```bash
export HF_TOKEN=<your-hf-token>
NEMOCLAW_PROVIDER=install-vllm \
NEMOCLAW_VLLM_MODEL=deepseek-r1-distill-70b \
nemoclaw onboard --non-interactive
```
NemoClaw accepts `HUGGING_FACE_HUB_TOKEN` as an alternative.
The token check runs on the host before any docker pull, so a missing or empty token aborts onboarding before bandwidth is spent on a 401.
### Add Managed-vLLM Serve Arguments
For advanced vLLM options that are not in the NemoClaw registry yet, export `NEMOCLAW_VLLM_EXTRA_ARGS_JSON` as a JSON array of individual non-blank `vllm serve` tokens.
NemoClaw trims and validates the array before pulling images or downloading models, shell-quotes each token, and appends the tokens after the registry defaults.
```bash
NEMOCLAW_PROVIDER=install-vllm \
NEMOCLAW_VLLM_EXTRA_ARGS_JSON='["--max-num-seqs","2","--disable-log-requests"]' \
nemoclaw onboard --non-interactive
```
Use this for operator-owned tuning only.
If the selected vLLM image does not support an argument, the managed container exits and NemoClaw prints the vLLM log tail.
## 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.
```bash
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.
On hosts with mixed NVIDIA GPU models, the preflight summary shows each detected GPU model and the total VRAM so you can confirm which device class the model selection used.
On Docker 29.x or containerd image-store hosts, NemoClaw resolves the host-platform manifest digest before pulling multi-architecture NIM images when the registry exposes an index.
It pulls `repo@digest` and retags the local image so NGC attestation metadata on other architectures does not block the selected platform.
If the registry does not expose a matching index, NemoClaw falls back to the tag pull.
NVIDIA hosts NIM container images on `nvcr.io`, and `docker pull` requires NGC registry authentication.
If Docker is not already logged in to `nvcr.io`, onboard prompts for an [NGC API key](https://org.ngc.nvidia.com/setup/api-key) and runs `docker login nvcr.io` over `--password-stdin` so the key is never written to disk or shell history.
The prompt masks the key during input and retries one time on a bad key before failing.
In non-interactive mode, onboard exits with login instructions if Docker is not already authenticated; run `docker login nvcr.io` yourself, then re-run `nemoclaw onboard --non-interactive`.
If `NGC_API_KEY` or `NVIDIA_INFERENCE_API_KEY` is already exported, NemoClaw passes it into the managed NIM container through the process environment instead of command-line arguments.
If the NIM container exits before the health endpoint becomes ready, onboarding stops early and prints the last container log lines.
After NIM becomes healthy, NemoClaw reads `/v1/models` and uses the served model id for validation when it differs from the catalog name.
Unsafe served ids are rejected instead of being written into the sandbox config.
**Note:**
NIM uses vLLM internally.
The same `chat/completions` API path restriction applies.
## Timeout Configuration
Local inference requests use a default timeout of 180 seconds.
Large prompts on hardware such as DGX Spark can exceed shorter timeouts, so NemoClaw sets a higher default for Ollama, vLLM, NIM, and compatible-endpoint setup.
To override the timeout, set the `NEMOCLAW_LOCAL_INFERENCE_TIMEOUT` environment variable before onboarding:
```bash
export NEMOCLAW_LOCAL_INFERENCE_TIMEOUT=300
nemoclaw onboard
```
The value is in seconds.
NemoClaw bakes this setting into the sandbox at build time.
Changing it after onboarding requires re-running `nemoclaw onboard`.
`NEMOCLAW_LOCAL_INFERENCE_TIMEOUT` only governs the inference-server validation probe.
During local Ollama setup, NemoClaw treats host-side curl process timeouts as retryable probe failures and retries with a larger timeout before it reports a validation failure.
NemoClaw also retries Docker runtime detection with a longer `docker info` timeout before it chooses the local inference route.
The post-create readiness wait (image build, gateway upload, in-sandbox boot) has its own budget, `NEMOCLAW_SANDBOX_READY_TIMEOUT`, also defaulting to 180 seconds.
On hosts where the sandbox image takes minutes to build or upload, raise both settings together.
Examples include large quantized models, DGX Station first runs, and remote VMs over a slow link.
```bash
export NEMOCLAW_LOCAL_INFERENCE_TIMEOUT=300
export NEMOCLAW_SANDBOX_READY_TIMEOUT=600
nemoclaw onboard
```
If onboard ends with `Sandbox '<name>' was created but did not become ready within 180s`, refer to Troubleshooting (use the `nemoclaw-user-reference` skill).
## Next Steps
- [Use a Local Inference Server](../SKILL.md) for Ollama, vLLM, NIM, and compatible-endpoint setup details.
<AgentOnly variant="openclaw">
- [Tool-Calling Reliability](tool-calling-reliability.md) for deciding when Ollama is enough and when vLLM with a parser is safer.
</AgentOnly>
- [Switch Inference Models](switch-inference-providers.md) for changing the model at runtime without re-onboarding.

135
.agents/skills/nemoclaw-user-configure-inference/references/set-up-sub-agent.md
View file

@ -1,135 +0,0 @@
# Set Up Task-Specific Sub-Agents
OpenClaw documents the sub-agent behavior, `sessions_spawn` tool, `agents.list` configuration, tool policy, nesting, and auth model in [Sub-Agents](https://docs.openclaw.ai/tools/subagents).
Use that page as the source of truth for how OpenClaw sub-agents work.
This NemoClaw page covers the sandbox-specific pieces: where the OpenClaw config lives, where to put per-agent credentials, which writable workspace path agents should use, and how the Omni VLM demo maps onto those paths.
## NemoClaw Sandbox Paths
NemoClaw runs OpenClaw inside an OpenShell sandbox.
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 so OpenClaw can detect the updated config. |
| `/sandbox/.openclaw/agents/<agent-id>/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. |
For file-based tasks, instruct agents to use `/sandbox/.openclaw/workspace/`.
Avoid relying on legacy `.openclaw-data` paths or read-only OpenClaw paths in delegation instructions.
## Omni Vision Sub-Agent Example
The [`vlm-demo`](https://github.com/brevdev/nemoclaw-demos/tree/main/vlm-demo) applies the OpenClaw sub-agent pattern to a vision task.
It keeps the primary `main` agent on the normal NemoClaw inference route and adds a `vision-operator` sub-agent backed by an Omni vision model.
| OpenClaw field | Omni example value |
|---|---|
| Primary agent | `main` |
| Primary model | `inference/nvidia/nemotron-3-super-120b-a12b` |
| Auxiliary provider | `nvidia-omni` |
| Sub-agent | `vision-operator` |
| Sub-agent model | `nvidia-omni/private/nvidia/nemotron-3-nano-omni-reasoning-30b-a3b` |
| Delegation tool | `sessions_spawn` |
The sub-agent uses Omni as the specialist model for image tasks.
The primary orchestration model remains responsible for conversation, planning, and deciding when to delegate.
## Update the Sandbox Config
Fetch the current OpenClaw config from the sandbox, patch it with your auxiliary provider and `agents.list` changes, then upload it back.
On Docker-driver sandboxes, run these commands from the host that owns the sandbox containers.
The container name includes a runtime suffix, so discover it from the OpenShell sandbox label:
```bash
export SANDBOX=my-assistant
export SANDBOX_CTR=$(docker ps --filter "label=openshell.ai/sandbox-name=$SANDBOX" --format "{{.Names}}" | sed -n '1p')
docker exec --user root "$SANDBOX_CTR" cat /sandbox/.openclaw/openclaw.json > /tmp/openclaw.json
```
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.
Use NemoClaw runtime controls when the sandbox needs a hardened config posture after the manual edit.
```bash
docker exec --user root "$SANDBOX_CTR" chmod 644 /sandbox/.openclaw/openclaw.json
docker exec --user root "$SANDBOX_CTR" chmod 644 /sandbox/.openclaw/.config-hash
docker exec --user root -i "$SANDBOX_CTR" sh -c 'cat > /sandbox/.openclaw/openclaw.json' < /tmp/openclaw.updated.json
docker exec --user root "$SANDBOX_CTR" /bin/bash -c "cd /sandbox/.openclaw && sha256sum openclaw.json > .config-hash"
docker exec --user root "$SANDBOX_CTR" chown sandbox:sandbox /sandbox/.openclaw/openclaw.json /sandbox/.openclaw/.config-hash
docker exec --user root "$SANDBOX_CTR" chmod 444 /sandbox/.openclaw/openclaw.json
docker exec --user root "$SANDBOX_CTR" chmod 444 /sandbox/.openclaw/.config-hash
```
Check `/tmp/gateway.log` after upload and confirm the gateway hot-reloaded the provider or `agents.list` change.
## Add Sub-Agent Credentials
If the auxiliary model uses a provider key outside the normal NemoClaw inference route, put that key in the sub-agent auth profile.
For the Omni example:
```text
/sandbox/.openclaw/agents/vision-operator/agent/auth-profiles.json
```
Use the same provider ID that appears in `models.providers`, such as `nvidia-omni`.
After uploading the auth profile, make sure the sandbox user owns the sub-agent directory:
```bash
docker exec --user root "$SANDBOX_CTR" chown -R sandbox:sandbox /sandbox/.openclaw/agents/vision-operator
```
## Allow Auxiliary Provider Egress
If the sub-agent calls a provider directly, update the OpenShell network policy for the binary that makes the request.
In the Omni demo, the OpenClaw gateway runs as `/usr/local/bin/node`, so the NVIDIA endpoint policy must allow that binary.
Refer to Customize the Network Policy (use the `nemoclaw-user-manage-policy` skill) for policy update workflows.
## Sub-Agent Gateway Connectivity
Spawned sub-agents connect back to the OpenClaw gateway over WebSocket at `OPENCLAW_GATEWAY_URL`.
Inside the sandbox this connection runs through the enforced process tree, where the OpenShell proxy always blocks loopback destinations.
NemoClaw therefore points `OPENCLAW_GATEWAY_URL` at the sandbox's own interface address (for example `ws://10.200.0.2:18790`) and allowlists that endpoint in the base sandbox policy (`openclaw_gateway_dialback`).
If `sessions_spawn` returns `gateway closed (1006 abnormal closure (no close frame))` and the gateway log shows no connection attempt, the dial-back path is blocked.
Check the following:
1. `OPENCLAW_GATEWAY_URL` in the gateway process environment targets the sandbox interface address, not `127.0.0.1`.
2. The active policy allows that address and port. Custom `NEMOCLAW_DASHBOARD_PORT` or proxy subnet values need a matching `openshell policy update`.
3. Do not point the dial-back at `127.0.0.1` — the proxy denies loopback regardless of policy.
## Add Delegation Instructions
OpenClaw handles `sessions_spawn`, but the primary agent still needs task instructions.
Place those instructions in the writable workspace, for example:
```text
/sandbox/.openclaw/workspace/TOOLS.md
```
The Omni demo includes `vlm-demo/vlm-subagent/TOOLS.md`, which tells `main` to delegate image tasks to `vision-operator` and tells the sub-agent to read the image path it receives.
Adapt that file for other task-specific models.
## Demo Assets
Use the [`vlm-demo`](https://github.com/brevdev/nemoclaw-demos/tree/main/vlm-demo) repository for runnable Omni example assets:
- `vlm-subagent-guide.md` for a command-by-command walkthrough.
- `vlm-subagent/openclaw-patch.py` for patching `openclaw.json`.
- `vlm-subagent/auth-profiles.template.json` for the sub-agent auth profile.
- `vlm-subagent/TOOLS.md` for delegation instructions.
## Next Steps
Use the following resources for more information:
- Refer to [OpenClaw Sub-Agents](https://docs.openclaw.ai/tools/subagents) for `sessions_spawn`, `agents.list`, nesting, tool policy, and auth behavior.
- Refer to [Switch Inference Providers](switch-inference-providers.md) to change the primary orchestration model instead of adding a sub-agent model.
- Refer to Workspace Files (use the `nemoclaw-user-manage-sandboxes` skill) to understand per-agent workspace directories.

284
.agents/skills/nemoclaw-user-configure-inference/references/switch-inference-providers.md
View file

@ -1,284 +0,0 @@
# Switch Inference Models at Runtime
import { AgentOnly } from "../_components/AgentGuide";
Change the active inference model while the sandbox is running.
You do not need to restart the sandbox.
## Prerequisites
- A running NemoClaw sandbox.
- The OpenShell CLI on your `PATH`, which NemoClaw uses under the hood.
## Switch to a Different Model
<AgentOnly variant="openclaw">
Use `nemoclaw inference set` with the provider and model that match the upstream you want to use.
The command updates the OpenShell inference route and synchronizes the running agent config.
For OpenClaw, it updates `agents.defaults.model.primary` and the matching provider namespace.
</AgentOnly>
<AgentOnly variant="hermes">
Use `nemoclaw inference set` with the provider and model that match the upstream you want to use.
The command updates the OpenShell inference route and synchronizes the running agent config.
For Hermes, it updates `/sandbox/.hermes/config.yaml` (`model.default`, `model.base_url`, `model.provider: custom`, API-family mode when needed, and the OpenShell proxy API-key placeholder) without rebuilding or restarting Hermes.
Pass `--sandbox <name>` when you do not want to use the default registered sandbox.
Under `nemoclaw`, pass `--sandbox <name>` when you have registered more than one Hermes sandbox.
</AgentOnly>
<AgentOnly variant="openclaw">
Pass `--sandbox <name>` when you do not want to use the default registered sandbox.
</AgentOnly>
### NVIDIA Endpoints
```bash
nemoclaw inference set --provider nvidia-prod --model nvidia/nemotron-3-super-120b-a12b
```
### OpenAI
```bash
nemoclaw inference set --provider openai-api --model gpt-5.4
```
### Anthropic
```bash
nemoclaw inference set --provider anthropic-prod --model claude-sonnet-4-6
```
### Google Gemini
```bash
nemoclaw inference set --provider gemini-api --model gemini-2.5-flash
```
### Compatible Endpoints
If you onboarded a custom compatible endpoint, switch models with the provider created for that endpoint:
```bash
nemoclaw inference set --provider compatible-endpoint --model <model-name>
```
```bash
nemoclaw inference set --provider compatible-anthropic-endpoint --model <model-name>
```
<AgentOnly variant="hermes">
### Hermes Provider
For a NemoClaw-managed Hermes sandbox, use the Hermes alias with the registered Hermes Provider route:
```bash
nemoclaw inference set --provider hermes-provider --model openai/gpt-5.4-mini
```
</AgentOnly>
### API Family Sync
Before patching the in-sandbox config, NemoClaw resolves the target route's API family: OpenAI chat completions, Anthropic Messages, or OpenAI Responses.
For OpenClaw, `inference set` syncs the provider API family and primary model reference into the running config.
For Hermes, `inference set` writes `model.api_mode: anthropic_messages` for Anthropic Messages routes, `model.api_mode: codex_responses` for OpenAI Responses routes, and removes `api_mode` for OpenAI-style chat-completions routes.
Hermes also keeps `model.api_key` on the OpenShell proxy placeholder so dashboard and API sessions continue to authenticate through the gateway after a route change.
Amazon Bedrock Runtime routes created through `compatible-anthropic-endpoint` are the exception.
When you switch within the same Bedrock Runtime compatible provider, NemoClaw keeps the route OpenAI-compatible and does not set Hermes to Anthropic Messages mode.
#### Switching from Responses API to Chat Completions
If onboarding selected `/v1/responses` but the agent fails at runtime, re-run onboarding so the wizard re-probes the endpoint and bakes the correct API path into the image.
This can happen when the backend does not emit the streaming events OpenClaw requires.
```bash
nemoclaw onboard
```
Select the same provider and endpoint again.
The updated streaming probe detects incomplete `/v1/responses` support and selects `/v1/chat/completions` automatically.
For the compatible-endpoint provider, NemoClaw uses `/v1/chat/completions` by default, so you do not need an environment variable to keep the safe path.
To opt in to `/v1/responses` for a backend you have verified end to end, set `NEMOCLAW_PREFERRED_API` before onboarding:
```bash
NEMOCLAW_PREFERRED_API=openai-responses nemoclaw onboard
```
**Note:**
`NEMOCLAW_INFERENCE_API_OVERRIDE` patches the config at container startup but does not update the Dockerfile ARG baked into the image.
If you recreate the sandbox without the override environment variable, the image reverts to the original API path.
A fresh `nemoclaw onboard` is the reliable fix because it updates both the
session and the baked image.
## Cross-Provider Switching
<AgentOnly variant="openclaw">
Switching to a different provider family (for example, from NVIDIA Endpoints to Anthropic) also uses `nemoclaw inference set`.
The command updates both the gateway route and the OpenClaw provider namespace in the running sandbox config.
If the in-sandbox config sync fails after the gateway route is updated, NemoClaw keeps the host registry aligned with the gateway and prints a rebuild hint.
Run the rebuild before relying on the running agent if the warning says the image config could not be patched.
```bash
nemoclaw inference set --provider anthropic-prod --model claude-sonnet-4-6 --no-verify
```
</AgentOnly>
<AgentOnly variant="hermes">
Switching to a different provider family (for example, from NVIDIA Endpoints to Anthropic) also uses `nemoclaw inference set`.
The command updates both the gateway route and `/sandbox/.hermes/config.yaml`.
If the Hermes config sync fails after the gateway route is updated, NemoClaw keeps the host registry aligned with the gateway and prints a rebuild hint.
Run the rebuild before relying on the running agent if the warning says the image config could not be patched.
```bash
nemoclaw inference set --provider anthropic-prod --model claude-sonnet-4-6 --no-verify
```
</AgentOnly>
Use `--no-verify` only when OpenShell cannot verify the provider at switch time but you have already confirmed the provider and credential.
## Tune Model Metadata
The sandbox image bakes model metadata (context window, max output tokens, reasoning mode, and accepted input modalities) into `openclaw.json` at build time.
To change these values, set the corresponding environment variables before running `nemoclaw onboard` so they patch into the Dockerfile before the image builds.
| Variable | Values | Default |
|---|---|---|
| `NEMOCLAW_CONTEXT_WINDOW` | Positive integer (tokens) | `131072` |
| `NEMOCLAW_MAX_TOKENS` | Positive integer (tokens) | `4096` |
| `NEMOCLAW_REASONING` | `true` or `false` | `false` |
| `NEMOCLAW_INFERENCE_INPUTS` | `text` or `text,image` | `text` |
| `NEMOCLAW_AGENT_TIMEOUT` | Positive integer (seconds) | `600` |
| `NEMOCLAW_AGENT_HEARTBEAT_EVERY` | Go-style duration (`30m`, `1h`, `0m` to disable) | `unset` (OpenClaw default) |
NemoClaw ignores invalid values and bakes the default into the image.
For Local Ollama, onboarding loads the selected model first and uses Ollama's reported runtime context length when `NEMOCLAW_CONTEXT_WINDOW` is unset.
For local vLLM, onboarding uses the runtime `max_model_len` value when the server reports one and `NEMOCLAW_CONTEXT_WINDOW` is unset.
Use `NEMOCLAW_INFERENCE_INPUTS=text,image` only for a model that accepts image input through the selected provider.
During interactive onboarding, NemoClaw prompts for **Text only** or **Text + Image** when the discovered model name looks multimodal and `NEMOCLAW_INFERENCE_INPUTS` is not already valid.
Non-interactive onboarding uses the environment value or the default `text` setting.
```bash
export NEMOCLAW_CONTEXT_WINDOW=65536
export NEMOCLAW_MAX_TOKENS=8192
export NEMOCLAW_REASONING=true
export NEMOCLAW_INFERENCE_INPUTS=text,image
export NEMOCLAW_AGENT_TIMEOUT=1800
export NEMOCLAW_AGENT_HEARTBEAT_EVERY=0m
nemoclaw onboard
```
<AgentOnly variant="openclaw">
`NEMOCLAW_AGENT_TIMEOUT` controls the per-request inference timeout baked into `agents.defaults.timeoutSeconds`.
Increase it for slow local inference, such as CPU-only Ollama or vLLM on modest hardware.
NemoClaw writes this value into `openclaw.json` during onboarding.
The default sandbox can keep that file writable for agent state, but direct in-sandbox edits are not the supported or durable way to change NemoClaw-managed defaults.
Rebuild the sandbox with `nemoclaw onboard` to apply a new value.
</AgentOnly>
<AgentOnly variant="hermes">
`NEMOCLAW_AGENT_TIMEOUT` controls the per-request inference timeout baked into the Hermes sandbox image.
Increase it for slow local inference, such as CPU-only Ollama or vLLM on modest hardware.
Direct in-sandbox edits are not the supported or durable way to change NemoClaw-managed defaults.
Rebuild the sandbox with `nemoclaw onboard` to apply a new value.
</AgentOnly>
<AgentOnly variant="openclaw">
`NEMOCLAW_AGENT_HEARTBEAT_EVERY` sets `agents.defaults.heartbeat.every`.
This controls OpenClaw's periodic main-session agent turn.
Each interval, the agent wakes up to review follow-ups and read `HEARTBEAT.md` if present in the workspace.
The OpenClaw default is 30 minutes (1 hour for Anthropic OAuth / Claude CLI reuse).
Tune the cadence with a duration string like `5m` or `2h`, or set `0m` to disable the periodic turns entirely.
Disabling also drops `HEARTBEAT.md` from normal-run bootstrap context per upstream behavior, so the model no longer sees heartbeat-only instructions.
NemoClaw writes this value into `openclaw.json` during onboarding.
The in-sandbox `openclaw config set` command is not the supported path for NemoClaw-managed build-time defaults, and a rebuild overwrites direct file edits.
Rebuild the sandbox with `nemoclaw onboard --resume` to apply a new value.
</AgentOnly>
<AgentOnly variant="hermes">
Hermes does not use OpenClaw's `HEARTBEAT.md` wake-up mechanism.
Rebuild the sandbox with `nemoclaw onboard --resume` to apply build-time inference metadata changes.
</AgentOnly>
These variables are build-time settings.
If you change them on an existing sandbox, recreate the sandbox so the new values bake into the image:
```bash
nemoclaw onboard --resume --recreate-sandbox
```
## Verify the Active Model
Use `nemoclaw inference get` to print the provider and model the gateway is currently routing to.
Run it before `nemoclaw inference set` to confirm the starting state, or after a switch to verify the new route.
```bash
nemoclaw inference get
```
Expected output:
```text
Provider: nvidia-prod
Model: nvidia/nemotron-3-super-120b-a12b
```
Pass `--json` for machine-readable output.
```bash
nemoclaw inference get --json
```
Expected output:
```json
{
"provider": "nvidia-prod",
"model": "nvidia/nemotron-3-super-120b-a12b"
}
```
The command exits non-zero with `OpenShell inference route is not configured.` when the gateway has no registered inference route.
Run `nemoclaw onboard` to configure one.
Run the status command when you also need sandbox, service, and messaging health:
```bash
nemoclaw <name> status
```
The status output includes the active provider, model, and endpoint with the rest of the sandbox state.
## Notes
<AgentOnly variant="openclaw">
- The host keeps provider credentials.
- The sandbox continues to use `inference.local`.
- `nemoclaw inference set` patches the selected running OpenClaw or Hermes sandbox config and recomputes its config hash.
- Use `nemoclaw onboard --resume --recreate-sandbox` for build-time settings such as context window, max tokens, reasoning mode, heartbeat cadence, or image contents.
- Local Ollama and local vLLM routes use local provider tokens rather than `OPENAI_API_KEY`. Rebuilds of older local-inference sandboxes clear the stale OpenAI credential requirement automatically.
</AgentOnly>
<AgentOnly variant="hermes">
- The host keeps provider credentials.
- The sandbox continues to use `inference.local`.
- `nemoclaw inference set` patches the selected running Hermes sandbox config and recomputes its config hash.
- Use `nemoclaw onboard --resume --recreate-sandbox` for build-time settings such as context window, max tokens, reasoning mode, heartbeat cadence, or image contents.
- Local Ollama and local vLLM routes use local provider tokens rather than `OPENAI_API_KEY`. Rebuilds of older local-inference sandboxes clear the stale OpenAI credential requirement automatically.
</AgentOnly>
## Related Topics
- [Inference Options](inference-options.md) for the full list of providers available during onboarding.

154
.agents/skills/nemoclaw-user-configure-inference/references/tool-calling-reliability.md
View file

@ -1,154 +0,0 @@
# Tool-Calling Reliability for Local Inference
Local inference is useful for privacy, cost control, and offline development, but tool-calling agents place stricter demands on the model server than simple chat.
The model server must return structured `tool_calls`, not a JSON-looking string inside normal assistant text.
Use this page when the TUI shows raw JSON such as:
```json
{"arguments":{"query":"robotics"},"name":"memory_search"}
```
If that appears as text in the assistant reply, OpenClaw cannot dispatch the tool because the inference response did not include a structured tool call.
## Quick Choice Guide
| Workload | Ollama is usually sufficient | Prefer vLLM with a parser |
|---|---|---|
| Plain chat | Yes | Optional |
| Embeddings-only or retrieval setup | Yes | Optional |
| One simple tool with short prompts | Often | Optional |
| Agent loops with several tools | Risky | Yes |
| Long system prompts or sender metadata | Risky | Yes |
| Multi-turn tool dispatch | Risky | Yes |
Ollama can work well for lightweight local chat and some simple tool surfaces.
For OpenClaw-style agent loops with multiple tools, long instructions, or multi-turn dispatch, use a server that exposes OpenAI-compatible `/v1/chat/completions` with a tool-call parser.
vLLM is the common local choice.
## Symptom
The common failure mode is:
- The model emits text that looks like a tool call.
- The response does not include a structured `tool_calls` field.
- The gateway treats the response as normal text.
- No tool runs, and the user sees raw JSON in the TUI.
This is different from a network or policy block.
`nemoclaw <name> status`, `nemoclaw <name> logs`, and `nemoclaw debug --quick` can all look healthy while tool dispatch still fails inside the conversation.
### Nemotron Managed Inference
For the `nvidia/nemotron-3-super-120b-a12b` managed inference route on `inference.local`, NemoClaw disables OpenClaw's native code-based tool search surface.
That route otherwise tends to generate invalid JavaScript for the `tool_search_code` helper, which creates `[tools] tool_search_code failed` noise even when normal turns succeed.
The agent still uses the structured tool-calling surface that the model handles correctly.
## Recommended Fix
For persistent NemoClaw use, start vLLM with auto tool choice and the parser that matches your model family, then rerun onboarding and select **Local vLLM [experimental]** or **Other OpenAI-compatible endpoint**.
For Hermes 3 style models, a known-good vLLM command shape is:
```bash
vllm serve /models/Hermes-3-Llama-3.1-8B \
--served-model-name hermes-3-llama-3.1-8b \
--enable-auto-tool-choice \
--tool-call-parser hermes \
--port 8000
```
For a Docker Compose setup:
```yaml
services:
vllm-nemoclaw:
image: vllm/vllm-openai:latest
container_name: vllm-nemoclaw
restart: unless-stopped
ports:
- "8002:8000"
volumes:
- /path/to/models:/models:ro
- /path/to/hf-cache:/root/.cache/huggingface
ipc: host
deploy:
resources:
reservations:
devices:
- capabilities: [gpu]
count: all
command: >
--model /models/Hermes-3-Llama-3.1-8B
--served-model-name hermes-3-llama-3.1-8b
--enable-auto-tool-choice
--tool-call-parser hermes
--gpu-memory-utilization 0.20
--max-model-len 32768
--api-key ${VLLM_API_KEY}
```
Then onboard against that endpoint:
```bash
NEMOCLAW_PROVIDER=custom \
NEMOCLAW_ENDPOINT_URL=http://localhost:8002/v1 \
NEMOCLAW_MODEL=hermes-3-llama-3.1-8b \
COMPATIBLE_API_KEY=$VLLM_API_KEY \
nemoclaw onboard --non-interactive
```
If the endpoint does not require authentication, set `COMPATIBLE_API_KEY` to any non-empty placeholder, such as `dummy`.
## Advanced Temporary Repointing
NemoClaw-managed sandboxes normally block direct `openclaw config set` writes inside the sandbox because those edits do not survive rebuilds.
Prefer rerunning `nemoclaw onboard` for a persistent provider change.
If you are intentionally testing a mutable OpenClaw config, prepare a batch file
like this:
```json
{
"models": {
"providers": {
"vllm-local": {
"baseUrl": "http://host.openshell.internal:8002/v1",
"api": "openai",
"apiKey": "${VLLM_API_KEY}"
}
}
},
"agents": {
"defaults": {
"model": {
"primary": "vllm-local/hermes-3-llama-3.1-8b"
}
}
}
}
```
Apply it only in environments where OpenClaw allows config writes:
```bash
openclaw config set --batch-file /sandbox/.openclaw/vllm-tool-calls.json
```
After testing, persist the working provider through `nemoclaw onboard` so the sandbox image, OpenShell inference route, and host-managed credentials stay in sync.
## Verify the Fix
After switching to vLLM, ask for an action that should use a tool. Good signs:
- The TUI does not show JSON blobs as assistant text.
- The gateway log shows tool dispatch and a follow-up answer.
- `nemoclaw <name> status` reports the local vLLM or compatible endpoint as the active provider.
If JSON still appears as text, confirm that you started vLLM with both `--enable-auto-tool-choice` and the correct `--tool-call-parser` value for your model.
## Next Steps
- [Use a Local Inference Server](../SKILL.md)
- [Inference Options](inference-options.md)
- [Switch Inference Models](switch-inference-providers.md)

13
.agents/skills/nemoclaw-user-configure-security/SKILL.md
View file

@ -1,13 +0,0 @@
---
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. Trigger keywords - nemoclaw security best practices, sandbox security controls risk framework, nemoclaw credential storage, openshell provider, api key security, openclaw security controls, nemoclaw security boundary, prompt injection, tool access control."
license: "Apache-2.0"
---
# NemoClaw User Configure Security
## References
- **Load [references/best-practices.md](references/best-practices.md)** when evaluating security posture, reviewing sandbox security defaults, or assessing control trade-offs. Presents a risk framework for every configurable security control in NemoClaw.
- **Load [references/credential-storage.md](references/credential-storage.md)** when reviewing how credentials are handled, locating a stored credential, or assessing the storage threat model. Covers where NemoClaw stores provider credentials, why nothing is persisted to host disk, and how the OpenShell gateway acts as the single system of record.
- **Load [references/openclaw-controls.md](references/openclaw-controls.md)** when reviewing the security boundary between NemoClaw and OpenClaw or assessing what NemoClaw does not cover. Lists OpenClaw security controls that operate independently of NemoClaw, including prompt injection detection, tool access control, rate limiting, environment variable policy, audit framework, supply chain scanning, messaging access policy, context visibility, and safe regex.

11
.agents/skills/nemoclaw-user-configure-security/evals/evals.json
View file

@ -1,11 +0,0 @@
[
{
"id": "docs-security-best-practices-001",
"question": "I'm evaluating NemoClaw security best practices. Help me understand the risk posture of each configurable control so I can justify the setup to my team or security reviewers.",
"expected_skill": "nemoclaw-user-configure-security",
"ground_truth": "A NemoClaw-specific answer that helps the user understand the risk posture of each configurable control and gives enough concrete guidance, decision criteria, verification steps, or risk framing to justify the setup to my team or security reviewers.",
"expected_behavior": [
"Uses the expected_skill and does not make up answers if it cannot find the answer from the skill."
]
}
]

602
.agents/skills/nemoclaw-user-configure-security/references/best-practices.md
View file

@ -1,602 +0,0 @@
# NemoClaw Security Best Practices: Controls, Risks, and Posture Profiles
import { AgentOnly } from "../_components/AgentGuide";
NemoClaw ships with deny-by-default security controls across five layers: network, filesystem, process, gateway authentication, and inference.
You can tune every control, but each change shifts the risk profile.
This page documents each configurable control, 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 (use the `nemoclaw-user-overview` skill).
## Protection Layers at a Glance
NemoClaw enforces security at five layers.
NemoClaw locks some controls when it creates the sandbox and requires a restart to change them.
You can hot-reload others while the sandbox runs.
The following diagram shows the default posture immediately after onboarding, before you approve any endpoints or apply any presets.
```mermaid
flowchart TB
subgraph HOST["Your Machine: default posture after onboarding"]
direction TB
YOU["👤 Operator"]
subgraph NC["NemoClaw + OpenShell"]
direction TB
subgraph SB["Sandbox: the agent's isolated world"]
direction LR
PROC["⚙️ Process Layer<br/>Controls what the agent can execute"]
FS["📁 Filesystem Layer<br/>Controls what the agent can read and write"]
AGENT["🤖 Agent"]
end
subgraph GW["Gateway: the gatekeeper"]
direction LR
NET["🌐 Network Layer<br/>Controls where the agent can connect"]
AUTH["🔐 Gateway Authentication Layer<br/>Controls which devices and clients can reach the gateway"]
INF["🧠 Inference Layer<br/>Controls which AI models the agent can use"]
end
end
end
OUTSIDE["🌍 Outside World<br/>Internet · AI Providers · APIs"]
AGENT -- "all requests" --> GW
GW -- "approved only" --> OUTSIDE
YOU -. "approve / deny" .-> GW
classDef agent fill:#76b900,stroke:#5a8f00,color:#fff,stroke-width:2px,font-weight:bold
classDef locked fill:#1a1a1a,stroke:#76b900,color:#fff,stroke-width:2px
classDef hot fill:#333,stroke:#76b900,color:#e6f2cc,stroke-width:2px
classDef external fill:#f5f5f5,stroke:#ccc,color:#1a1a1a,stroke-width:1px
classDef operator fill:#fff,stroke:#76b900,color:#1a1a1a,stroke-width:2px,font-weight:bold
class AGENT agent
class PROC,FS,AUTH locked
class NET,INF hot
class OUTSIDE external
class YOU operator
style HOST fill:none,stroke:#76b900,stroke-width:2px,color:#1a1a1a
style NC fill:none,stroke:#76b900,stroke-width:1px,stroke-dasharray:5 5,color:#1a1a1a
style SB fill:#f5faed,stroke:#76b900,stroke-width:2px,color:#1a1a1a
style GW fill:#2a2a2a,stroke:#76b900,stroke-width:2px,color:#fff
```
| Layer | What it protects | Enforcement point | Changeable at runtime |
| --- | --- | --- | --- |
| Network | Unauthorized outbound connections and data exfiltration. | OpenShell gateway | Yes. Use `openshell policy set` or operator approval. |
| Filesystem | System binary tampering, credential theft, config manipulation. | Landlock LSM + container mounts | Landlock layout: no. Requires sandbox re-creation. Use host-side NemoClaw commands for durable config changes. |
| Process | Privilege escalation, fork bombs, syscall abuse. | Container runtime (Docker/K8s `securityContext`) | No. Requires sandbox re-creation. |
| Gateway Authentication | Unauthorized devices or clients reaching the gateway and its dashboard. | OpenShell gateway | No. Set at image build / onboarding time. |
| Inference | Credential exposure, unauthorized model access, cost overruns. | OpenShell gateway | Yes. Use the NemoClaw inference switching command. |
## Network Controls
NemoClaw controls which hosts, ports, and HTTP methods the sandbox can reach, and lets operators approve or deny requests in real time.
Network policy allowlists do not disable OpenShell's SSRF guard; see Customize the Network Policy (use the `nemoclaw-user-manage-policy` skill) for the interaction between egress rules and internal-address blocking.
### Deny-by-Default Egress
The sandbox blocks all outbound connections unless you explicitly list the endpoint in the applicable baseline policy files.
| Aspect | Detail |
|---|---|
| Default | All egress denied. Only endpoints in the baseline policy can receive traffic. |
| What you can change | Add endpoints to the policy file (static) or with `openshell policy set` (dynamic). |
| Risk if relaxed | Each allowed endpoint is a potential data exfiltration path. The agent can send workspace content, credentials, or conversation history to any reachable host. |
| Recommendation | Add only endpoints the agent needs for its task. Prefer operator approval for one-off requests over permanently widening the baseline. |
### Binary-Scoped Endpoint Rules
Each network policy entry restricts which executables can reach the endpoint using the `binaries` field.
OpenShell identifies the calling binary by reading `/proc/<pid>/exe` (the kernel-trusted executable path, not `argv[0]`), walking the process tree for ancestor binaries, and computing a SHA256 hash of each binary on first use.
If someone replaces a binary while the sandbox runs, the hash mismatch immediately denies the request.
| Aspect | Detail |
|---|---|
| Default | Each endpoint restricts access to specific binaries. For example, the `github` preset restricts access so only `/usr/bin/git` can reach `github.com`. Binary paths support glob patterns (`*` matches one path component, `**` matches recursively). |
| What you can change | Add binaries to an endpoint entry, or omit the `binaries` field to allow any executable. |
| Risk if relaxed | Removing binary restrictions lets any process in the sandbox reach the endpoint. An agent could use `curl`, `wget`, or a Python script to exfiltrate data to an allowed host, bypassing the intended usage pattern. |
| Recommendation | Always scope endpoints to the binaries that need them. If the agent needs a host from a new binary, add that binary explicitly rather than removing the restriction. |
### Path-Scoped HTTP Rules
Endpoint rules restrict allowed HTTP methods and URL paths.
| Aspect | Detail |
|---|---|
| Default | Some endpoints allow GET and POST on `/**` (for example, `clawhub.ai`). Others restrict methods and paths to specific API routes (for example, `integrate.api.nvidia.com` allows POST only to inference and embedding paths and GET to model listings). Read-only endpoints such as `docs.openclaw.ai`, the `npm_registry` baseline entry, and the `pypi` preset allow GET only (PyPI also allows HEAD). The `npm` preset is an intentional exception: npm/Yarn registry traffic uses L4 pass-through for Node 22 undici CONNECT compatibility. |
| What you can change | Add methods (PUT, DELETE, PATCH) or restrict paths to specific prefixes. |
| Risk if relaxed | Allowing all methods on an API endpoint gives the agent write and delete access. For example, allowing DELETE on `api.github.com` lets the agent delete repositories. |
| Recommendation | Use GET-only rules for endpoints that the agent only reads. Add write methods only for endpoints where the agent must create or modify resources. Restrict paths to specific API routes when possible. |
### L4-Only vs L7 Inspection (`protocol` Field)
All sandbox egress goes through OpenShell's CONNECT proxy.
The `protocol` field on an endpoint controls whether the proxy also inspects individual HTTP requests inside the tunnel.
| Aspect | Detail |
|---|---|
| Default | Endpoints without a `protocol` field use L4-only enforcement: the proxy checks host, port, and binary identity, then relays the TCP stream without inspecting payloads. Setting `protocol: rest` enables L7 inspection: the proxy auto-detects and terminates TLS, then evaluates each HTTP request's method and path against the endpoint's `rules` or `access` preset. |
| What you can change | Add `protocol: rest` to an endpoint to enable per-request HTTP inspection. Use the `access` preset (`full`, `read-only`, `read-write`) or explicit `rules` to control allowed methods and paths. |
| Risk if relaxed | L4-only endpoints (no `protocol` field) allow the agent to send any data through the tunnel after the initial connection is permitted. The proxy cannot see or filter the HTTP method, path, or body. The `access: full` preset with `protocol: rest` enables inspection but allows all methods and paths, so it does not restrict what the agent can do at the HTTP level. |
| Recommendation | Use `protocol: rest` with specific `rules` for REST APIs where you want method and path control. Use `protocol: rest` with `access: read-only` for read-only endpoints. Omit `protocol` only for non-HTTP protocols (WebSocket, gRPC streaming), endpoints that do not need HTTP inspection, or documented compatibility exceptions that require a client-managed CONNECT tunnel. |
### Operator Approval Flow
When the agent reaches an unlisted endpoint, OpenShell blocks the request and prompts you in the TUI.
| Aspect | Detail |
|---|---|
| Default | Enabled. The gateway blocks all unlisted endpoints and requires approval. |
| What you can change | The system merges approved endpoints into the sandbox's policy as a new durable revision. They persist across sandbox restarts within the same sandbox instance. However, when you destroy and recreate the sandbox through onboarding, the policy resets to the baseline defined in the blueprint. |
| Risk if relaxed | Approving an endpoint permanently widens the running sandbox's policy. If you approve a broad domain (such as a CDN that hosts arbitrary content), the agent can fetch anything from that domain until you destroy and recreate the sandbox. |
| Recommendation | Review each blocked request before approving. If you find yourself approving the same endpoint repeatedly, add it to the baseline policy with appropriate binary and path restrictions. To reset approved endpoints, destroy and recreate the sandbox. |
### Policy Presets
NemoClaw ships preset policy files in `nemoclaw-blueprint/policies/presets/` for common integrations.
| Preset | What it enables | Key risk |
|---|---|---|
| `brave` | Brave Search API. | Agent can issue search queries. |
| `brew` | Homebrew (Linuxbrew) package manager. The sandbox base image includes the `brew` binary; this preset opens network egress to GitHub and the Homebrew formulae index so `brew install` can fetch bottles. | Allows installing arbitrary Homebrew packages, which may contain malicious code. |
| `claude-code` | Claude Code CLI API, telemetry, and crash-report endpoints. | Allows a separately installed Claude Code CLI to reach Anthropic and telemetry hosts with its own credentials. Do not use this preset for NemoClaw inference routing. |
| `discord` | Discord REST API, WebSocket gateway, CDN. | CDN endpoint (`cdn.discordapp.com`) allows GET to any path. WebSocket uses `access: full` (no inspection). |
| `github` | GitHub and GitHub REST API. | Gives agent read/write access to repositories and issues via `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. |
| `slack` | Slack API, Socket Mode, webhooks. | WebSocket uses `access: full`. Agent can post to any channel the bot token has access to. |
| `telegram` | Telegram Bot API. | Agent can send messages to any chat the bot token has access to. |
**Recommendation:** Apply presets only when the agent's task requires the integration. Review the preset's YAML file before applying to understand the endpoints, methods, and binary restrictions it adds.
## Filesystem Controls
NemoClaw restricts which paths the agent can read and write, protecting system binaries, configuration files, and gateway credentials.
### Read-Only System Paths
The container mounts system directories read-only to prevent the agent from modifying binaries, libraries, or configuration files.
| Aspect | Detail |
|---|---|
| Default | `/usr`, `/lib`, `/proc`, `/dev/urandom`, `/app`, `/etc`, `/var/log` are read-only. |
| What you can change | Add or remove paths in the `filesystem_policy.read_only` section of the policy file. |
| Risk if relaxed | Making `/usr` or `/lib` writable lets the agent replace system binaries (such as `curl` or `node`) with trojanized versions. Making `/etc` writable lets the agent modify DNS resolution, TLS trust stores, or user accounts. |
| Recommendation | Never make system paths writable. If the agent needs a writable location for generated files, use a subdirectory of `/sandbox`. |
### Agent Config Directory
<AgentOnly variant="openclaw">
The `/sandbox/.openclaw` directory contains the OpenClaw gateway configuration (model routing, CORS settings, channel config).
The current entrypoint reads the gateway auth token from OpenClaw config when present, exports it as `OPENCLAW_GATEWAY_TOKEN`, and writes it to `/tmp/nemoclaw-proxy-env.sh` so interactive sandbox sessions can reach the gateway through system-wide shell hooks.
In root mode, the gateway process still runs as the separate `gateway` user, but the token is intentionally available to sandbox shells for local gateway access.
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.
For sensitive workloads, use a reviewed host-side immutability workflow after initial setup so the sandbox user cannot change config and high-risk state entry points.
The immutability workflow locks high-risk state directories (`skills`, `hooks`, `cron`, `agents`, `extensions`, `plugins`, `workspace`, `memory`, `devices`, `canvas`, `telegram`, `wechat`, `whatsapp`, `platforms`, `weixin`, `profiles`, `skins`) to `root:sandbox` with `chmod -R go-w`.
The OpenClaw gateway (a member of the `sandbox` group) keeps read access to plugin and agent code; the sandbox user can no longer write them.
The same workflow also locks the secret-bearing directories (`credentials`, `identity`, `pairing`) to `root:root 700` with `chmod -R go-rwX`.
Neither the sandbox user nor the gateway can read those secrets while the lock is active.
Restoring the mutable-default posture returns both groups to `sandbox:sandbox 2770`.
The list is the union of state directories declared by every shipped agent manifest; the lock helper silently skips dirs that aren't present in a given agent's config tree.
Two exemption kinds keep runtime data writable.
The lock inventory omits top-level Hermes runtime dirs (`sessions/`, `memories/`, `logs/`, `cache/`, `plans/`) and the image-build-regenerated `openclaw-weixin/`; the lock helper never touches those paths.
Inside a locked tree, the helper restores `agents/<agent-id>/sessions/` to `sandbox:sandbox 2770` after the surrounding `agents/` lock so the OpenClaw TUI can create and write session metadata under an otherwise root-owned parent.
If any high-risk state-dir root is a symlink when the lock runs, the lock helper refuses to proceed and reports "Config not locked: state dir root is a symlink" instead of following the link with privileged `chown -R` / `chmod -R`.
- **DAC permissions (default).** The sandbox user owns `/sandbox/.openclaw` with mode `2770` (setgid `sandbox:sandbox`) and `openclaw.json` with mode `660`, so the agent and its group can read and write config directly. A reviewed host-side immutability workflow should compare the intended ownership and mode with the live sandbox filesystem before treating the config tree as locked.
- **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.
- **Content integrity seal.**
A clean immutable config lock can capture a SHA-256 seal of `openclaw.json` and other locked files into host-side state.
Verification recomputes hashes inside the sandbox and surfaces drift on mismatch, so a host-root tamper that flips permissions back to `444 root:root` after rewriting the file is still flagged.
Sandboxes locked before the seal landed have no recorded hash; permission-only verification cannot prove their bytes match the image original, so the seal is **not** a retroactive proof of integrity for legacy state.
The same limitation applies when the locked file set grew after the existing seal was captured.
Rebuild the sandbox for a known-good baseline before trusting a new seal.
- **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 (`2770 sandbox:sandbox`), sets `openclaw.json` to `660 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 | 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, lock config after initial setup. For development workflows, the writable default is appropriate. |
</AgentOnly>
<AgentOnly variant="hermes">
The `/sandbox/.hermes` directory contains Hermes runtime configuration, generated environment settings, logs, platform state, and durable database state.
NemoClaw writes `config.yaml` and `.env` during onboarding and rebuilds.
Direct edits to these files can be overwritten when NemoClaw regenerates the image.
Hermes also stores runtime state such as `state.db`, logs, and platform sessions under the `.hermes` tree.
Messaging sessions such as WhatsApp pairing can remain mutable by design so they survive rebuilds.
| Aspect | Detail |
|---|---|
| Default | The Hermes config tree contains NemoClaw-generated config plus mutable runtime state. |
| What you can change | Use host-side NemoClaw commands for durable model, provider, messaging, and policy changes; inspect files directly only for debugging. |
| Risk of direct edits | Direct edits to generated config can drift from the host registry and may be lost on rebuild. |
| Recommendation | For sensitive workloads, keep generated config under NemoClaw control and back up Hermes state before destructive operations. |
</AgentOnly>
### Writable Paths
The agent has read-write access to `/sandbox`, `/tmp`, `/dev/null`, and `/dev/pts`.
| Aspect | Detail |
|---|---|
| Default | `/sandbox` (agent workspace), `/tmp` (temporary files), `/dev/null`, and `/dev/pts` (the devpts pseudo-terminal directory, required so PTY-based tools such as `tmux`, `script`, and interactive shells can allocate a terminal). |
| What you can change | Add additional writable paths in `filesystem_policy.read_write`. |
| Risk if relaxed | Each additional writable path expands the agent's ability to persist data and potentially modify system behavior. Adding `/var` lets the agent write to log directories. Adding `/home` gives access to other user directories. |
| Recommendation | Keep writable paths to `/sandbox` and `/tmp`. If the agent needs a persistent working directory, create a subdirectory under `/sandbox`. |
### Landlock LSM Enforcement
Landlock is a Linux Security Module that enforces filesystem access rules at the kernel level.
| Aspect | Detail |
|---|---|
| Default | `compatibility: best_effort`. The entrypoint applies Landlock rules when the kernel supports them and silently skips them on older kernels. |
| What you can change | This is a NemoClaw default, not a user-facing knob. |
| Risk if relaxed | On kernels without Landlock support (pre-5.13), filesystem restrictions rely solely on container mount configuration, which is less granular. |
| Recommendation | Run on a kernel that supports Landlock (5.13+). Ubuntu 22.04 LTS and later include Landlock support. |
## Process Controls
NemoClaw limits the capabilities, user privileges, and resource quotas available to processes inside the sandbox.
### Capability Drops
The entrypoint drops dangerous Linux capabilities from the bounding set at startup using `capsh`.
This limits what capabilities any child process (gateway, sandbox, agent) can ever acquire.
When the entrypoint switches from root to the `sandbox` and `gateway` users, it uses `setpriv` when available to remove the remaining privilege-separation capabilities from the child process at the same time as the user change.
The initial entrypoint drop removes `cap_sys_admin`, `cap_sys_ptrace`, `cap_net_raw`, `cap_dac_override`, `cap_sys_chroot`, `cap_fsetid`, `cap_setfcap`, `cap_mknod`, `cap_audit_write`, and `cap_net_bind_service`.
During `setpriv` step-down, the child process also loses `cap_setuid`, `cap_setgid`, `cap_fowner`, `cap_chown`, and `cap_kill`.
This behavior is best effort: if `capsh` is not available or `CAP_SETPCAP` is not in the bounding set, the entrypoint logs a warning and continues with the default capability set.
If `setpriv` is unavailable, the entrypoint falls back to `gosu` and logs a warning that the remaining bounding-set capabilities were retained for the child process.
To make the drop fail-closed instead of best-effort, set `NEMOCLAW_REQUIRE_CAP_DROP=1` in the entrypoint environment.
The agent then refuses to start unless the agent process tree's bounding set is verified free of the dangerous capabilities, so it will not boot on a host whose bounding set still holds them — typically one that cannot perform the drop (no `CAP_SETPCAP`, or `capsh` missing) and was not given a clean bounding set by the container runtime.
This is opt-in because such hosts are common (many cloud VMs, Docker Desktop, WSL); leaving it unset preserves the best-effort default.
The check covers the agent process tree only — a `nemoclaw connect` shell is spawned by the container runtime outside that tree and is not affected (tracked in [NVIDIA/OpenShell#1452](https://github.com/NVIDIA/OpenShell/issues/1452)).
<AgentOnly variant="openclaw">
For additional protection, pass `--cap-drop=ALL` with `docker run` or Compose. Refer to Sandbox Hardening (use the `nemoclaw-user-deploy-remote` skill).
</AgentOnly>
| Aspect | Detail |
|---|---|
| Default | The entrypoint drops dangerous capabilities at startup using `capsh`, then uses `setpriv` during user step-down when possible. Best-effort. |
| What you can change | When launching with `docker run` directly, pass `--cap-drop=ALL --cap-add=NET_BIND_SERVICE` for stricter enforcement. In the standard NemoClaw onboarding flow, the entrypoint handles capability dropping automatically. |
| Risk if relaxed | `CAP_SYS_ADMIN` and `CAP_SYS_PTRACE` expand kernel and process attack surface. `CAP_NET_RAW` allows raw socket access for network sniffing. `CAP_DAC_OVERRIDE` bypasses filesystem permission checks. If `capsh` or `setpriv` cannot run, the container retains more of the runtime-provided capability set. |
| Recommendation | Run on an image that includes `capsh` and `setpriv` (the NemoClaw image includes them). For defense-in-depth, also pass `--cap-drop=ALL` at the container runtime level. |
### Gateway Process Isolation
The in-sandbox gateway runs as a separate `gateway` user, not as the `sandbox` user that runs the agent.
| Aspect | Detail |
|---|---|
| Default | The entrypoint starts the gateway process using `gosu gateway`, isolating it from the agent's `sandbox` user. |
| What you can change | This is not a user-facing knob. The entrypoint enforces it when running as root. In non-root mode (when OpenShell sets `no-new-privileges`), gateway process isolation does not work because `gosu` cannot change users. |
| Risk if relaxed | If the gateway and agent run as the same user, the agent can kill the gateway process and restart it with a tampered configuration (the "fake-HOME" attack). |
| Recommendation | No action needed. The entrypoint handles this automatically. Be aware that non-root mode disables this isolation. |
### No New Privileges
The `no-new-privileges` flag prevents processes from gaining additional privileges through setuid binaries or capability inheritance.
| Aspect | Detail |
|---|---|
| Default | OpenShell sets `PR_SET_NO_NEW_PRIVS` using `prctl()` inside the sandbox process as part of the seccomp filter setup. The NemoClaw Compose example also shows the equivalent `security_opt: no-new-privileges:true` setting. |
| What you can change | OpenShell's seccomp path enforces this inside the sandbox. It is not a user-facing knob. |
| Risk if relaxed | Without this flag, a compromised process could execute a setuid binary to escalate to root inside the container, then attempt container escape techniques. |
| Recommendation | No action needed. OpenShell enforces this automatically when the sandbox network policy is active. This flag prevents `gosu` from switching users, so non-root mode disables gateway process isolation in the NemoClaw entrypoint. |
### Process Limit
A process limit caps the number of processes the sandbox user can spawn.
The entrypoint sets both soft and hard limits using `ulimit -u 512`.
This behavior is best effort: if the container runtime restricts `ulimit` modification, the entrypoint logs a security warning and continues without the limit.
| Aspect | Detail |
|---|---|
| Default | 512 processes (`ulimit -u 512`), best-effort. |
| What you can change | Increase or decrease the limit with `--ulimit nproc=N:N` in `docker run` or the `ulimits` section in Compose. The runtime-level ulimit takes precedence over the entrypoint's setting. |
| Risk if relaxed | Removing or raising the limit makes the sandbox vulnerable to fork-bomb attacks, where a runaway process spawns children until the host runs out of resources. If the entrypoint cannot set the limit (logs `[SECURITY] Could not set soft/hard nproc limit`), the container runs without process limits. |
| Recommendation | Keep the default at 512. If the agent runs workloads that spawn many child processes (such as parallel test runners), increase to 1024 and monitor host resource usage. If the entrypoint logs a warning about ulimit restrictions, set the limit through the container runtime instead. |
### Open File Descriptor Limit
An open file descriptor limit caps the number of files, sockets, and pipes the
sandbox user can hold open at once. The entrypoint sets both soft and hard
limits using `ulimit -n 65536`. This is best-effort: if the container runtime
restricts `ulimit` modification, the entrypoint logs a security warning and
continues without the limit.
| Aspect | Detail |
|---|---|
| Default | 65536 open files, soft and hard (`ulimit -n 65536`), best-effort. |
| What you can change | Increase or decrease the limit with `--ulimit nofile=N:N` in `docker run` or the `ulimits` section in Compose. The runtime-level ulimit takes precedence over the entrypoint's setting. |
| Risk if relaxed | Without this cap the sandbox inherits the Docker daemon default (`nofile` ~1048576). A runaway or hostile process can then open file descriptors until it exhausts them — a denial-of-service that can starve the gateway, the agent, or the host of file handles. If the entrypoint cannot set the limit (logs `[SECURITY] Could not set soft/hard nofile limit`), the container runs without a file-descriptor cap. Ref [#4527](https://github.com/NVIDIA/NemoClaw/issues/4527). |
| Recommendation | Keep the default at 65536. If the agent legitimately keeps many connections or files open, raise it deliberately and monitor host file-descriptor usage. If the entrypoint logs a warning about ulimit restrictions, set the limit through the container runtime instead. |
### Non-Root User
The sandbox runs agent processes as a dedicated `sandbox` user and group.
The entrypoint starts as root for privilege separation, then drops to the `sandbox` user for all agent commands.
| Aspect | Detail |
|---|---|
| Default | `run_as_user: sandbox`, `run_as_group: sandbox`. A separate `gateway` user runs the gateway process. |
| What you can change | Change the `process` section in the policy file to run as a different user. |
| Risk if relaxed | Running as `root` inside the container gives the agent access to modify any file in the container filesystem and increases the impact of container escape vulnerabilities. |
| Recommendation | Never run as root. Keep the `sandbox` user. |
### PATH Hardening
The entrypoint locks the `PATH` environment variable to system directories, preventing the agent from injecting malicious binaries into command resolution.
| Aspect | Detail |
|---|---|
| Default | The entrypoint sets `PATH` to `/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin` at startup. |
| What you can change | This is not a user-facing knob. The entrypoint enforces it. |
| Risk if relaxed | Without PATH hardening, the agent could create an executable named `curl` or `git` in a writable directory earlier in the PATH, intercepting commands run by the entrypoint or other processes. |
| Recommendation | No action needed. The entrypoint handles this automatically. |
### Build Toolchain Removal
The Dockerfile removes compilers and network probes from the runtime image.
| Aspect | Detail |
|---|---|
| Default | The Dockerfile purges `gcc`, `gcc-12`, `g++`, `g++-12`, `cpp`, `cpp-12`, `make`, `netcat-openbsd`, `netcat-traditional`, and `ncat` from the sandbox image. |
| What you can change | Modify the Dockerfile to keep these tools, or install them at runtime if package manager access is allowed. |
| Risk if relaxed | A compiler lets the agent build arbitrary native code, including kernel exploits or custom network tools. `netcat` enables arbitrary TCP connections that bypass HTTP-level policy enforcement. |
| Recommendation | Keep build tools removed. If the agent needs to compile code, run the build in a separate, purpose-built container and copy artifacts into the sandbox. |
### Image Digest Pinning
The blueprint references the sandbox image by an immutable `@sha256:` digest instead of a mutable tag such as `:latest`.
A registry compromise or accidental force-push cannot silently swap the sandbox image.
| Aspect | Detail |
|---|---|
| Default | `nemoclaw-blueprint/blueprint.yaml` pins the sandbox image by digest. A CI regression test blocks any mutable-tag reference from merging. |
| What you can change | Contributors bumping the sandbox image must update the digest in `blueprint.yaml`. Release tooling should rewrite the digest automatically. |
| Risk if relaxed | Reverting to a mutable tag (`:latest`) allows a registry-side change to replace the sandbox image without any blueprint update, which is a supply-chain risk. |
| Recommendation | Always reference the sandbox image by digest. If you build a custom image with the onboarding `--from` path, the digest constraint does not apply to your local build. |
### Auth Profile Permissions
The entrypoint and migration flows enforce `chmod 600` on all `auth-profiles.json` files under `~/.openclaw`.
This prevents other users on the host from reading stored credentials.
| Aspect | Detail |
|---|---|
| Default | `600` permissions applied recursively at startup and after migration restores. |
| What you can change | This is not a user-facing knob. The entrypoint enforces it. |
| Risk if relaxed | Looser permissions let other users or processes on the host read provider API keys and tokens stored in auth profiles. |
| Recommendation | No action needed. If you see a `permission denied` error when reading auth profiles, verify that you are running as the same user who created them. |
## Gateway Authentication Controls
<AgentOnly variant="openclaw">
The OpenClaw gateway authenticates devices that connect to the Control UI dashboard.
NemoClaw hardens these defaults at image build time.
### Device Authentication
Device authentication requires each connecting device to go through a pairing flow before it can interact with the gateway.
| Aspect | Detail |
|---|---|
| Default | Enabled. The gateway requires device pairing for all connections. |
| What you can change | Set `NEMOCLAW_DISABLE_DEVICE_AUTH=1` as a Docker build argument to disable device authentication. This is a build-time setting baked into `openclaw.json` and verified by hash at startup. |
| Risk if relaxed | Disabling device auth allows any device on the network to connect to the gateway without proving identity. This is dangerous when combined with LAN-bind changes or cloudflared tunnels in remote deployments, resulting in an unauthenticated, publicly reachable dashboard. |
| Recommendation | Keep device auth enabled (the default). Only disable it for headless or development environments where no untrusted devices can reach the gateway. |
### Gateway Bind Address
NemoClaw binds the OpenShell gateway to loopback by default.
| Aspect | Detail |
|---|---|
| Default | `NEMOCLAW_GATEWAY_BIND_ADDRESS=127.0.0.1`. |
| What you can change | Set `NEMOCLAW_GATEWAY_BIND_ADDRESS=0.0.0.0` before onboarding to listen on all IPv4 interfaces. |
| Risk if relaxed | Other hosts on the network may be able to reach the OpenShell gateway. |
| Recommendation | Keep the loopback default unless the gateway must be reachable from another host. |
### Insecure Auth Derivation
The `allowInsecureAuth` setting controls whether the gateway permits non-HTTPS authentication.
| Aspect | Detail |
|---|---|
| Default | Derived from the `CHAT_UI_URL` scheme at build time. When the URL uses `http://` (local development), insecure auth is allowed. When it uses `https://` (remote or production), insecure auth is blocked. |
| What you can change | This is derived automatically from `CHAT_UI_URL`. Set `CHAT_UI_URL` to an `https://` URL to enforce secure auth. |
| Risk if relaxed | Allowing insecure auth over HTTPS defeats the purpose of TLS, because authentication tokens transit in cleartext. |
| Recommendation | Use `https://` for any deployment accessible beyond `localhost`. The default local URL (`http://127.0.0.1:18789`) correctly allows insecure auth for local development. |
### Auto-Pair Client Allowlist
The auto-pair watcher automatically approves device pairing requests from recognized clients, so you do not need to manually approve the Control UI.
| Aspect | Detail |
|---|---|
| Default | Startup auto-pairing and `connect`-time approval share one policy. NemoClaw approves devices with `clientId` set to `openclaw-control-ui` or `clientMode` set to `webchat` or `cli`, and only for `operator.pairing`, `operator.read`, and `operator.write` scopes. All other clients or scopes are rejected and logged. |
| What you can change | This is not a user-facing knob. The allowlist is defined by NemoClaw's OpenClaw device-approval helper. |
| Risk if relaxed | Approving all device types without validation lets rogue or unexpected clients pair with the gateway unchallenged. |
| Recommendation | No action needed. NemoClaw handles this automatically at startup and during `connect` for late scope upgrades. If you see `[auto-pair] rejected unknown client=...` in the logs, investigate the source of the unexpected connection. |
</AgentOnly>
<AgentOnly variant="hermes">
Hermes exposes an OpenAI-compatible API on the forwarded Hermes port and can optionally expose the native Hermes dashboard.
Do not publish those endpoints on shared or public networks unless you put them behind your own access controls.
NemoClaw still keeps provider credentials in OpenShell and routes model traffic through `inference.local`.
Generated Hermes runtime files use OpenShell resolver placeholders for managed-tool and messaging credentials.
Hermes startup rejects raw secret-shaped values in sandbox-visible environment or config fields, while allowing empty values, migration sentinels, OpenShell resolver placeholders, and expected Slack placeholder forms.
</AgentOnly>
### CLI Secret Redaction
The CLI automatically redacts secret patterns (API keys, bearer tokens, provider credentials) from command output and error messages before logging them.
| Aspect | Detail |
|---|---|
| Default | Enabled. The runner redacts secrets from stdout, stderr, and thrown error messages. |
| What you can change | This is not a user-facing knob. The CLI enforces it on all command output paths. |
| Risk if relaxed | Without redaction, secrets could appear in terminal scrollback, log files, or debug output shared in bug reports. |
| Recommendation | No action needed. If you share NemoClaw debug output, verify that no secrets appear in the collected diagnostics. |
### Memory Secret Scanner
<AgentOnly variant="openclaw">
The NemoClaw plugin blocks the agent from writing likely secrets (API keys, tokens, private keys) into persistent memory files.
The scanner intercepts Write, Edit, and similar tool calls targeting memory and workspace paths before they reach disk.
| Aspect | Detail |
|---|---|
| Default | Enabled. The plugin registers a `before_tool_call` hook that scans for 14 high-confidence secret patterns. |
| What it covers | Three path classifiers, all enforced through `isMemoryPath()`, plus credential-shaped text such as provider API keys, OpenAI project keys with `sk-proj-` prefixes, and Slack app-level `xapp-` tokens. The path classifiers are: (1) absolute `MEMORY_PATH_SEGMENTS` such as `/.openclaw/memory/`, `/.openclaw/workspace/`, `/.openclaw/agents/`, `/.openclaw/skills/`, `/.openclaw/hooks/`, `/.openclaw/credentials/`, `/.openclaw/openclaw.json`, `/.nemoclaw/`; (2) canonical workspace basenames in `MEMORY_BASENAMES` (`IDENTITY.md`, `MEMORY.md`, `SOUL.md`, `USER.md`, `AGENTS.md`) matched regardless of the surrounding path; and (3) lexically-normalized workspace-relative writes matching `MEMORY_RELATIVE_PREFIXES` (`.openclaw/`, `.nemoclaw/`, `memory/`) or named workspace daily memory paths, for embedded-fallback mode where the host's path resolver is unavailable. |
| What you can change | This is not a user-facing knob. The plugin enforces it automatically. |
| Risk if relaxed | Without scanning, the agent could persist API keys or tokens in memory files that survive across sessions and backups. |
| Recommendation | No action needed. If a write is blocked, the agent receives an actionable error listing the detected patterns. |
</AgentOnly>
<AgentOnly variant="hermes">
Hermes does not use the OpenClaw NemoClaw plugin memory scanner.
Keep secrets in environment variables or OpenShell providers, and avoid writing raw credentials to Hermes state files or workspace content.
</AgentOnly>
## Inference Controls
OpenShell routes all inference traffic through the gateway to isolate provider credentials from the sandbox.
### Routed Inference through `inference.local`
The OpenShell gateway intercepts all inference requests from the agent and routes them to the configured provider.
The agent never receives the provider API key.
| Aspect | Detail |
|---|---|
| Default | The agent talks to `inference.local`. The host owns the credential and upstream endpoint. |
| What you can change | You cannot configure this architecture. The system always enforces it. |
| Risk if bypassed | If the agent could reach an inference endpoint directly (by adding it to the network policy), it would need an API key. Since the sandbox does not contain credentials, this acts as defense-in-depth. However, adding an inference provider's host to the network policy without going through OpenShell routing could let the agent use a stolen or hardcoded key. |
| Recommendation | Do not add inference provider hosts (such as `api.openai.com` or `api.anthropic.com`) to the network policy for NemoClaw model traffic. Use OpenShell inference routing instead. The `claude-code` preset is a separate opt-in exception for running the Claude Code CLI with its own credentials, not a way to configure NemoClaw inference. |
### Provider Trust Tiers
Different inference providers have different trust and cost profiles.
| Provider | Trust level | Cost risk | Data handling |
|---|---|---|---|
| NVIDIA Endpoints | High. Hosted on `build.nvidia.com`. | Pay-per-token with an API key. Unattended agents can accumulate cost. | NVIDIA infrastructure processes requests. |
| OpenAI | High. Commercial API. | Pay-per-token. Same cost risk as NVIDIA Endpoints. | Subject to OpenAI data policies. |
| Anthropic | High. Commercial API. | Pay-per-token. Same cost risk as NVIDIA Endpoints. | Subject to Anthropic data policies. |
| Google Gemini | High. Commercial API. | Pay-per-token. Same cost risk as NVIDIA Endpoints. | Subject to Google data policies. |
| Local Ollama | Self-hosted. No data leaves the machine. | No per-token cost. GPU/CPU resource cost. | Data stays local. |
| Custom compatible endpoint | Varies. Depends on the proxy or gateway. | Varies. | Depends on the endpoint operator. |
**Recommendation:** For sensitive workloads, use local Ollama to keep data on-premise. For general use, NVIDIA Endpoints provide a good balance of capability and trust. Review the data policies of any cloud provider you use.
### Experimental Providers
The `NEMOCLAW_EXPERIMENTAL=1` environment variable gates local NVIDIA NIM and generic Linux managed vLLM install/start.
DGX Spark and DGX Station managed vLLM entries appear by default.
An already-running vLLM server on `localhost:8000` also appears in the menu without a flag because selecting it is an explicit user action.
| Aspect | Detail |
|---|---|
| Default | Local NVIDIA NIM and generic Linux managed vLLM install/start are hidden. DGX Spark and DGX Station managed vLLM entries, plus already-running vLLM on `localhost:8000`, are offered when detected. |
| What you can change | Set `NEMOCLAW_EXPERIMENTAL=1` before onboarding to surface Local NIM and generic Linux managed vLLM. To request only the managed vLLM path non-interactively, set `NEMOCLAW_PROVIDER=install-vllm`. |
| Risk if selected | NemoClaw has not fully validated these providers. NIM requires a NIM-capable GPU. The managed vLLM path pulls a container image and starts it on a supported NVIDIA GPU host. Misconfiguration can cause failed inference or unexpected behavior. |
| Recommendation | Use experimental providers only for evaluation. Do not rely on them for always-on assistants. |
## Posture Profiles
The following profiles describe how to configure NemoClaw for different use cases.
These are not separate policy files.
They provide guidance on which controls to keep tight or relax.
### Locked-Down (Default)
Use for always-on assistants with minimal external access.
- Keep all defaults. Do not add presets.
- Use operator approval for any endpoint the agent requests.
- Use NVIDIA Endpoints or local Ollama for inference.
- Monitor the TUI for unexpected network requests.
### Development
Use when the agent needs package registries, Docker Hub, or broader GitHub access during development tasks.
- Apply the `pypi` and `npm` presets for package installation.
- Keep binary restrictions on all presets.
- Review the agent's network activity periodically with `openshell term`.
- Use operator approval for any endpoint not covered by a preset.
### Integration Testing
Use when the agent talks to internal APIs or third-party services during testing.
- Add custom endpoint entries with tight path and method restrictions.
- Use `protocol: rest` for all HTTP APIs to maintain inspection.
- Use operator approval for unknown endpoints during test runs.
- Review and clean up the baseline policy after testing. Remove endpoints that are no longer needed.
## Common Mistakes
The following patterns weaken security without providing meaningful benefit.
| Mistake | Why it matters | What to do instead |
|---------|---------------|-------------------|
| 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 generated agent config writable on sensitive workloads | The generated config tree contains model routing, channel settings, and runtime integration state (`/sandbox/.openclaw` for OpenClaw, `/sandbox/.hermes` for Hermes). Writable config lets the agent drift from host-managed policy and routing. | Keep generated config under NemoClaw control for always-on assistants handling sensitive data. |
| Adding inference provider hosts to the network policy for NemoClaw inference | 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. Apply `claude-code` only when intentionally running the separate Claude Code CLI inside the sandbox. |
| 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. |
## Known Limitations
| Limitation | Impact | Mitigation |
|-----------|--------|------------|
| Bypassing managed gateway paths | Network policy and inference auth are not enforced when an agent runtime is launched outside the NemoClaw-managed gateway path. | Use NemoClaw-managed sandbox entrypoints for production workflows. |
| Direct filesystem writes bypass application-layer scanners | Application-layer scanners can intercept agent tool calls, not arbitrary raw filesystem writes (e.g., `echo secret > file`). | Landlock restricts writable paths. Application-layer scanning is defense-in-depth, not a filesystem-level control. |
| Base64/hex-encoded secrets are not detected | Content-based regex scanning cannot detect encoded or obfuscated secrets. | Use environment variables or credential stores instead of writing secrets to files. |
## Related Topics
- Network Policies (use the `nemoclaw-user-reference` skill) for the full baseline policy reference.
- Customize the Network Policy (use the `nemoclaw-user-manage-policy` skill) for static and dynamic policy changes.
- Approve or Deny Network Requests (use the `nemoclaw-user-manage-policy` skill) for the operator approval flow.
<AgentOnly variant="openclaw">
- Sandbox Hardening (use the `nemoclaw-user-deploy-remote` skill) for container-level security measures.
</AgentOnly>
- Inference Options (use the `nemoclaw-user-configure-inference` skill) for provider configuration details.
- How It Works (use the `nemoclaw-user-overview` skill) for the protection layer architecture.

123
.agents/skills/nemoclaw-user-configure-security/references/credential-storage.md
View file

@ -1,123 +0,0 @@
# Credential Storage
import { AgentOnly } from "../_components/AgentGuide";
NemoClaw does not persist provider credentials to host disk.
The OpenShell gateway is the only system of record for stored credentials.
When you provide a provider credential, either interactively during `nemoclaw onboard` or through an environment variable, NemoClaw holds the value in memory only long enough to register it with the OpenShell gateway through `openshell provider create` or `openshell provider update`.
The gateway stores the credential and the OpenShell L7 proxy substitutes it into outbound requests at egress, so sandboxed agents see placeholders instead of the raw secret.
<AgentOnly variant="openclaw">
The sandbox-side OpenClaw gateway token is generated at container startup and is not rotated through provider credential commands.
</AgentOnly>
<AgentOnly variant="hermes">
Hermes API credentials and provider credentials are managed through the same OpenShell provider boundary; generated Hermes runtime files are recreated during rebuilds.
Those files should contain resolver placeholders, not live provider credentials.
For managed tools and messaging, NemoClaw keeps host-side auth in OpenShell providers or host brokers and writes placeholder values into `/sandbox/.hermes/config.yaml`, `/sandbox/.hermes/.env`, and process environment entries visible to the sandbox.
Hermes startup rejects raw secret-shaped values in those sandbox-visible surfaces.
</AgentOnly>
## Where Credentials Live
Provider credentials live in the OpenShell gateway store.
List what is registered with:
```bash
openshell provider list
```
Or, equivalently, through NemoClaw:
```bash
nemoclaw credentials list
```
Both commands show the provider names registered with the gateway.
The values themselves cannot be read back from the CLI; this is a deliberate property of OpenShell.
NemoClaw still keeps non-secret operational state under `~/.nemoclaw/` (such as the sandbox registry).
That directory is created with mode `0700` and contains no credential material.
## Environment Variables Take Precedence
When a NemoClaw command needs a credential value during a single run (for example to forward it to an `openshell provider` registration), it reads from `process.env` first.
This means you can:
- Prefix any command with the credential to override the gateway-stored value: `NVIDIA_INFERENCE_API_KEY=nvapi-... nemoclaw onboard`
- Use short-lived or rotated credentials in CI by exporting them once per pipeline run
- Avoid registering credentials in the gateway entirely if your environment supplies them
When the host environment is empty, day-two operations such as `nemoclaw <name> rebuild` and remote-provider updates can reuse the credential already registered with the OpenShell gateway.
Export the credential only when you want to create, replace, or rotate the stored provider value.
## Deploy Reads from Environment Only
`nemoclaw deploy` (which provisions a remote Brev box) cannot read secrets back from the gateway, so it requires every credential to be present in the host environment at invocation time.
A typical deploy invocation looks like:
```bash
NVIDIA_INFERENCE_API_KEY=nvapi-... \
HF_TOKEN=hf_... \
TELEGRAM_BOT_TOKEN=... \
nemoclaw deploy my-instance
```
For remote vLLM or Hugging Face workflows that need gated model access, `nemoclaw deploy` also forwards `HF_TOKEN` and `HUGGING_FACE_HUB_TOKEN` to the VM when either variable is present.
If a required credential is missing the deploy aborts before any remote work begins.
## GitHub Tokens
NemoClaw never persists `GITHUB_TOKEN` itself.
When a private repo requires authentication NemoClaw runs `gh auth token`, which returns whatever the GitHub CLI has stored — without caring about the storage backend.
The GitHub CLI prefers an OS keychain when one is reachable: macOS Keychain on macOS, Windows Credential Manager on Windows, and Linux Secret Service (libsecret + a running D-Bus session) on Linux.
On hosts where no keychain is reachable (CI runners, headless launches, WSL without a session bus, macOS contexts where Keychain access is blocked, etc.) `gh auth login` falls back to a `gh`-managed file under `~/.config/gh/` with mode `0600`.
NemoClaw treats both backends identically.
`gh auth token` returns the value, and NemoClaw stages it in `process.env` for the current run only.
If `gh` is not installed or not logged in, NemoClaw prompts for a personal access token for that single run; the prompted value is held in process memory and is not written to host disk.
Run `gh auth login` if you want a persistent backing store (whichever one applies on your host) so future runs do not prompt.
## Migration From Earlier Releases
Earlier NemoClaw releases stored credentials as plaintext JSON in `~/.nemoclaw/credentials.json` with mode `0600`.
On first `nemoclaw onboard` after upgrading, NemoClaw automatically:
1. Reads the legacy file.
2. Stages allowlisted credential values into `process.env` for the rest of the run.
3. Re-registers each value with the OpenShell gateway through the normal onboarding path.
4. Securely overwrites and deletes `~/.nemoclaw/credentials.json` only after every staged value has been verified as migrated to the gateway.
You will see a one-line stderr notice the first time this happens.
Credential lookup paths such as rebuild also stage allowlisted legacy values so interrupted upgrades can keep working, but those staging-only paths do not delete the plaintext file because they cannot prove every legacy value was registered with the gateway.
If `~/.nemoclaw/credentials.json` remains after a rebuild or other credential lookup, run `nemoclaw onboard` to complete the verified gateway migration and cleanup.
## Rotate or Remove a Stored Credential
The simplest way to replace a stored value is to rerun onboarding with the new value in your environment:
```bash
NVIDIA_INFERENCE_API_KEY=nvapi-new-value nemoclaw onboard
```
To remove a credential from the gateway entirely:
```bash
nemoclaw credentials reset <PROVIDER_NAME>
```
`<PROVIDER_NAME>` is the OpenShell provider name (run `nemoclaw credentials list` first if you are not sure).
On the next run NemoClaw prompts again unless the credential is supplied through the environment.
## Security Recommendations
1. Prefer short-lived or low-scope provider credentials where the upstream service supports them.
2. Rotate keys after suspected exposure, machine transfer, or account changes.
3. Prefer environment variables for ephemeral automation rather than registering long-lived secrets in the gateway.
4. Do not copy any host-side NemoClaw state into container images, Git repositories, bug reports, or support bundles. Even though credentials no longer live on disk, the surrounding configuration may reveal which providers you have registered.
5. Keep your home directory private and owned by your user account.
## Related Files
For the broader sandbox security model and operational trade-offs, see [Security Best Practices](best-practices.md) and Architecture (use the `nemoclaw-user-reference` skill).

119
.agents/skills/nemoclaw-user-configure-security/references/openclaw-controls.md
View file

@ -1,119 +0,0 @@
# OpenClaw Security Controls Beyond NemoClaw's Scope
NemoClaw provides infrastructure-layer security through sandbox isolation, network policy, filesystem restrictions, SSRF validation, and credential handling.
It delegates all application-layer security to OpenClaw.
This page documents areas where NemoClaw adds no independent protection beyond what OpenClaw already provides.
The details below reflect the OpenClaw documentation at the time of writing.
Consult the [OpenClaw Security docs](https://docs.openclaw.ai/gateway/security) for the current state.
## Prompt Injection Detection and Prevention
OpenClaw detects and neutralizes prompt injection attempts before they reach the agent.
| Control | Detail |
|---|---|
| Regex detection | Pattern matching detects common injection vectors such as "ignore all previous instructions" and `<system>` tag spoofing |
| Boundary wrapping | Untrusted input is wrapped in randomized XML boundary markers |
| Unicode folding | Homoglyph folding normalizes bracket variants to prevent visual spoofing |
| Invisible character stripping | Zero-width invisible characters are removed from input |
| Boundary sanitization | Fake boundary markers are sanitized to prevent marker injection |
| Auto-wrapping | Web fetch and search results are automatically wrapped as untrusted external content |
## Tool Access Control and Policy Pipeline
OpenClaw enforces a multi-layer tool policy pipeline that gates every tool call.
| Control | Detail |
|---|---|
| Deny list | High-risk tools (`exec`, `spawn`, `shell`, `fs_write`, `fs_delete`, and others) are blocked from Gateway HTTP by default |
| Policy pipeline | Multi-layer pipeline evaluates tool calls through profile, provider, agent, sandbox, and per-provider policies |
| Fail-closed semantics | Tool call hooks block execution on any error |
| Loop detection | Optional guard detects and blocks repeated identical tool call patterns (disabled by default, opt-in via `tools.loopDetection.enabled`) |
| Plugin approval | Approval workflow defaults to deny on timeout |
## Authentication Rate Limiting and Flood Protection
OpenClaw rate-limits authentication attempts and guards against connection floods.
| Control | Detail |
|---|---|
| Auth rate limiter | Sliding-window rate limiter tracks failed authentication attempts per IP and per scope |
| Control plane limiter | Per-device write rate limiting for control plane operations |
| WebSocket flood guard | Closes connections after repeated unauthorized attempts |
| Pre-auth budget | Limits connections before authentication completes |
## Environment Variable Security Policy
OpenClaw blocks environment variables that could enable code injection, privilege escalation, or credential theft.
| Category | Detail |
|---|---|
| Always-blocked keys | Keys such as `NODE_OPTIONS`, `LD_PRELOAD`, shell injection vectors, crypto mining variables, and `GIT_*` hijacking paths |
| Override-blocked keys | Additional keys blocked unless explicitly overridden |
| Blocked prefixes | Prefixes such as `GIT_CONFIG_`, `NPM_CONFIG_`, `CARGO_REGISTRIES_`, `TF_VAR_` |
| Universal blocked prefixes | `DYLD_`, `LD_`, `BASH_FUNC_` |
## Security Audit Framework
OpenClaw runs more than 50 distinct automated security checks that cover configuration, credential handling, and sandbox posture.
Run `openclaw security audit` to see all findings for your deployment.
These checks include:
- Synced-folder leak detection.
- Plaintext secrets in configuration files.
- Hooks hardening verification.
- Gateway no-auth detection.
- Sandbox misconfiguration scanning.
- Weak-model susceptibility assessment.
- Multi-user exposure matrix.
- Node command policy validation.
- Dangerous config flag scanning (`allowInsecureAuth`, `dangerouslyDisableDeviceAuth`, and similar flags).
## Skill and Extension Supply Chain Scanning
OpenClaw scans skills and extensions with a built-in static analysis scanner before installation.
Critical findings block installation by default.
The scanner checks for patterns including:
- Direct process execution calls.
- Dynamic code execution (`eval`, `new Function`, and similar constructs).
- Cryptocurrency mining patterns.
- Unexpected network activity.
- Potential data exfiltration (file read combined with network calls).
- Obfuscated code.
- Environment variable harvesting combined with network calls.
## DM and Group Messaging Access Policy
OpenClaw controls who can interact with the agent through direct messages and group channels.
| Control | Detail |
|---|---|
| DM policy modes | Four modes: open, disabled, pairing, allowlist |
| Group policies | Per-group access rules |
| Per-sender authorization | Individual sender gating |
| Command authorization | Command-level access control |
| Multi-user detection | Heuristic that detects multi-user scenarios |
## Context Visibility and Output Controls
OpenClaw restricts what supplemental context the agent can see and how it can modify outputs.
| Control | Detail |
|---|---|
| Mode-based restrictions | Limits visibility of history, threads, quotes, and forwarded messages based on the active mode |
| Sender-based restrictions | Limits visibility based on who sent the message |
| Plugin output hooks | Plugin hooks intercept and modify tool results before they reach the user |
## Safe Regex (ReDoS Prevention)
OpenClaw includes safe regex compilation to prevent regular expression denial of service (ReDoS) attacks.
The implementation detects unsafe nested quantifiers, bounds input length, and caches results.
## Next Steps
- [Security Best Practices](best-practices.md) for NemoClaw's own security controls and risk framework.
- [Credential Storage](credential-storage.md) for how NemoClaw stores and protects provider credentials.

197
.agents/skills/nemoclaw-user-deploy-remote/SKILL.md
View file

@ -1,197 +0,0 @@
---
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. Use when deploying NemoClaw to a remote VM, onboarding a Brev instance, or migrating away from the legacy `nemoclaw deploy` wrapper. Trigger keywords - deploy nemoclaw remote gpu, nemoclaw brev cloud deployment, nemoclaw plugins, openclaw plugins, install openclaw plugin, nemoclaw onboard from dockerfile, nemoclaw dockerignore, nemoclaw brev web ui, nemoclaw getting started, brev quickstart, nvidia nemotron agent, nemoclaw sandbox hardening, container security, docker capabilities, process limits."
license: "Apache-2.0"
---
# Deploy NemoClaw to a Remote GPU Instance
## Gotchas
- The `nemoclaw deploy` command is deprecated.
- On Brev, set `CHAT_UI_URL` in the launchable environment configuration so the installer can read it when it builds the sandbox image.
## Prerequisites
- Access to a remote GPU VM that can run Docker and the NVIDIA Container Toolkit.
- The [Brev CLI](https://brev.nvidia.com) installed and authenticated if you provision the VM with Brev.
- A provider credential for the inference backend you want to use during onboarding.
- `HF_TOKEN` or `HUGGING_FACE_HUB_TOKEN` exported when your remote vLLM or Hugging Face workflow needs access to gated models.
- NemoClaw installed locally if you plan to use the deprecated `nemoclaw deploy` wrapper. Otherwise, install NemoClaw directly on the remote host after provisioning it.
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`.
## Preferred Deployment Path
Provision the remote GPU VM first, then run the normal installer and onboard flow on that VM.
For Brev, `<instance-name>` is the instance name and SSH alias created by the Brev CLI.
For another cloud provider, replace the provisioning and SSH commands with that provider's console or CLI workflow.
```bash
# On your local machine
brev create <instance-name> --gpu <gpu-type>
brev ssh <instance-name>
```
If `brev` is missing or unauthenticated, install or log in to the Brev CLI first, or provision the VM through your cloud console and connect with `ssh <user>@<host>`.
Run the installer on the remote VM:
```bash
curl -fsSL https://www.nvidia.com/nemoclaw.sh | bash
```
Set any remote-only environment variables on the VM before onboarding.
For example, set the browser origin if you will open the dashboard through a Brev public URL, and raise the first-run readiness budget on cold cloud hosts:
```bash
export CHAT_UI_URL="https://openclaw0-<id>.brevlab.com"
export NEMOCLAW_SANDBOX_READY_TIMEOUT=600
nemoclaw onboard
```
After successful onboarding, you should see output that reports a ready sandbox and the next command to connect:
```text
✓ Sandbox '<name>' is ready
Next: nemoclaw <name> connect
```
## Legacy Brev Compatibility
**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.
Use the legacy compatibility wrapper only when you need the older Brev-specific bootstrap flow:
```bash
nemoclaw deploy <instance-name>
```
Replace `<instance-name>` with a name for your remote instance, for example `my-gpu-box`.
The sandbox created on the remote VM uses `NEMOCLAW_SANDBOX_NAME`, or `my-assistant` when the variable is unset.
Sandbox names must be lowercase, start with a letter, contain only letters, numbers, and internal hyphens, and end with a letter or number.
The deploy wrapper validates the sandbox name before it provisions the Brev instance, opens SSH, or starts the remote installer.
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, such as the cloudflared tunnel, when `cloudflared` is available. Onboarding configures channel messaging, and the channels run through OpenShell-managed processes, not through `nemoclaw tunnel 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.
If you export `HF_TOKEN` or `HUGGING_FACE_HUB_TOKEN`, the wrapper forwards those values to the VM so remote setup can pull gated Hugging Face model repositories.
## Connect to the Remote Sandbox
After onboarding finishes, run the host CLI on the remote VM:
```bash
nemoclaw <name> connect
```
If you used the deprecated Brev compatibility wrapper, the wrapper opens an interactive shell inside the remote sandbox.
To reconnect through that legacy flow, run `nemoclaw deploy <instance-name>` again.
## Monitor the Remote Sandbox
SSH to the instance and run the OpenShell TUI on the remote VM to monitor activity and approve network requests:
```bash
ssh <instance-name> 'openshell term'
```
## Verify Inference
Run a test agent prompt from the remote VM host:
```bash
nemoclaw <name> exec -- openclaw agent --agent main -m "Hello from the remote sandbox" --session-id test
```
## 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 you access 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 uses before running `nemoclaw onboard` on the remote VM:
```bash
export CHAT_UI_URL="https://openclaw0-<id>.brevlab.com"
nemoclaw onboard
```
For SSH port-forwarding, the origin is typically the default `http://127.0.0.1:18789`, so you do not need extra configuration.
**Warning:**
On Brev, set `CHAT_UI_URL` in the launchable environment configuration so the installer can read it when it builds the sandbox image.
If you do not set `CHAT_UI_URL` on a headless host, the compatibility wrapper prints a warning.
`NEMOCLAW_DISABLE_DEVICE_AUTH` is also evaluated at image build time.
When `CHAT_UI_URL` points at a non-loopback origin, NemoClaw disables OpenClaw device pairing in the generated sandbox configuration because browser-only remote users cannot complete terminal-based pairing.
Any device that can reach the configured dashboard origin can connect without pairing, so avoid exposing that origin on internet-reachable or shared-network deployments.
## First-Run Readiness Budget
On a remote GPU host, the first `nemoclaw onboard` typically does the slowest work of the lifecycle: the host builds the sandbox image locally and uploads it into the OpenShell gateway, which can stream hundreds of MiB over the VM's link before the readiness wait even starts.
The post-create readiness wait defaults to 180 seconds (`NEMOCLAW_SANDBOX_READY_TIMEOUT`), which fits warm-cache, workstation-class onboarding but can be too short for:
- DGX Station first runs with large quantized models (70B+ parameter footprints, NVFP4 weights).
- Cloud VMs where the local image-build cache is cold and the upload runs over the public network.
- Hosts onboarding the Brave Web Search preset on the first run (the egress policy stack adds boot work).
Raise the budget before re-running onboard:
```bash
export NEMOCLAW_SANDBOX_READY_TIMEOUT=600
nemoclaw onboard
```
If onboard ends with `Sandbox '<name>' was created but did not become ready within 180s`, onboard first deletes the partially created sandbox, so the next attempt with the raised budget starts from a clean state.
For the inference-probe budget that runs earlier in onboarding, refer to `NEMOCLAW_LOCAL_INFERENCE_TIMEOUT` (use the `nemoclaw-user-configure-inference` skill).
## Proxy Configuration
NemoClaw routes sandbox traffic through a gateway proxy that defaults to `10.200.0.1:3128`.
If your network requires a different proxy, set `NEMOCLAW_PROXY_HOST` and `NEMOCLAW_PROXY_PORT` before onboarding:
```bash
export NEMOCLAW_PROXY_HOST=proxy.example.com
export NEMOCLAW_PROXY_PORT=8080
nemoclaw onboard
```
NemoClaw bakes these values into the sandbox image at build time.
NemoClaw also forwards them into the runtime container during sandbox creation, so `/tmp/nemoclaw-proxy-env.sh` uses the same host and port that the image build used.
NemoClaw accepts only alphanumeric characters, dots, hyphens, and colons for the host.
The port must be numeric (0-65535).
Changing the proxy after onboarding requires re-running `nemoclaw onboard`.
## GPU Configuration
The deprecated Brev compatibility wrapper uses the `NEMOCLAW_GPU` environment variable to select the GPU type.
The default value is `a2-highgpu-1g:nvidia-tesla-a100:1`.
That value is specific to GCP-backed Brev instances.
Other Brev providers or cloud consoles use different GPU type strings.
Set this variable before running the deprecated wrapper to use a different GPU configuration:
```bash
export NEMOCLAW_GPU="a2-highgpu-1g:nvidia-tesla-a100:2"
nemoclaw deploy <instance-name>
```
## References
- **Load [references/install-openclaw-plugins.md](references/install-openclaw-plugins.md)** when users ask how to install, build, or configure OpenClaw plugins under NemoClaw. Explains the difference between OpenClaw plugins and agent skills, and shows the current Dockerfile-based workflow for baking a plugin into a NemoClaw sandbox, including `.dockerignore` handling for custom build contexts.
- **Load [references/brev-web-ui.md](references/brev-web-ui.md)** when a user wants to try NemoClaw without installing the CLI, or asks how to get started on Brev. Guides users through deploying NemoClaw with the Brev web UI.
- **Load [references/sandbox-hardening.md](references/sandbox-hardening.md)** when reviewing sandbox image security controls, auditing capability drops, or looking up the runtime resource limits. Includes the sandbox container image hardening reference, covering Docker capabilities and process limits.
## Related Skills
- `nemoclaw-user-manage-sandboxes` — Set Up Messaging Channels (use the `nemoclaw-user-manage-sandboxes` skill) to connect Telegram, Discord, or Slack through OpenShell-managed channel messaging
- `nemoclaw-user-monitor-sandbox` — Monitor Sandbox Activity (use the `nemoclaw-user-monitor-sandbox` skill) for sandbox monitoring tools
- `nemoclaw-user-reference` — `nemoclaw deploy` (use the `nemoclaw-user-reference` skill) for the full `deploy` command reference

11
.agents/skills/nemoclaw-user-deploy-remote/evals/evals.json
View file

@ -1,11 +0,0 @@
[
{
"id": "docs-deployment-deploy-to-remote-gpu-001",
"question": "I'm deploying NemoClaw to a remote GPU instance. Help me move the sandboxed assistant off my local machine so I can support persistent or GPU-backed operation.",
"expected_skill": "nemoclaw-user-deploy-remote",
"ground_truth": "A NemoClaw-specific answer that helps the user move the sandboxed assistant off my local machine and gives enough concrete guidance, decision criteria, verification steps, or risk framing to support persistent or GPU-backed operation.",
"expected_behavior": [
"Uses the expected_skill and does not make up answers if it cannot find the answer from the skill."
]
}
]

155
.agents/skills/nemoclaw-user-deploy-remote/references/brev-web-ui.md
View file

@ -1,155 +0,0 @@
# Launch NemoClaw with the Brev Web UI
Use the Brev web UI to launch a hosted NemoClaw sandbox from your browser.
This flow provisions a remote VM, configures inference, starts OpenClaw inside an OpenShell sandbox, and opens the OpenClaw dashboard.
**Note:**
Use this guide when you want to try NemoClaw without installing the CLI or using a local GPU.
If you want to manage the remote host from a terminal, see [Deploy to a Remote GPU Instance](../SKILL.md).
## What This Flow Creates
The Brev web flow creates the following resources:
- A Brev-managed Linux VM.
- Docker and the OpenShell runtime on that VM.
- A NemoClaw sandbox running OpenClaw.
- Inference routing for the provider you select during setup.
- A browser-accessible OpenClaw dashboard.
## Prerequisites
- An NVIDIA Brev account at [brev.nvidia.com](https://brev.nvidia.com).
- An NVIDIA API key from [build.nvidia.com](https://build.nvidia.com/settings/api-keys) if you use the default NVIDIA Cloud provider.
You do not need to install local software for this flow.
## Get Your NVIDIA API Key
If you already have an NVIDIA API key, skip this section.
Otherwise, follow these steps to generate a new key:
1. Go to [build.nvidia.com](https://build.nvidia.com).
2. Sign in or create an account.
3. Click your profile icon in the top right.
4. Select **API Keys**.
5. Click **Generate API Key**.
6. Copy the key. It starts with `nvapi-`.
Keep this key ready for the next step.
## Launch NemoClaw from Brev
Use the [NemoClaw Brev launchable](https://brev.nvidia.com/launchable/deploy/now?launchableID=env-3Azt0aYgVNFEuz7opyx3gscmowS) to launch a NemoClaw sandbox from your browser.
1. Open the [NemoClaw Brev launchable](https://brev.nvidia.com/launchable/deploy/now?launchableID=env-3Azt0aYgVNFEuz7opyx3gscmowS) and sign in if prompted.
2. Review the instance type, cloud provider, and estimated hourly cost on the NemoClaw setup page.
3. Click **Deploy NemoClaw**.
The deployment panel on the right shows progress while Brev deploys the CPU instance and prepares VM mode.
Keep this page open until the deployment completes.
When the panel shows the **NemoClaw** button, click it to open the agent setup page.
## Configure Your Agent
The setup page walks you through three stages: **Configure**, **Setup**, and **Launch**.
### Configure
The Configure stage opens the **Connect to AI** screen.
Use the NVIDIA Cloud provider shown on this screen.
1. Leave **NVIDIA Cloud** selected.
2. Paste your `nvapi-` API key.
3. Click **Create Agent**.
**Note:**
The **Show Other Providers** dropdown appears below the **NVIDIA Cloud** card and can be easy to miss.
Click it to expand the provider list.
The expanded list includes **OpenAI**, **Anthropic**, and **Google Gemini**.
For these providers, get the API key from the provider's own console before you create the agent.
### Setup
NemoClaw configures the remote host and sandbox automatically.
This stage usually takes about 5 minutes.
During setup, NemoClaw installs the runtime, prepares the sandboxed agent environment, and configures inference routing for the provider you selected.
### Launch
When setup finishes, Brev shows the following confirmation:
```text
AGENT CREATED SUCCESSFULLY
Your agent is running in a secure sandbox and ready to use.
Agent: agent
Model: nemotron-3-super-120b
Provider: NVIDIA Cloud
```
Click **Chat With Agent** to open the OpenClaw dashboard.
**Note:**
The dashboard might initially show a **Pairing required** warning.
This means the gateway is still completing pairing in the background.
Wait a few minutes for pairing to finish automatically.
Refresh the dashboard to check whether the warning has cleared and the dashboard has connected.
If pairing does not finish, go to the **Overview** page in the OpenClaw UI, find the **Gateway Access** panel, and click **Connect**.
## Start a Chat
Use the dashboard chat box to send your first message:
```text
Hello! What can you do for me? What skills do you have available?
```
The agent reads its workspace files and introduces itself.
The starter workspace includes these example skills:
- **Weather** gets current weather and forecasts.
- **Healthcheck** runs security audit and hardening checks.
- **Skill-Creator** creates new custom skills.
## Personalize Agent Memory
The agent starts with an empty `USER.md` file.
Ask the agent to add details that help it personalize future responses.
In the chat, type the following:
```text
Please update my USER.md file with the following:
Name: [your name]
Timezone: [your timezone, such as "America/New_York"]
Notes: [what you are working on]
```
The agent writes this information to its workspace so it can use it across sessions on the same sandbox.
## Stop Your Instance When Done
Brev continues billing while the instance runs.
Stop the instance when you finish experimenting.
1. Go back to [brev.nvidia.com](https://brev.nvidia.com).
2. Click **GPUs** in the nav bar.
3. Find your NemoClaw instance.
4. Click **Stop**.
Check the Brev UI for the current hourly price before leaving the instance running.
## Next Steps
After your agent is running, explore these related tasks:
- Set Up Messaging Channels (use the `nemoclaw-user-manage-sandboxes` skill) to learn how to connect Telegram, Slack, or Discord.
- Switch Inference Providers (use the `nemoclaw-user-configure-inference` skill) to learn how to change the model provider after setup.
- Monitor Sandbox Activity (use the `nemoclaw-user-monitor-sandbox` skill) to learn how to inspect sandbox health and logs.
- [Deploy to a Remote GPU Instance](../SKILL.md) to learn how to deploy NemoClaw to a remote GPU instance using the CLI.
- Troubleshooting (use the `nemoclaw-user-reference` skill) to learn how to fix common setup and runtime issues.

122
.agents/skills/nemoclaw-user-deploy-remote/references/install-openclaw-plugins.md
View file

@ -1,122 +0,0 @@
# Install OpenClaw Plugins
OpenClaw plugins extend the OpenClaw runtime with hooks, services, tools, or provider integrations.
They are different from NemoClaw-managed agent skills:
- **Plugins** are code packages loaded by OpenClaw.
- **Skills** are `SKILL.md` directories that teach an agent how to perform a task.
- **Policy presets** are network-egress rules that control what sandboxed code can reach.
The supported NemoClaw path for OpenClaw plugins is to bake the plugin into a custom sandbox image and onboard from that Dockerfile.
## Prepare a Build Directory
Put the Dockerfile and everything it needs to `COPY` in one directory.
`nemoclaw onboard --from <Dockerfile>` uses the Dockerfile's parent directory as the Docker build context.
Add a `.dockerignore` next to the Dockerfile to exclude local caches, generated artifacts, model files, or other paths that are not needed by the image build.
NemoClaw still applies its own secret-safety exclusions for credential-like paths such as `.env*`, `.ssh/`, `.aws/`, `.npmrc`, `secrets/`, `*.pem`, and `*.key`, even if `.dockerignore` negates them.
```text
my-plugin-sandbox/
├── Dockerfile
└── my-plugin/
├── package.json
└── src/
```
## Example Dockerfile
Use the custom image to copy the plugin into the OpenClaw extensions directory and let OpenClaw refresh its config before NemoClaw starts the sandbox.
```dockerfile
ARG SANDBOX_BASE=ghcr.io/nvidia/nemoclaw/sandbox-base:latest
FROM ${SANDBOX_BASE}
COPY my-plugin/ /opt/my-plugin/
WORKDIR /opt/my-plugin
RUN npm ci --no-audit --no-fund && npm run build
RUN mkdir -p /sandbox/.openclaw/extensions \
&& cp -a /opt/my-plugin /sandbox/.openclaw/extensions/my-plugin \
&& openclaw doctor --fix
WORKDIR /opt/nemoclaw
```
If the plugin needs configuration in `openclaw.json`, apply it after `openclaw doctor --fix` so the base config exists first.
## Create the Sandbox
Point `nemoclaw onboard --from` at the Dockerfile in the build directory.
```bash
nemoclaw onboard --from ./my-plugin-sandbox/Dockerfile
```
If you need a second sandbox alongside an existing one, use a dedicated build directory and rerun onboarding with the sandbox name and ports you intend to use.
## Build Performance
Custom plugin images are normal Docker builds, so build time depends on the build context size and the Docker layer cache rather than on NemoClaw.
Keep the build context small and dedicated.
The Dockerfile's parent directory is staged as the build context before the Docker build starts, so a broad directory can make onboarding look stuck while Docker is only preparing context.
A small build directory stages quickly:
```text
my-plugin-sandbox/ # fast: only what the image needs
├── Dockerfile
├── .dockerignore
└── my-plugin/
```
A Dockerfile placed in a large tree stages slowly:
```text
~/ # slow: stages the whole home directory
├── Dockerfile
├── Downloads/
├── datasets/
└── models/
```
Distinguish cold builds from warm rebuilds.
The first build on a fresh host is a cold build that downloads the base image and package indexes, so it is the slowest run.
Later warm rebuilds reuse cached layers when the base image and earlier layers are unchanged.
Order Dockerfile instructions from least-changing to most-changing so warm rebuilds reuse cached dependency layers:
1. Base image.
2. System package installs.
3. Dependency manifests such as `package.json`.
4. Dependency install such as `npm ci`.
5. Application source.
Pin the base image to an explicit tag or digest so warm rebuilds resolve the same cached base instead of pulling a new one.
When a build feels slow, set `NEMOCLAW_TRACE=1` before onboarding to capture phase timings that separate context staging, Docker build, image upload, and sandbox readiness.
For the full `--from` build-context rules and trace details, refer to CLI Commands Reference (use the `nemoclaw-user-reference` skill).
## Network Access
Plugins still run inside the sandbox policy boundary.
If a plugin needs network egress, add or update a policy preset for the required hostnames and binaries before rebuilding the sandbox.
For policy concepts, refer to Network Policies (use the `nemoclaw-user-reference` skill).
For custom preset workflows, refer to Customize Network Policy (use the `nemoclaw-user-manage-policy` skill).
## Common Mistakes
These are the most common places where plugin installation gets mixed up with other NemoClaw extension paths.
- Do not use `nemoclaw <sandbox> skill install` for OpenClaw plugins. That command only installs `SKILL.md` agent skills.
- Do not put a Dockerfile in a broad directory such as `/tmp` unless you intend to send that whole directory as the Docker build context.
- Do not rely on `.dockerignore` to include credential-like paths; NemoClaw excludes those from staged custom build contexts for safety.
- Keep plugin dependencies in the build stage or plugin directory; avoid copying
unrelated host files into the sandbox image.
## Next Steps
- Review [Sandbox Hardening](sandbox-hardening.md) before adding plugin code to a shared or long-lived sandbox.
- Review Network Policies (use the `nemoclaw-user-reference` skill) to plan plugin egress rules.
- Follow Customize Network Policy (use the `nemoclaw-user-manage-policy` skill) if the plugin needs a custom preset.

148
.agents/skills/nemoclaw-user-deploy-remote/references/sandbox-hardening.md
View file

@ -1,148 +0,0 @@
# 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
NemoClaw explicitly purges build toolchains (`gcc`, `g++`, `make`) and network probes (`netcat`) from the runtime image.
These tools are not needed at runtime and would unnecessarily widen the attack surface.
The runtime image keeps a small set of operational utilities for normal sandbox workflows, including `vi`, `jq`, and `dos2unix`.
Use these utilities for lightweight inspection and file cleanup inside the sandbox, but make durable image or policy changes in the NemoClaw source tree and rebuild the sandbox.
If you need a compiler during build, use the existing multi-stage build.
The `builder` stage has full Node.js tooling.
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 with the `--ulimit nproc=512:512` flag if you launch with `docker run` directly.
## Open File Descriptor Limits
The same ENTRYPOINT also sets `ulimit -n 65536` to cap the number of open file
descriptors a sandbox user can hold. Without this cap the sandbox inherits the
Docker daemon default (`nofile` ~1048576), which can exceed the host runtime
limit and lets a runaway process exhaust file descriptors. The startup script
(`nemoclaw-start.sh`) applies the same limit.
Adjust the value via the `--ulimit nofile=65536:65536` flag if launching with
`docker run` directly.
Like the process limit, this is applied to the PID 1 entrypoint process tree
(gateway + agent). `openshell sandbox connect` shells are spawned outside that
tree and still inherit the runtime default (tracked upstream in
NVIDIA/OpenShell#1452), so enforce both limits at the container runtime when
that residual matters to you.
## Dropping Linux Capabilities
The NemoClaw entrypoint drops dangerous capabilities from the process bounding set before it starts agent services.
It removes `CAP_SYS_ADMIN`, `CAP_SYS_PTRACE`, `CAP_NET_RAW`,
`CAP_DAC_OVERRIDE`, `CAP_SYS_CHROOT`, `CAP_FSETID`, `CAP_SETFCAP`,
`CAP_MKNOD`, `CAP_AUDIT_WRITE`, and `CAP_NET_BIND_SERVICE`.
When `setpriv` is available, the entrypoint also removes the remaining privilege-separation capabilities during the switch from root to the `sandbox` and `gateway` users.
The bounding-set drop is best effort: if `capsh` or `CAP_SETPCAP` is unavailable the entrypoint logs a warning and continues with the runtime-provided capability set.
If `setpriv` is unavailable, the entrypoint falls back to `gosu`.
To make the drop fail-closed instead, set `NEMOCLAW_REQUIRE_CAP_DROP=1` in the entrypoint environment: the agent then refuses to start unless the agent process tree's bounding set is verified free of the dangerous capabilities.
This is opt-in because hosts that cannot drop capabilities (no `CAP_SETPCAP` — many cloud VMs, Docker Desktop, WSL) are common, and the check covers the agent process tree only.
For defense-in-depth, also drop all Linux capabilities at the container runtime
when you launch the image directly:
```bash
docker run --rm \
--cap-drop=ALL \
--ulimit nproc=512:512 \
--ulimit nofile=65536:65536 \
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
nofile:
soft: 65536
hard: 65536
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`.
## Filesystem Layout
The sandbox Landlock policy declares which paths are writable.
The agent's home directory (`/sandbox`) is writable by default:
| Path | Access | Purpose |
|------|--------|---------|
| `/sandbox` | read-write | Home directory where agents can create files and use standard home paths |
| `/sandbox/.openclaw` | read-write | Agent config, state, workspace, plugins |
| `/sandbox/.nemoclaw` | read-write (Landlock); DAC-restricted | Parent directory is `root:root` mode `1755`; the sandbox user can write only to `state/`, `migration/`, `snapshots/`, `staging/`, and `config.json`. `blueprints/` and the parent itself are root-owned to prevent tampering. |
| `/tmp` | read-write | Temporary files and logs |
The `Access` column reflects the Landlock policy declaration only.
Actual write success additionally requires POSIX (DAC) ownership and permissions to allow it.
For example, Landlock lists `/sandbox/.nemoclaw` as writable, but the sandbox user cannot create files directly under it because the parent directory is root-owned; writes must target the sandbox-owned subdirectories listed above.
This writable default is intentional.
Seeing the sandbox user create files under `/sandbox` or `/sandbox/.openclaw` in a fresh sandbox does not mean Landlock failed.
Landlock still enforces the fixed read-only system paths below.
System paths remain read-only to prevent agents from:
- Replacing system binaries with trojanized versions
- Modifying DNS resolution or TLS trust stores
- Tampering with libraries or shell configuration outside `/sandbox`
The image build pre-creates locked shell init files `.bashrc` and `.profile` without proxy entries.
System-wide shell hooks that read `/tmp/nemoclaw-proxy-env.sh` source the runtime proxy configuration.
### Landlock Kernel Requirements
Landlock LSM requires Linux kernel 5.13 or later with `CONFIG_SECURITY_LANDLOCK=y`.
The NemoClaw sandbox policy uses `compatibility: best_effort`, which means Landlock enforcement is silently skipped on kernels that do not support it.
On such kernels, protection falls back to DAC (file ownership and permissions) only.
Files outside the writable paths would be inaccessible to the agent regardless of DAC permissions.
Operators should verify Landlock availability:
```bash
ls /sys/kernel/security/landlock
```
For production deployments, kernel 5.13+ with Landlock enabled is strongly recommended.
The `test/e2e/e2e-cloud-experimental/checks/04-landlock-readonly.sh` script validates enforcement at runtime.
## References
- [#804](https://github.com/NVIDIA/NemoClaw/issues/804): Filesystem layout and Landlock policy
- [#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
- [#4527](https://github.com/NVIDIA/NemoClaw/issues/4527): Cap open file descriptors (nofile)
- [#797](https://github.com/NVIDIA/NemoClaw/issues/797): Drop Linux capabilities

270
.agents/skills/nemoclaw-user-get-started/SKILL.md
View file

@ -1,270 +0,0 @@
---
name: "nemoclaw-user-get-started"
description: "Installs NemoClaw, launches a sandbox, and runs the first agent prompt. Use when onboarding, installing, or launching a NemoClaw sandbox for the first time. Trigger keywords - nemoclaw quickstart, install nemoclaw openclaw sandbox, nemohermes quickstart, hermes agent nemoclaw, run hermes openshell sandbox, nemoclaw prerequisites, nemoclaw supported platforms, nemoclaw hardware software, nemoclaw windows wsl2 setup, nemoclaw install windows docker desktop."
license: "Apache-2.0"
---
# NemoClaw Quickstart with OpenClaw
Follow these steps to get started with NemoClaw and your first sandboxed OpenClaw agent.
**Note:**
Review the [Prerequisites](references/prerequisites.md) before following this guide.
**Use Agent Skills:**
NemoClaw ships user skills for AI coding assistants.
Load them when you want your assistant to walk through installation, inference choices, policy approvals, monitoring, or troubleshooting with NemoClaw-specific guidance.
Refer to Agent Skills (use the `nemoclaw-user-agent-skills` skill).
## Install NemoClaw and Onboard an 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
```
The third-party software notice runs before the installer installs Node.js or the NemoClaw CLI.
The piped installer can prompt through your terminal when a TTY is available.
In non-TTY contexts, such as CI, an SSH command with piped stdin, or a shell script, pass explicit acceptance to the `bash` side of the pipe:
```bash
curl -fsSL https://www.nvidia.com/nemoclaw.sh | NEMOCLAW_ACCEPT_THIRD_PARTY_SOFTWARE=1 bash
```
Or pass the installer flag through `bash -s`:
```bash
curl -fsSL https://www.nvidia.com/nemoclaw.sh | bash -s -- --yes-i-accept-third-party-software
```
To run both installation and onboarding without prompts, also set non-interactive mode and the provider variables your chosen inference path requires:
```bash
curl -fsSL https://www.nvidia.com/nemoclaw.sh | NEMOCLAW_NON_INTERACTIVE=1 NEMOCLAW_ACCEPT_THIRD_PARTY_SOFTWARE=1 bash
```
Do not place `NEMOCLAW_ACCEPT_THIRD_PARTY_SOFTWARE=1` before `curl`.
In `NEMOCLAW_ACCEPT_THIRD_PARTY_SOFTWARE=1 curl ... | bash`, the variable applies only to `curl`, so the installer process cannot see the acceptance.
If you use nvm or fnm to manage Node.js, the installer might 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.
On Linux, the installer checks Docker before it installs NemoClaw.
If Docker is missing, the installer downloads the official Docker convenience script, asks for `sudo`, installs Docker, and starts the Docker service when systemd is available.
If you installed Docker but your current shell cannot use the Docker socket yet, the installer adds your user to the `docker` group when needed and exits with a recovery command.
On macOS, the installer uses the Docker-driver OpenShell gateway path with Docker Desktop or Colima.
```bash
newgrp docker
curl -fsSL https://www.nvidia.com/nemoclaw.sh | bash
```
On DGX Spark, DGX Station, and Windows WSL, an interactive installer offers express install after you accept the third-party software notice.
Express install switches onboarding to non-interactive mode, allows `sudo` password prompts for required host changes, and selects the managed local inference path for that platform.
Unless `NEMOCLAW_POLICY_TIER` is set, it applies sandbox policy in `suggested` mode with the `balanced` tier by default, using the base sandbox policy plus supported package, model, web-search, local-inference, and read-only weather presets.
On DGX Spark, express install uses `my-spark-assistant` as the sandbox name unless `NEMOCLAW_SANDBOX_NAME` is already set.
On WSL, express install selects the Windows-host Ollama setup path.
Set `NEMOCLAW_NO_EXPRESS=1` to skip the express prompt, or set `NEMOCLAW_PROVIDER` before launching the installer when you want to choose a provider yourself.
The installer auto-launches `nemoclaw onboard` when it can locate the freshly installed binary.
If it cannot locate the binary, or if blocking host preflight checks fail, it does not launch the wizard automatically.
In that case, the installer prints the relevant diagnostics and a `To finish setup, run:` block with the explicit `nemoclaw onboard` command.
**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.
### Respond to the Onboard Wizard
After the installer launches `nemoclaw onboard`, the wizard runs preflight checks, starts or reuses the OpenShell gateway, asks for an inference provider and model, collects any required credential, then asks for the sandbox name.
It prints a review summary before it registers the provider with OpenShell.
After you confirm, NemoClaw registers inference, prompts for optional web search and messaging channels, builds and starts the sandbox, sets up OpenClaw, then applies the selected network policy tier and presets.
At any prompt, press Enter to accept the default shown in `[brackets]`, type `back` to return to the previous prompt, or type `exit` to quit.
If existing sandbox sessions are running, the installer warns before onboarding because the setup can rebuild or upgrade sandboxes after the new sandbox launches.
The inference provider prompt presents a numbered list.
```text
1) NVIDIA Endpoints
2) OpenAI
3) Other OpenAI-compatible endpoint
4) Anthropic
5) Other Anthropic-compatible endpoint
6) Google Gemini
7) Local Ollama (localhost:11434)
8) Model Router (experimental)
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.
A configured blueprint router profile makes the Model Router option appear.
**Tip:**
Export the API key before launching the installer so the wizard does not have to ask for it.
For example, run `export NVIDIA_INFERENCE_API_KEY=<your-key>` before `curl ... | bash`.
If you entered a key incorrectly, refer to Reset a Stored Credential (use the `nemoclaw-user-manage-sandboxes` skill) to clear and re-enter it.
### Choose an Inference Provider
Pick the option that matches where you want inference traffic to go.
For full provider behavior, curated models, validation details, and local-runtime setup notes, refer to Inference Options (use the `nemoclaw-user-configure-inference` skill).
For Ollama, vLLM, NIM, and compatible local servers, refer to Use a Local Inference Server (use the `nemoclaw-user-configure-inference` skill).
| Option | Use when | Credential variable |
|---|---|---|
| NVIDIA Endpoints | You want hosted models from `build.nvidia.com`, including hosted Nemotron models. | `NVIDIA_INFERENCE_API_KEY` |
| OpenAI | You want the OpenAI API at `https://api.openai.com/v1`. | `OPENAI_API_KEY` |
| Other OpenAI-compatible endpoint | You have OpenRouter, LocalAI, llama.cpp, vLLM, NIM, SGLang, an enterprise gateway, or another `/v1/chat/completions` endpoint. | `COMPATIBLE_API_KEY` |
| Anthropic | You want the Anthropic Messages API. | `ANTHROPIC_API_KEY` |
| Other Anthropic-compatible endpoint | You have a Claude proxy, Bedrock-compatible gateway, or self-hosted `/v1/messages` endpoint. | `COMPATIBLE_ANTHROPIC_API_KEY` |
| Google Gemini | You want Google's OpenAI-compatible Gemini endpoint. | `GEMINI_API_KEY` |
| Local Ollama | You want a host-local Ollama model. | None |
| Model Router | You want NemoClaw to start the host-side model router. | `NVIDIA_INFERENCE_API_KEY` |
Export the relevant key before launching the installer when possible.
If your compatible endpoint does not require authentication, set its credential variable to any non-empty placeholder.
### Review the Configuration Before the Sandbox Build
After you enter the sandbox name, the wizard prints a review summary and asks for final confirmation before registering the provider, prompting for optional integrations, and building the sandbox image.
For example, if you picked an OpenAI-compatible endpoint, the summary looks like the following:
```text
──────────────────────────────────────────────────
Review configuration
──────────────────────────────────────────────────
Provider: compatible-endpoint
Model: openai/openai/gpt-5.5
API key: configured for OpenShell gateway registration
Web search: disabled
Managed tools: none
Messaging: none
Sandbox name: my-gpt-claw
Note: Sandbox build typically takes 5–15 minutes on this host.
──────────────────────────────────────────────────
Web search and messaging channels will be prompted next.
Apply this configuration? [Y/n]:
```
The default is `Y`, so you can press Enter one time to continue. Answer `n` to abort cleanly, fix the entries, and re-run `nemoclaw onboard`.
Non-interactive runs (`NEMOCLAW_NON_INTERACTIVE=1`) print the summary for log clarity but skip the prompt.
### Configure Web Search and Messaging
After you confirm the summary, NemoClaw registers the selected provider with the OpenShell gateway and sets the `inference.local` route.
The wizard then asks whether to enable Brave Web Search.
If you enable it, enter a Brave Search API key when prompted.
The wizard also offers messaging channels such as Telegram, Discord, Slack, WeChat, and WhatsApp.
Press a channel number to toggle it, then press Enter to continue.
If you leave all channels unselected, pressing Enter skips messaging setup.
If you select a channel, NemoClaw validates the token format before it bakes the channel configuration into the sandbox.
For example, Slack bot tokens must start with `xoxb-`.
WeChat and WhatsApp are experimental.
Review Messaging Channels (use the `nemoclaw-user-manage-sandboxes` skill) before enabling them.
### Choose Network Policy Presets
After the sandbox image builds and OpenClaw starts inside the sandbox, NemoClaw asks which network policy tier to apply.
Web search and messaging selections happen before this point so the sandbox image and the policy suggestions stay aligned.
The default **Balanced** tier includes common development presets such as npm, PyPI, Hugging Face, Homebrew, read-only weather lookups, and Brave Search when the selected agent supports web search.
Use the arrow keys or `j` and `k` to move, Space to select, and Enter to confirm.
The preset selector lets you include more destinations, such as GitHub, Jira, Slack, Telegram, or local inference.
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.
NemoClaw reports inference route and messaging bridge checks 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.
```text
──────────────────────────────────────────────────
NemoClaw is ready
Sandbox: my-gpt-claw
Model: openai/openai/gpt-5.5 (Other OpenAI-compatible endpoint)
Start chatting
Browser:
http://127.0.0.1:18789/
Terminal:
nemoclaw my-gpt-claw connect
then run: openclaw tui
Authenticated dashboard URL, if needed:
nemoclaw my-gpt-claw dashboard-url --quiet
Manage later
Status: nemoclaw my-gpt-claw status
Logs: nemoclaw my-gpt-claw logs --follow
Model: nemoclaw inference set --model <model> --provider <provider> --sandbox my-gpt-claw
Policies: nemoclaw my-gpt-claw policy-add
Credentials: nemoclaw credentials reset <KEY> && nemoclaw onboard
──────────────────────────────────────────────────
[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)`, `nvidia-routed (Model Router)`, or `<your-model> (Other OpenAI-compatible endpoint)`.
## Run Your First Agent Prompt
You can chat with the agent from the terminal or the browser.
### Open the OpenClaw UI in a Browser to Chat with the Agent
The onboard wizard starts a background port forward to the sandbox dashboard, then prints the dashboard URL in the install summary.
The default host port is `18789`.
If that port is already taken, NemoClaw uses the next free dashboard port, such as `18790`, and prints that port in the final URL.
If the chosen port becomes occupied after the sandbox build starts, onboarding rolls back the newly created sandbox and asks you to retry instead of printing an unreachable dashboard URL.
The install transcript does not print the gateway token.
If the browser requires authentication, use the `dashboard-url --quiet` command to print a complete URL explicitly.
```text
nemoclaw my-gpt-claw dashboard-url --quiet
```
Open the dashboard URL in your browser.
If the browser asks for authentication, run `nemoclaw my-gpt-claw dashboard-url --quiet` and open the returned URL.
Treat the authenticated URL like a password.
### Chat with the Agent from the Terminal
Connect to the sandbox and use the OpenClaw CLI.
```bash
nemoclaw my-assistant connect
# inside the sandbox:
openclaw tui
```
## References
- **Load [references/quickstart-hermes.md](references/quickstart-hermes.md)** when users ask for Hermes setup, NemoHermes onboarding, or running Hermes inside OpenShell. Installs NemoClaw, selects the Hermes agent, and launches a sandboxed Hermes dashboard and API endpoint.
- **Load [references/prerequisites.md](references/prerequisites.md)** when verifying prerequisites before installation. Lists the hardware, software, and container runtime requirements for running NemoClaw.
- **Load [references/windows-preparation.md](references/windows-preparation.md)** when preparing a Windows machine for NemoClaw, enabling WSL 2, configuring Docker Desktop for Windows, or troubleshooting a Windows-specific install error. Covers Windows-only preparation steps required before the Quickstart.
## Related Skills
- `nemoclaw-user-overview` — NemoClaw Overview (use the `nemoclaw-user-overview` skill) to learn what NemoClaw is and its capabilities
- `nemoclaw-user-agent-skills` — Agent Skills (use the `nemoclaw-user-agent-skills` skill) to load NemoClaw guidance into an AI coding assistant

11
.agents/skills/nemoclaw-user-get-started/evals/evals.json
View file

@ -1,11 +0,0 @@
[
{
"id": "docs-get-started-prerequisites-001",
"question": "I'm checking prerequisites before installation. Help me verify my host has the required hardware, software, and platform support so I can avoid a failed first setup.",
"expected_skill": "nemoclaw-user-get-started",
"ground_truth": "A NemoClaw-specific answer that helps the user verify my host has the required hardware, software, and platform support and gives enough concrete guidance, decision criteria, verification steps, or risk framing to avoid a failed first setup.",
"expected_behavior": [
"Uses the expected_skill and does not make up answers if it cannot find the answer from the skill."
]
}
]

78
.agents/skills/nemoclaw-user-get-started/references/prerequisites.md
View file

@ -1,78 +0,0 @@
# Prerequisites
Before you start, verify that your machine has the software and hardware needed to run NemoClaw.
## Hardware
| Resource | Minimum | Recommended |
|----------|----------------|------------------|
| CPU | 4 vCPU | 4+ vCPU |
| RAM | 8 GB | 16 GB |
| Disk | 20 GB free | 40 GB free |
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.
The pipeline 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.
## Software
| Dependency | Version |
|------------|----------------------------------|
| Node.js | 22.16 or later |
| npm | 10 or later |
| Docker | Docker Engine, Docker Desktop, or Colima on a tested platform |
| Platform | See [Platforms](#platforms) below |
On Linux, the installer can install Docker, start the Docker service, and add your user to the `docker` group.
If the group change is not active in the current shell, the installer exits with `newgrp docker` guidance before it starts onboarding.
If you choose the native Linux Ollama install path, the onboard wizard also requires `zstd` for Ollama archive extraction.
The installer also requires `strings` from `binutils` to verify the OpenShell binary before it continues with OpenShell install work.
**Docker Group Access:**
NemoClaw needs Docker access.
On personal Linux development machines, adding your user to the `docker` group is the standard way to run Docker without sudo.
Members of the `docker` group can control the daemon with root-level impact, so grant this access only to trusted local accounts; on shared or managed systems, use your organization's approved Docker access path.
For background, review Docker's [daemon attack surface guidance](https://docs.docker.com/engine/security/#docker-daemon-attack-surface).
On Debian and Ubuntu, NemoClaw installs `zstd` with `apt-get` if it is missing; on other Linux distributions, install `zstd` before onboarding.
If the installer reports that `strings` is missing, install `binutils` and rerun the installer:
```bash
sudo apt-get install -y binutils
```
On macOS, NemoClaw uses the Docker-driver OpenShell gateway path with Docker Desktop or Colima.
You do not need to install or sign a separate OpenShell VM driver helper for standard macOS onboarding.
**OpenShell Lifecycle:**
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`.
**Docker Storage Driver:**
On Linux hosts running Docker 26 or later with the [containerd image store](https://docs.docker.com/engine/storage/containerd/) enabled (the install-time default for fresh `docker-ce` installations on Ubuntu 24.04 and similar distros), `nemoclaw onboard` transparently builds a `fuse-overlayfs`-enabled cluster image to bypass a kernel-level nested-overlay limitation in k3s.
You do not need manual setup.
Refer to the troubleshooting guide (use the `nemoclaw-user-reference` skill) for the override knobs and a manual `daemon.json` alternative.
## Platforms
The following table lists tested platform and runtime combinations.
Availability is not limited to these entries, but untested configurations can have issues.
The table comes from [`ci/platform-matrix.json`](https://github.com/NVIDIA/NemoClaw/blob/main/ci/platform-matrix.json), the single source of truth kept in sync by CI and QA.
| OS | Container runtime | Status | Notes |
|----|-------------------|--------|-------|
| Linux | Docker | Tested | Primary tested path. |
| macOS (Apple Silicon) | Colima, Docker Desktop | Tested with limitations | Install Xcode Command Line Tools (`xcode-select --install`) and start the runtime before running the installer. |
| DGX Spark | Docker | Tested | Use the standard installer and `nemoclaw onboard`. For an end-to-end walkthrough with local Ollama inference, see the [NVIDIA Spark playbook](https://build.nvidia.com/spark/nemoclaw). |
| Windows WSL2 | Docker Desktop (WSL backend) | Tested with limitations | Requires WSL2 with Docker Desktop backend. |
## Next Steps
- Prepare Windows for NemoClaw if you are using Windows.
- [Quickstart](../SKILL.md) to install NemoClaw and launch your first sandboxed agent.
- Agent Skills (use the `nemoclaw-user-agent-skills` skill) to load NemoClaw guidance into an AI coding assistant before setup.

215
.agents/skills/nemoclaw-user-get-started/references/quickstart-hermes.md
View file

@ -1,215 +0,0 @@
# NemoClaw Quickstart with Hermes
Use NemoHermes when you want NemoClaw to create an OpenShell sandbox that runs Hermes instead of the default OpenClaw agent.
The `nemohermes` command is an alias for `nemoclaw` with the Hermes agent pre-selected.
Review the [Prerequisites](prerequisites.md) before starting.
Install Docker, start it, and verify that the current shell can reach it before Hermes onboarding builds the sandbox image.
On Linux, the installer can install Docker, start the service, and add your user to the `docker` group.
If it changes group membership, run the printed `newgrp docker` recovery command before rerunning the installer.
On macOS, start Docker Desktop or Colima before you run the installer.
The first Hermes build can take several minutes because NemoClaw builds the Hermes sandbox base image if it is not already cached.
## Install and Onboard
Start the installer with `NEMOCLAW_AGENT=hermes` set in your shell.
The installer installs the CLI, selects the `nemohermes` alias, and runs the guided onboarding flow.
```bash
export NEMOCLAW_AGENT=hermes
curl -fsSL https://www.nvidia.com/nemoclaw.sh | bash
```
If a headless host needs to expose the Hermes dashboard through a remote URL or tunnel, set `CHAT_UI_URL` before onboarding.
Use the externally reachable origin for the dashboard port `18789`.
NemoClaw derives the forwarded dashboard port from this value, binds the forward for remote access when the origin is non-loopback, and prints the final dashboard URL in the ready summary.
The OpenAI-compatible API remains available separately on port `8642`.
```bash
export NEMOCLAW_AGENT=hermes
export CHAT_UI_URL="https://hermes.example.com:18789"
curl -fsSL https://www.nvidia.com/nemoclaw.sh | bash
```
For SSH local port forwarding to `127.0.0.1:18789`, leave `CHAT_UI_URL` unset.
Do not append an OpenClaw `#token=` fragment to the Hermes dashboard URL.
Hermes API clients authenticate with the bearer token from the generated Hermes environment instead of an OpenClaw dashboard URL token.
If NemoClaw is already installed, start Hermes onboarding directly.
```bash
nemohermes onboard
```
## Respond to the Wizard
The onboard wizard asks for an inference provider, model, any required credential, and sandbox name before it prints the review summary.
After you confirm, NemoClaw registers inference, prompts for supported messaging channels, builds and starts the sandbox, sets up Hermes, then applies the selected network policy tier and presets.
At any prompt, press Enter to accept the default shown in `[brackets]`, type `back` to return to the previous prompt, or type `exit` to quit.
The default Hermes sandbox name is `hermes`.
Use a distinct sandbox name, such as `my-hermes`, so you can run Hermes and OpenClaw sandboxes side by side.
NemoClaw prevents same-name reuse when an existing sandbox uses a different agent.
```text
Sandbox name [hermes]: my-hermes
```
Choose the inference provider that matches where you want Hermes model traffic to go.
The provider options and credential environment variables are the same as the standard NemoClaw quickstart.
For provider-specific prompts, refer to the Inference Options (use the `nemoclaw-user-configure-inference` skill) page.
The Hermes wizard does not ask for Brave Web Search because Hermes does not use NemoClaw's OpenClaw web-search configuration.
If you authenticate Hermes through Nous Portal OAuth, the wizard can also prompt for managed Nous tool gateways such as web search, image generation, audio, browser automation, or managed code execution.
Those choices add the matching Hermes policy presets to the sandbox.
API-key mode is inference-only and does not enable managed tool gateways.
After provider and model selection, review the summary and confirm the build.
NemoClaw writes Hermes configuration into `/sandbox/.hermes`, routes model traffic through `inference.local`, and starts the Hermes gateway inside the sandbox.
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.
The example below uses NVIDIA Endpoints and creates a sandbox named `my-hermes`.
```bash
export NEMOCLAW_AGENT=hermes
export NEMOCLAW_NON_INTERACTIVE=1
export NEMOCLAW_ACCEPT_THIRD_PARTY_SOFTWARE=1
export NEMOCLAW_SANDBOX_NAME=my-hermes
export NVIDIA_INFERENCE_API_KEY=<your-key>
curl -fsSL https://www.nvidia.com/nemoclaw.sh | bash
```
Use the provider variables from Inference Options (use the `nemoclaw-user-configure-inference` skill) when you choose a different provider.
## Connect to Hermes
When onboarding completes, NemoClaw prints the sandbox name, model, lifecycle commands, the Hermes dashboard URL, and the OpenAI-compatible API URL.
Hermes exposes its built-in browser dashboard on port `18789`.
NemoClaw also forwards the OpenAI-compatible API on port `8642` for local clients, and the summary now announces both URLs.
NemoClaw builds the Hermes dashboard assets into the sandbox image, so the dashboard starts without running `npm` as the sandbox user under `/opt/hermes`.
Dashboard chat uses the prebuilt `/opt/hermes/ui-tui` bundle.
If you need to recover the Hermes dashboard manually, use `hermes dashboard --tui --skip-build` so recovery does not try to rebuild assets under root-owned install paths.
Set `NEMOCLAW_HERMES_DASHBOARD_TUI=1` before onboarding only if you want Hermes' optional in-browser TUI tab.
```text
──────────────────────────────────────────────────
NemoHermes is ready
Sandbox: my-hermes
Model: nvidia/nemotron-3-super-120b-a12b (NVIDIA Endpoints)
Access
Hermes Agent Dashboard
Port 18789 must be forwarded before opening this URL.
http://127.0.0.1:18789/
Hermes Agent OpenAI-compatible API
Port 8642 must be forwarded before connecting.
http://127.0.0.1:8642/v1
Terminal:
nemohermes my-hermes connect
Manage later
Status: nemohermes my-hermes status
Logs: nemohermes my-hermes logs --follow
Model: nemohermes inference set --model <model> --provider <provider> --sandbox my-hermes
Policies: nemohermes my-hermes policy-add
Credentials: nemohermes credentials reset <KEY> && nemohermes onboard
──────────────────────────────────────────────────
```
To chat with the agent from a terminal, follow these steps:
1. Connect to the sandbox and start the Hermes CLI.
```bash
nemohermes my-hermes connect
```
2. Inside the sandbox, run the Hermes CLI.
```bash
hermes
```
## Open the Dashboard
The onboard flow starts the dashboard port forward automatically.
Open the dashboard from the host:
```bash
nemohermes my-hermes dashboard-url --quiet
```
Expected output:
```text
http://127.0.0.1:18789/
```
Hermes handles dashboard sessions itself, so this URL does not include an OpenClaw `#token=` fragment.
## Check the API Endpoint
The onboard flow also starts the API port forward automatically.
Check the health endpoint from the host to confirm that the Hermes API is reachable.
```bash
curl -sf http://127.0.0.1:8642/health
```
If the command cannot connect after a reboot or terminal restart, start the forward again.
```bash
openshell forward start --background 8642 my-hermes
```
Configure an OpenAI-compatible client with the base URL `http://127.0.0.1:8642/v1`.
Hermes uses API header authentication for client requests.
Do not append an OpenClaw `#token=` URL fragment to the Hermes endpoint.
Treat the dashboard as a local management UI.
Avoid exposing it on shared or public networks unless you put it behind your own access controls.
## Manage the Sandbox
Use the same lifecycle commands as a standard NemoClaw sandbox.
The `nemohermes` alias keeps help text and recovery messages aligned with Hermes, while targeting the same registered sandbox.
`nemoclaw list` shows the agent type for each sandbox so you can distinguish Hermes and OpenClaw entries.
```bash
nemohermes my-hermes status
nemohermes my-hermes logs --follow
nemohermes my-hermes snapshot create --name before-change
nemohermes my-hermes rebuild
```
To change the active model or provider without rebuilding the sandbox, use `nemohermes inference set`.
It updates the OpenShell inference route and patches `/sandbox/.hermes/config.yaml` without restarting Hermes.
```bash
nemohermes inference set --model <model> --provider <provider>
```
To remove the sandbox when you are done, destroy it explicitly.
```bash
nemohermes my-hermes destroy
```
## Next Steps
- Inference Options (use the `nemoclaw-user-configure-inference` skill) to choose a provider and model.
- Commands (use the `nemoclaw-user-reference` skill) to see the full `nemohermes` alias behavior.
- Backup and Restore (use the `nemoclaw-user-manage-sandboxes` skill) to preserve sandbox state before destructive operations.
- Monitor Sandbox Activity (use the `nemoclaw-user-monitor-sandbox` skill) to inspect OpenShell events and sandbox logs.

168
.agents/skills/nemoclaw-user-get-started/references/windows-preparation.md
View file

@ -1,168 +0,0 @@
# Prepare Windows for NemoClaw
import { AgentOnly } from "../_components/AgentGuide";
You can run NemoClaw inside Windows Subsystem for Linux (WSL 2) on Windows.
<AgentOnly variant="openclaw">
Complete these steps before following the Quickstart.
</AgentOnly>
<AgentOnly variant="hermes">
Complete these steps before following Quickstart with Hermes.
</AgentOnly>
Linux and macOS users do not need this page and can go directly to the Quickstart.
**Note:**
NVIDIA tested this guide on x86-64.
## Prerequisites
Verify the following before you begin:
- Windows 10 (build 19041 or later) or Windows 11.
<AgentOnly variant="openclaw">
- Hardware requirements are the same as the Quickstart.
</AgentOnly>
<AgentOnly variant="hermes">
- Hardware requirements are the same as Quickstart with Hermes.
</AgentOnly>
## Option: Use the Bootstrap Script
Open Windows PowerShell on the Windows host and run the bootstrap script:
```powershell
Invoke-WebRequest -Uri 'https://raw.githubusercontent.com/NVIDIA/NemoClaw/main/scripts/bootstrap-windows.ps1' -OutFile "$env:TEMP\bootstrap-windows.ps1"; powershell.exe -ExecutionPolicy Bypass -File "$env:TEMP\bootstrap-windows.ps1"
```
The command downloads the script to a temporary file before running it.
`-ExecutionPolicy Bypass` applies only to that PowerShell process and avoids local policy blocking the downloaded script.
Run it from Windows, not from inside WSL.
The script requests Administrator privileges when needed, enables the required WSL 2 Windows features, installs or opens Ubuntu 24.04, and installs and starts Docker Desktop.
When Ubuntu needs first-run account setup, the script opens a handoff window and waits for that account to exist before it changes Docker settings.
It enables Docker Desktop WSL integration for the target distro, restarts Docker Desktop only when Docker was already running, and leaves your global default WSL distro unchanged.
If the target Ubuntu distro is already registered, the script confirms it uses WSL 2, converts it from WSL 1 when needed, and verifies Docker is reachable from WSL.
If Windows requires a reboot after enabling WSL features, the script prompts for the reboot and registers a one-time continuation for the next sign-in.
If Docker Desktop shows first-run prompts, complete them and return to the PowerShell window.
For advanced options, download the script first and run `Get-Help "$env:TEMP\bootstrap-windows.ps1" -Detailed`.
Useful parameters include `-DistroName`, `-InstallerUrl`, `-InstallerArgs`, and `-InstallDockerDesktop`.
The default distro is `Ubuntu-24.04`.
To reuse an existing distro named `Ubuntu`, pass `-DistroName Ubuntu`.
The bootstrap script does not install NemoClaw itself.
When Windows preparation is complete, it opens Ubuntu and prints the standard installer command to run inside Ubuntu:
```bash
curl -fsSL https://www.nvidia.com/nemoclaw.sh | bash
```
If the bootstrap script reports that Ubuntu cannot reach Docker, open Docker Desktop Settings and confirm that Docker Desktop enables WSL integration for Ubuntu (**Settings** > **Resources** > **WSL integration**), make sure Docker Desktop is running, then rerun the script.
If the bootstrap script reports that `winget.exe` is not available (common on Windows Server or stripped Windows installs), install **App Installer** from the Microsoft Store (which provides `winget`), or download and install Docker Desktop manually from [docker.com](https://www.docker.com/products/docker-desktop/).
After you install Docker Desktop, rerun the bootstrap script.
The script skips the install step after it detects Docker Desktop.
The manual steps below describe the same Windows preparation pieces and are useful when you need to verify or repair WSL, Ubuntu, or Docker Desktop by hand.
## Enable WSL 2
Open an elevated PowerShell (Run as Administrator):
```powershell
wsl --install --no-distribution
```
This enables both the Windows Subsystem for Linux and Virtual Machine Platform features.
Reboot if prompted.
## Install and Register Ubuntu
After reboot, open an elevated PowerShell again:
```powershell
wsl --install -d Ubuntu-24.04
```
Let the distribution launch and complete first-run setup (pick a Unix username and password), then type `exit` to return to PowerShell.
**Warning:**
Do not use the `--no-launch` flag.
The `--no-launch` flag downloads the package but does not register the distribution with WSL.
Commands like `wsl -d Ubuntu-24.04` fail with "There is no distribution with the supplied name" until you launch the distribution at least one time.
Verify that WSL registered the distribution and runs it with WSL 2:
```powershell
wsl -l -v
```
Expected output:
```text
NAME STATE VERSION
* Ubuntu-24.04 Running 2
```
## Install Docker Desktop
Install [Docker Desktop](https://www.docker.com/products/docker-desktop/) with the WSL 2 backend (the default on Windows 11).
After installation, open Docker Desktop Settings and confirm that Docker Desktop enables WSL integration for your Ubuntu distribution (**Settings** > **Resources** > **WSL integration**).
Open WSL from PowerShell:
```powershell
wsl
```
Then verify Docker from inside WSL:
```bash
docker info
```
`docker info` prints server information.
If you see "Cannot connect to the Docker daemon", confirm that Docker Desktop is running and that Docker Desktop enables WSL integration.
## Set Up Local Inference with Ollama (Optional)
If you plan to select Ollama as your inference provider during onboarding, use one Ollama instance that WSL can reach.
You can install Ollama inside WSL yourself:
```bash
curl -fsSL https://ollama.com/install.sh | sh
```
If you installed Ollama but it is not already running in WSL, onboarding starts it for you.
You can also start it yourself beforehand with `ollama serve`.
You can also use Ollama for Windows.
During onboarding, NemoClaw can use an already-running Windows-host daemon, start or restart an installed daemon, or install Ollama on the Windows host.
If the installer offers express install on WSL, accepting it selects this Windows-host Ollama path automatically.
When Ollama runs on the Windows host, NemoClaw detects it from WSL through `host.docker.internal` and pulls missing models through the Ollama HTTP API.
Do not run both the Windows and WSL Ollama instances on port `11434` at the same time.
Use one instance, or move one of them to a different port before running `nemoclaw onboard`.
## Next Step
Your Windows environment is ready.
If you used the bootstrap script, follow the installer command it printed inside Ubuntu.
<AgentOnly variant="openclaw">
If you prepared Windows manually, open a WSL terminal (type `wsl` in PowerShell, or open Ubuntu from Windows Terminal) and continue with the Quickstart to install NemoClaw and launch your first sandbox.
</AgentOnly>
<AgentOnly variant="hermes">
If you prepared Windows manually, open a WSL terminal (type `wsl` in PowerShell, or open Ubuntu from Windows Terminal) and continue with Quickstart with Hermes to install NemoClaw and launch your first Hermes sandbox.
</AgentOnly>
All NemoClaw commands run inside WSL, not in PowerShell.
## Troubleshooting
For Windows-specific troubleshooting, refer to the Windows Subsystem for Linux section in the Troubleshooting guide.

68
.agents/skills/nemoclaw-user-guide/SKILL.md Normal file
View file

@ -0,0 +1,68 @@
---
name: "nemoclaw-user-guide"
description: "Guides human users' AI agents to the NemoClaw docs MCP server and canonical Fern documentation in Markdown form. Use when users ask how to install, configure, operate, troubleshoot, secure, or learn NemoClaw with an AI coding assistant. Trigger keywords - nemoclaw docs, use nemoclaw with ai agent, nemoclaw mcp docs, nemoclaw install help, nemoclaw quickstart, nemoclaw markdown docs, llms.txt, agent skills."
license: "Apache-2.0"
---
# NemoClaw Docs for AI Agents
Use the canonical NemoClaw documentation as your source of truth.
Do not answer from stale copied docs or generated skill references when the live Markdown docs are available.
## Retrieval Order
1. If the assistant supports MCP, configure the NemoClaw docs MCP server at `https://docs.nvidia.com/nemoclaw/_mcp/server`.
2. Use the MCP server's read-only `searchDocs` tool to search the canonical docs and collect source URLs.
3. If MCP is not available, fetch the AI documentation index first: `https://docs.nvidia.com/nemoclaw/llms.txt`.
4. Fetch the specific `.md` page listed in the index or returned by docs search for the user's task.
5. If you only find an HTML documentation URL, replace the `.html` suffix with `.md`, or append `.md` to the route when the URL has no suffix.
6. Prefer the user's selected agent variant, either OpenClaw or Hermes, and do not mix variant-specific instructions unless you explain why.
## Configure the MCP Server
For Claude Code, run:
```bash
claude mcp add --transport http fern-docs https://docs.nvidia.com/nemoclaw/_mcp/server
```
For Cursor, add `https://docs.nvidia.com/nemoclaw/_mcp/server` to the MCP server configuration.
For other MCP clients, configure a streamable HTTP MCP server at that URL.
## Starting Pages
Use these pages first for common onboarding flows:
- OpenClaw home: `https://docs.nvidia.com/nemoclaw/latest/user-guide/openclaw/home.md`.
- OpenClaw prerequisites: `https://docs.nvidia.com/nemoclaw/latest/user-guide/openclaw/get-started/prerequisites.md`.
- OpenClaw quickstart: `https://docs.nvidia.com/nemoclaw/latest/user-guide/openclaw/get-started/quickstart.md`.
- Hermes home: `https://docs.nvidia.com/nemoclaw/latest/user-guide/hermes/home.md`.
- Hermes prerequisites: `https://docs.nvidia.com/nemoclaw/latest/user-guide/hermes/get-started/prerequisites.md`.
- Hermes quickstart: `https://docs.nvidia.com/nemoclaw/latest/user-guide/hermes/get-started/quickstart.md`.
## How to Help the User
- Ask which agent variant they want to use before giving setup instructions: OpenClaw or Hermes.
- Ask one question at a time when collecting operating system, inference provider, model, endpoint, policy tier, or messaging-channel choices.
- Run commands for non-technical users when your environment allows it, after explaining what the command does and getting permission.
- Summarize important command output instead of asking the user to paste terminal output into chat.
- Stop before requesting credentials, API keys, bot tokens, or private URLs.
- Never ask the user to paste secrets into chat.
- Use redacted placeholders such as `<PASTE_YOUR_API_KEY_HERE>` in examples.
## Common Task Routing
- Installation and first sandbox: fetch the selected variant's prerequisites and quickstart pages.
- Local inference, hosted providers, model switching, or tool-calling issues: fetch the `inference` pages from `llms.txt`.
- Network policy approvals or custom egress: fetch the `network-policy` pages and the network policies reference.
- Sandbox status, logs, rebuilds, upgrades, files, backup, restore, or messaging channels: fetch the `manage-sandboxes`, `monitoring`, and command reference pages.
- Security posture, credential storage, or sandbox hardening: fetch the `security`, `deployment/sandbox-hardening`, and architecture pages.
- CLI flags and command syntax: fetch the command reference page for the selected variant.
- Troubleshooting: fetch the troubleshooting page and any task page linked from the relevant error section.
## Response Requirements
- Cite the Markdown documentation pages you used.
- Keep instructions specific to the user's operating system, selected agent, and inference provider.
- Explain assumptions when the docs do not cover the exact environment.
- Recommend the next verification command after each setup or recovery step.

57
.agents/skills/nemoclaw-user-guide/evals/evals.json Normal file
View file

@ -0,0 +1,57 @@
[
{
"id": "nemoclaw-user-guide-install-openclaw-001",
"question": "Help me install NemoClaw with OpenClaw from my coding assistant. I need the official docs and I do not want to paste secrets into chat.",
"expected_skill": "nemoclaw-user-guide",
"ground_truth": "A NemoClaw-specific answer that uses the user guide skill to route the assistant to `llms.txt` and the OpenClaw Markdown prerequisites and quickstart pages, asks one setup question at a time, and handles credentials with redacted placeholders instead of chat-transcribed secrets.",
"expected_behavior": [
"Uses `nemoclaw-user-guide`.",
"Starts from `https://docs.nvidia.com/nemoclaw/llms.txt` and the OpenClaw `.md` docs.",
"Does not tell the user to paste secrets into chat."
]
},
{
"id": "nemoclaw-user-guide-mcp-server-001",
"question": "Configure my coding assistant to search the NemoClaw docs through MCP before answering setup questions.",
"expected_skill": "nemoclaw-user-guide",
"ground_truth": "A NemoClaw-specific answer that uses the user guide skill to configure the docs MCP server at `https://docs.nvidia.com/nemoclaw/_mcp/server`, mentions the read-only `searchDocs` docs search tool, and gives client-specific setup guidance such as the Claude Code command or Cursor MCP server configuration.",
"expected_behavior": [
"Uses `nemoclaw-user-guide`.",
"Includes `https://docs.nvidia.com/nemoclaw/_mcp/server`.",
"Mentions MCP docs search before falling back to Markdown docs."
]
},
{
"id": "nemoclaw-user-guide-hermes-variant-001",
"question": "Use the Hermes version of the NemoClaw docs and walk me through the first sandbox setup.",
"expected_skill": "nemoclaw-user-guide",
"ground_truth": "A NemoClaw-specific answer that selects the Hermes documentation variant, fetches the Hermes Markdown home, prerequisites, and quickstart pages, and avoids mixing OpenClaw-specific instructions unless the difference is explained.",
"expected_behavior": [
"Uses `nemoclaw-user-guide`.",
"Routes to Hermes `.md` pages.",
"Keeps instructions variant-specific."
]
},
{
"id": "nemoclaw-user-guide-local-inference-001",
"question": "Switch my NemoClaw sandbox to local Ollama and use the Markdown docs instead of guessing.",
"expected_skill": "nemoclaw-user-guide",
"ground_truth": "A NemoClaw-specific answer that routes through `llms.txt` to the inference Markdown pages, gathers provider and model choices one at a time, and recommends verification after the switch.",
"expected_behavior": [
"Uses `nemoclaw-user-guide`.",
"Fetches inference pages from the Markdown docs.",
"Recommends a verification step after configuration."
]
},
{
"id": "nemoclaw-user-guide-policy-troubleshooting-001",
"question": "My agent hit a blocked network request. Help me find the right NemoClaw docs for approving it safely.",
"expected_skill": "nemoclaw-user-guide",
"ground_truth": "A NemoClaw-specific answer that routes to the network-policy Markdown pages and relevant troubleshooting or command reference pages, explains assumptions, and avoids granting broad egress without context.",
"expected_behavior": [
"Uses `nemoclaw-user-guide`.",
"Fetches network policy and troubleshooting Markdown docs.",
"Frames approval as a least-privilege workflow."
]
}
]

383
.agents/skills/nemoclaw-user-manage-policy/SKILL.md
View file

@ -1,383 +0,0 @@
---
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 integration policy examples, post-install policy setup, openshell approval workflow, policy preset, nemoclaw approve network requests, sandbox egress approval tui."
license: "Apache-2.0"
---
# Customize the Sandbox Network Policy
## Gotchas
- Adding a host to the egress policy permits the connection only after the endpoint, port, method, and binary rules match.
- Custom preset hosts bypass NemoClaw's review process and can widen sandbox egress to arbitrary destinations.
## Prerequisites
- A running NemoClaw sandbox for dynamic changes, or the NemoClaw source repository for static changes.
- The OpenShell CLI on your `PATH`.
import { AgentOnly } from "../_components/AgentGuide";
Add, remove, or modify the endpoints the sandbox can reach.
The NemoClaw repository defines the sandbox policy in a declarative YAML file, and [NVIDIA OpenShell](https://github.com/NVIDIA/OpenShell) enforces it at runtime.
NemoClaw supports both static policy changes that persist across restarts and dynamic updates applied to a running sandbox through the OpenShell CLI.
**Note:**
If the sandbox needs to reach an HTTP service running on the host, expose the service on a host IP that the OpenShell gateway can reach.
Apply a custom NemoClaw preset with `nemoclaw <sandbox> policy-add --from-file`.
Do not rely on `host.docker.internal` as a general host-service path because it bypasses the OpenShell policy path and may not be reachable in every sandbox runtime.
See Agent cannot reach a host-side HTTP service (use the `nemoclaw-user-reference` skill).
**Warning:**
Adding a host to the egress policy permits the connection only after the endpoint, port, method, and binary rules match.
OpenShell still applies SSRF protection separately, so a request can be denied if the final address resolves to a loopback, private, link-local, or otherwise blocked internal range.
If a package installer or browser runtime download still fails with an SSRF-style denial after you add the public host, install that binary into the sandbox image at build time with `nemoclaw onboard --from` (use the `nemoclaw-user-reference` skill) instead of relying on runtime egress.
## Static Changes
Static changes modify the baseline policy file and take effect after the next sandbox creation.
### Edit the Policy File
<AgentOnly variant="openclaw">
Open `nemoclaw-blueprint/policies/openclaw-sandbox.yaml` and add or modify endpoint entries.
If you want a built-in preset to be part of the baseline policy, merge its `network_policies` entries into this file and re-run `nemoclaw onboard`.
If you only need to apply a preset to a running sandbox, use `nemoclaw <name> policy-add` under [Dynamic Changes](#dynamic-changes).
That updates the live policy and does not edit `openclaw-sandbox.yaml`.
</AgentOnly>
<AgentOnly variant="hermes">
Open the Hermes policy additions and shared sandbox policy files under `agents/hermes/` and `nemoclaw-blueprint/policies/`, then add or modify endpoint entries.
If you want a built-in preset to be part of the baseline policy, merge its `network_policies` entries into the appropriate policy file and re-run `nemoclaw onboard`.
If you only need to apply a preset to a running sandbox, use `nemoclaw <name> policy-add` under [Dynamic Changes](#dynamic-changes).
That updates the live policy and does not edit the baseline policy files.
</AgentOnly>
Use a manual YAML edit when you need to allow custom hosts that are not covered by a preset, such as an internal API or a weather service.
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:
```bash
nemoclaw onboard
```
The wizard reads the modified policy file and applies it to the sandbox.
### Verify the Policy
Check that the sandbox is running with the updated policy:
```bash
nemoclaw <name> status
```
### Add Blueprint Policy Additions
If you maintain a custom blueprint, you can add extra policy entries under `components.policy.additions` in `nemoclaw-blueprint/blueprint.yaml`.
NemoClaw validates those entries with the same policy schema used by preset files, fetches the live policy during sandbox creation, merges the additions into `network_policies`, and applies the merged policy through OpenShell.
The applied additions are recorded in the run metadata so you can audit which blueprint-level policy entries were active for that sandbox run.
## Dynamic Changes
Dynamic changes apply a policy update to a running sandbox without restarting it.
> [!WARNING]
> `openshell policy set` **replaces** the sandbox's live policy with the contents of the file you provide; it does not merge.
> A running sandbox's live policy is the baseline policy plus every preset that was layered on during onboarding.
> Applying a file that contains only the baseline (or only a single preset) silently drops every other preset that was in effect.
### Option 1: Drop a Preset File and Use `policy-add` (Recommended)
This is the non-destructive path and the only flow NemoClaw supports out of the box for merging new entries into a running policy.
1. Create a preset-format YAML file under `nemoclaw-blueprint/policies/presets/`, for example `nemoclaw-blueprint/policies/presets/influxdb.yaml`:
```yaml
preset:
name: influxdb
description: "InfluxDB time-series database"
network_policies:
influxdb:
name: influxdb
endpoints:
- host: influxdb.internal.example.com
port: 8086
protocol: rest
enforcement: enforce
rules:
- allow: { method: GET, path: "/**" }
- allow: { method: POST, path: "/api/v2/write" }
binaries:
- { path: /usr/bin/curl }
```
2. Apply it to the running sandbox:
```bash
nemoclaw my-assistant policy-add
```
NemoClaw reads the live policy via `openshell policy get --full`, structurally merges your preset's `network_policies` into it, and writes the merged result back.
Existing presets and the baseline remain in place.
The preset file under `presets/` also persists across sandbox recreations.
### Option 2: Snapshot, Edit, and Set with OpenShell
Use this path only when you cannot add a file under the NemoClaw source tree.
You must start from the **live** policy, not from a baseline policy file, so the presets layered on at onboarding are preserved in the file you apply.
```bash
openshell policy get --full my-assistant > live-policy.yaml
```
Edit `live-policy.yaml` to add your entries under `network_policies:`, keeping the existing `version` field intact, then apply:
```bash
openshell policy set --policy live-policy.yaml my-assistant
```
### Scope of Dynamic Changes
Dynamic changes apply only to the current session.
When the sandbox stops, the running policy resets to the baseline policy plus the presets recorded for the sandbox.
Custom presets applied through `nemoclaw <sandbox> policy-add --from-file` or `--from-dir` are recorded with the sandbox, including their full YAML content.
Snapshot restore and rebuild replay those recorded presets, so they survive sandbox recreation even if the original files are no longer on disk.
For permanent baseline changes that apply to every future sandbox, edit the source policy for the target agent and re-run `nemoclaw onboard`.
### Approve Requests Interactively
For one-off access, you can approve blocked requests in the OpenShell TUI instead of editing the baseline policy:
```bash
openshell term
```
This is useful when you want to test a destination before deciding whether it belongs in a permanent preset or custom policy file.
## 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.
For guided post-install examples, see [Common Integration Policy Examples](references/integration-policy-examples.md).
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.
Available presets:
| Preset | Endpoints |
|--------|-----------|
| `brave` | Brave Search API |
| `brew` | Homebrew (Linuxbrew) package manager |
| `discord` | Discord API, gateway, and CDN access |
| `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 |
| `openclaw-pricing` | OpenClaw model-pricing reference fetch (LiteLLM and OpenRouter) |
| `outlook` | Microsoft 365 and Outlook |
| `pypi` | Python Package Index |
| `slack` | Slack API and webhooks |
| `telegram` | Telegram Bot API |
| `wechat` | WeChat (personal) iLink Bot API (experimental) |
| `whatsapp` | WhatsApp Web messaging (experimental) |
To apply a preset to a running sandbox:
```bash
nemoclaw <name> policy-add
```
**Note:**
Preset selection is interactive when you omit a preset name.
Pass a preset name with `--yes` for scripted workflows.
For example, to interactively add PyPI access to a running sandbox:
```bash
nemoclaw my-assistant policy-add
```
To list which presets are applied to a sandbox:
```bash
nemoclaw <name> policy-list
```
<AgentOnly variant="openclaw">
To include a preset in the baseline, merge its entries into `openclaw-sandbox.yaml` and re-run `nemoclaw onboard`.
</AgentOnly>
<AgentOnly variant="hermes">
To include a preset in the baseline, merge its entries into the Hermes policy additions and re-run `nemoclaw onboard`.
</AgentOnly>
**Note:**
The `openshell policy set --policy <file> <sandbox-name>` command operates on raw policy files and does not accept the `preset:` metadata block used in preset YAML files.
Use `nemoclaw <name> policy-add` for presets.
For scripted workflows, `policy-add` and `policy-remove` accept the preset name as a positional argument:
```bash
nemoclaw my-assistant policy-add pypi --yes
nemoclaw my-assistant policy-remove pypi --yes
```
Set `NEMOCLAW_NON_INTERACTIVE=1` instead of `--yes` to drive the same flow from an environment variable.
See Commands (use the `nemoclaw-user-reference` skill) for the full flag reference.
`nemoclaw <name> rebuild` reapplies every policy preset to the recreated sandbox, so presets survive an agent-version upgrade without manual reapplication.
## Custom Preset Files
Apply a user-authored preset YAML to a running sandbox without editing the baseline or dropping to `openshell policy set`.
### Authoring
A custom preset follows the same shape as the built-in ones under `nemoclaw-blueprint/policies/presets/`:
```yaml
preset:
name: my-internal-api
description: "Internal service"
network_policies:
my-internal-api:
name: my-internal-api
endpoints:
- host: api.example.internal
port: 443
protocol: rest
enforcement: enforce
rules:
- allow: { method: GET, path: "/**" }
binaries:
- { path: /usr/local/bin/node }
```
The top-level `preset.name` must be a lowercase RFC 1123 label (letters, digits, hyphens) and must not collide with a built-in preset name such as `slack` or `pypi`.
Rename `preset.name` if NemoClaw refuses to apply the file because of a collision.
### Apply a Single File
```bash
nemoclaw my-assistant policy-add --from-file ./presets/my-internal-api.yaml
```
Preview the endpoints without applying with `--dry-run`, and skip the confirmation prompt with `--yes` or by exporting `NEMOCLAW_NON_INTERACTIVE=1`.
### Apply Every File in a Directory
```bash
nemoclaw my-assistant policy-add --from-dir ./presets/ --yes
```
Files are processed in lexicographic order.
Processing stops at the first failure; presets already applied are not rolled back.
Fix the failing file and re-run the command to continue.
**Warning:**
Custom preset hosts bypass NemoClaw's review process and can widen sandbox egress to arbitrary destinations.
Review every host in a custom preset before applying it, especially when the file originates outside your team.
### Remove a Custom Preset
NemoClaw records custom presets applied with `--from-file` or `--from-dir` in the sandbox registry alongside their full YAML content.
You can remove them by name without keeping the original file on disk:
```bash
nemoclaw my-assistant policy-remove my-internal-api --yes
```
`policy-remove` accepts both built-in and custom preset names. Run `nemoclaw <name> policy-list` to see every preset currently applied to the sandbox.
## Agent Policy Context
When an agent runs in the sandbox, it needs a compact view of the active policy so it can decide whether a host or integration is allowed and what to suggest when something fails.
`nemoclaw <name> policy-explain` prints that view as a redacted summary: the recorded tier, the applied presets and their allowed host categories, the known presets that are not applied, the inspect/add/remove commands that change policy, and the support boundaries between NemoClaw, OpenShell, and the agent.
```bash
nemoclaw my-assistant policy-explain
```
Pass `--json` to emit the same context as a structured object the agent can read:
```bash
nemoclaw my-assistant policy-explain --json
```
NemoClaw also seeds the rendered context inside the sandbox at `/sandbox/.openclaw/workspace/POLICY.md` once during onboarding and refreshes it on every `policy-add` or `policy-remove`, so the in-sandbox agent picks it up when it scans the workspace.
Pass `--write` to refresh that file on demand without changing the policy:
```bash
nemoclaw my-assistant policy-explain --write
```
The output is intentionally redacted.
Network policy rule bodies, credential metadata, and binary allowlists are not included; only host stems and category-level summaries appear.
Host stems that resolve to RFC 1918 ranges (10/8, 172.16/12, 192.168/16), loopback (127/8, `::1`), link-local (169.254/16, `fe80::/10`), cloud metadata (`169.254.169.254`), unique-local IPv6 (`fc00::/7`), reserved zero (0.0.0.0/8), CGNAT (100.64/10), benchmarking (198.18/15), `localhost`, and the internal DNS suffixes `.local`, `.internal`, `.lan`, `.home`, `.home.arpa`, `.corp`, `.intra`, `.intranet`, `.localdomain` are dropped from `allowedHostCategories` and surface as a `redactedHostCount`.
Each active preset also carries a `verification` field that tells the agent whether the OpenShell gateway actually enforces it:
| Status | Meaning |
|--------|---------|
| `verified` | Registry lists the preset and the gateway confirms it is enforced. Safe to treat the host stems as allowed. |
| `registry-only` | Registry lists the preset but the gateway does not enforce it (drift). Treat allowed hosts as unverified; the agent should not assume the traffic will reach the host. |
| `gateway-only` | Gateway enforces a preset the registry does not list. Reported as active so the agent does not misclassify allowed hosts as blocked. |
| `gateway-unavailable` | Could not probe the gateway (no live snapshot). The whole report is advisory; rely on `nemoclaw <sandbox> policy-list` once the gateway is reachable. |
The context also documents how the agent should classify a failed host or integration attempt.
The rules are evaluated in order so HTTP 403 has a single interpretation per call: when the host matches an applied preset the request is treated as an authentication failure, otherwise as a policy denial.
1. `unsupported` — the caller asserts the capability is not offered for this sandbox (for example, a messaging channel that the active agent does not support). The agent should surface the limitation without retrying.
2. `missing-approval` — the host **is** allowed by an applied preset and the request was refused with HTTP 401. The network path is open; credentials are missing or invalid.
3. `missing-approval` (low confidence) — the host **is** allowed by an applied preset and the request was refused with HTTP 403. Ambiguous: OpenShell policies enforce by method, path, protocol, and binary, so a 403 on an allowed host can still be a finer-grained policy denial rather than missing credentials. Confirm credentials first, then run `openshell policy get` to check whether the specific method or path is blocked.
4. `blocked-by-policy` — either the host is **not** allowed by any applied preset and either an existing built-in or custom preset declares it (apply that preset), or the request is refused with a network-block error code (`EHOSTUNREACH`, `ENETUNREACH`, `ENOTFOUND`, `ECONNREFUSED`, `ETIMEDOUT`, `EAI_AGAIN`) or HTTP 403. The same network-block codes also surface as `blocked-by-policy` (low confidence) when the host is on an applied but **unverified** preset (`registry-only` or `gateway-unavailable`), because a block code on a host the registry says should be allowed is the strongest signal that the gateway is not enforcing the preset.
5. `unknown` — none of the above apply; the agent should surface the underlying error. A network-block code on a host that matches a **verified** preset stays `unknown` because the gateway has confirmed enforcement, so the block must be an upstream connectivity failure rather than a policy denial.
Each classification also carries a `confidence` field set to `high` or `low`. Low-confidence verdicts mean the agent should report multiple possibilities to the user instead of treating the next-step recommendation as authoritative. Common low-confidence triggers are:
- HTTP 403 on an active host (ambiguous between missing credentials and a finer-grained OpenShell denial by method, path, protocol, or binary).
- The matched preset is `registry-only` (the registry lists it but the gateway does not enforce it) — the agent must not assume the host is reachable.
- The matched preset is `gateway-unavailable` (no live gateway snapshot was available) — the verdict is registry-derived and advisory.
Callers that already hold a verified gateway snapshot can pass it to the classifier so verdicts about hosts on verified presets stay high-confidence.
Use the classification to pick the next step.
For `blocked-by-policy`, run `nemoclaw <name> policy-add <preset>` or author a [custom preset](#custom-preset-files).
For `missing-approval`, confirm the API token and scopes for the integration.
For `unsupported`, surface the limitation to the user without retrying.
## 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
- [Approve or Deny Agent Network Requests](references/approve-network-requests.md) for real-time operator approval.
- [Common Integration Policy Examples](references/integration-policy-examples.md) for maintained preset examples such as Outlook, messaging, GitHub, Jira, Brave Search, package managers, Hugging Face, and local inference.
- `nemoclaw-user-reference` — Network Policies (use the `nemoclaw-user-reference` skill) for the full baseline policy reference
- 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.

11
.agents/skills/nemoclaw-user-manage-policy/evals/evals.json
View file

@ -1,11 +0,0 @@
[
{
"id": "docs-network-policy-customize-network-policy-001",
"question": "I'm customizing sandbox network policy. Help me allow the agent to reach a required external service so I can enable the integration while preserving least privilege.",
"expected_skill": "nemoclaw-user-manage-policy",
"ground_truth": "A NemoClaw-specific answer that helps the user allow the agent to reach a required external service and gives enough concrete guidance, decision criteria, verification steps, or risk framing to enable the integration while preserving least privilege.",
"expected_behavior": [
"Uses the expected_skill and does not make up answers if it cannot find the answer from the skill."
]
}
]

63
.agents/skills/nemoclaw-user-manage-policy/references/approve-network-requests.md
View file

@ -1,63 +0,0 @@
# Approve or Deny Agent Network Requests
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.
## Prerequisites
- A running NemoClaw sandbox.
- The OpenShell CLI on your `PATH`.
## Open the TUI
Start the OpenShell terminal UI to monitor sandbox activity:
```bash
openshell term
```
For a remote sandbox, pass the instance name:
```bash
ssh my-gpu-box 'cd ~/nemoclaw && . .env && openshell term'
```
The TUI displays the sandbox state, active inference provider, and a live feed of network activity.
## 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.
## 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.
To keep an endpoint allowed after a restart, update the policy YAML or apply a preset as described in [Customize the Sandbox Network Policy](../SKILL.md).
## Run the Walkthrough
From the NemoClaw repository root, run the walkthrough script after you have onboarded at least one sandbox and it is reachable:
```bash
./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_INFERENCE_API_KEY` environment variable.
It assumes an existing sandbox to attach to.
## Related Topics
- [Customize the Sandbox Network Policy](../SKILL.md) to add endpoints permanently.
- Network Policies (use the `nemoclaw-user-reference` skill) for the full baseline policy reference.
- Monitor Sandbox Activity (use the `nemoclaw-user-monitor-sandbox` skill) for general sandbox monitoring.

375
.agents/skills/nemoclaw-user-manage-policy/references/integration-policy-examples.md
View file

@ -1,375 +0,0 @@
# Common NemoClaw Integration Policy Examples
import { AgentOnly } from "../_components/AgentGuide";
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/`.
For complete blueprint examples that combine a model, agent harness, OpenShell policy, and integration workflow, see [NemoClaw Community](https://github.com/NVIDIA/nemoclaw-community).
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:
```bash
nemoclaw my-assistant policy-list
```
For a live view of blocked requests, open the OpenShell TUI in a separate host terminal:
```bash
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 reviewable NemoClaw preset entry that `policy-add` can replay.
## 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` |
| OpenClaw model-pricing reference fetch | `openclaw-pricing` |
| npm and Yarn packages | `npm` |
| Microsoft 365, Outlook, and Graph API | `outlook` |
| Public reference APIs | `public-reference` |
| Python Package Index | `pypi` |
| Slack messaging | `slack` |
| Telegram Bot API | `telegram` |
| Weather and geocoding APIs | `weather` |
| WeChat (personal) iLink Bot API (experimental) | `wechat` |
| WhatsApp Web messaging (experimental) | `whatsapp` |
Preview the endpoints before applying:
```bash
nemoclaw my-assistant policy-add outlook --dry-run
```
Apply the preset:
```bash
nemoclaw my-assistant policy-add outlook --yes
```
Remove it later if the sandbox no longer needs that access:
```bash
nemoclaw my-assistant policy-remove outlook --yes
```
## Email and Calendar With Microsoft 365
Use the `outlook` preset for Microsoft 365 email and calendar workflows that use Microsoft Graph or Outlook endpoints.
The preset allows `graph.microsoft.com`, Microsoft login, and Outlook service endpoints.
```bash
nemoclaw my-assistant policy-add outlook --dry-run
nemoclaw my-assistant policy-add outlook --yes
```
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:
```bash
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:
```bash
export TELEGRAM_BOT_TOKEN=<your-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:
```bash
openshell term
```
The matching preset for each supported messaging channel is the channel name (`telegram`, `discord`, `slack`, `wechat`, or `whatsapp`).
## 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:
```bash
export SLACK_BOT_TOKEN=<your-slack-bot-token>
export SLACK_APP_TOKEN=<your-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:
```bash
export DISCORD_BOT_TOKEN=<your-discord-bot-token>
export DISCORD_SERVER_ID=<your-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:
```bash
nemoclaw my-assistant policy-add slack --yes
nemoclaw my-assistant policy-add discord --yes
```
## WeChat or WhatsApp Messaging (Experimental)
WeChat and WhatsApp are experimental.
Both rely on QR-based pairing flows that are more fragile than token-based bots.
The upstream client libraries can change behavior without notice.
WeChat uses Tencent's iLink Bot API for personal accounts.
The bot token is captured by a host-side QR scan during onboarding rather than pasted from a developer portal.
Add the channel interactively and apply the preset:
```bash
nemoclaw my-assistant channels add wechat
nemoclaw my-assistant rebuild
nemoclaw my-assistant policy-add wechat --yes
```
WhatsApp Web pairs entirely inside the sandbox through QR scan, so `channels add` does not collect a host-side token.
Apply the preset and complete the in-sandbox pairing after the rebuild:
```bash
NEMOCLAW_NON_INTERACTIVE=1 nemoclaw my-assistant channels add whatsapp
nemoclaw my-assistant rebuild
nemoclaw my-assistant policy-add whatsapp --yes
```
If you enabled WeChat or WhatsApp during onboarding, apply only the matching preset:
```bash
nemoclaw my-assistant policy-add wechat --yes
nemoclaw my-assistant policy-add whatsapp --yes
```
## GitHub and Jira
Use `github` when the agent needs GitHub API or Git access.
Use `jira` when the agent needs Atlassian Jira access.
Preview first:
```bash
nemoclaw my-assistant policy-add github --dry-run
nemoclaw my-assistant policy-add jira --dry-run
```
Apply the preset that matches the workflow:
```bash
nemoclaw my-assistant policy-add github --yes
nemoclaw my-assistant policy-add jira --yes
```
The `jira` preset intentionally allows Node.js access to Atlassian Cloud and does not allow `curl`.
When validating it manually, avoid plain `curl -s` against `auth.atlassian.com`.
Atlassian can return an empty redirect body even when the request succeeds.
An empty `curl -s` output from that endpoint is inconclusive before or after approval; do not use it as a pass/fail signal.
Use a body-visible API probe instead:
```bash
node -e "require('https').get('https://api.atlassian.com', r => console.log(r.statusCode))"
curl -sS --max-time 10 -w '\n%{http_code}\n' https://api.atlassian.com/oauth/token/accessible-resources
```
Before approval, the curl probe should report `000` or a local policy denial.
After explicitly approving curl for `api.atlassian.com` in OpenShell, it should return Atlassian's unauthenticated `401` JSON response.
That `401` is the expected success signal for this manual probe.
This manual probe proves curl reached Atlassian, but no Jira credentials were supplied.
Remove access when the task is done:
```bash
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:
```bash
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.
## Weather and Public Reference Lookups
Use the `weather` preset when the agent needs read-only weather or geocoding lookups.
The Balanced and Open tiers include it by default.
The preset covers Open-Meteo, geocoding, and National Weather Service endpoints without enabling messaging or productivity APIs.
```bash
nemoclaw my-assistant policy-add weather --dry-run
nemoclaw my-assistant policy-add weather --yes
```
Use the `public-reference` preset when the agent needs read-only public-reference APIs, such as Wikipedia, Wikidata, Wikimedia Commons, Nominatim, or country metadata.
The Open tier includes this preset by default.
```bash
nemoclaw my-assistant policy-add public-reference --dry-run
nemoclaw my-assistant policy-add public-reference --yes
```
## 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 with `pip`, Python, or `uv` | `pypi` |
| Homebrew packages | `brew` |
| Hugging Face model or dataset access | `huggingface` |
Add only the preset required for the task:
```bash
nemoclaw my-assistant policy-add npm --yes
nemoclaw my-assistant policy-add pypi --yes
nemoclaw my-assistant policy-add brew --yes
nemoclaw my-assistant policy-add huggingface --yes
```
Remove package access after a one-time setup task if the sandbox no longer needs it:
```bash
nemoclaw my-assistant policy-remove npm --yes
nemoclaw my-assistant policy-remove pypi --yes
nemoclaw my-assistant policy-remove brew --yes
nemoclaw my-assistant policy-remove huggingface --yes
```
The `pypi` preset allows Python, `pip`, virtual-environment Python and `pip`, and `/usr/local/bin/uv` to reach PyPI endpoints.
If `uv` is installed somewhere else in the sandbox, add a custom preset for that binary path instead of broadening the maintained preset locally.
### Homebrew Specifics
The sandbox base image includes Homebrew (Linuxbrew), so applying the `brew` preset is the only step needed before installing a formula.
A `/usr/local/bin/brew` wrapper puts the entry point on the sandbox `PATH` while delegating to the Linuxbrew prefix.
Installed formula commands are available from the Linuxbrew bin directory in sandbox shell sessions:
```bash
nemoclaw my-assistant policy-add brew --yes
nemoclaw my-assistant exec -- brew install <formula>
nemoclaw my-assistant exec -- bash -lc '<formula-command>'
```
You do not need to bootstrap Homebrew, install build dependencies, or source `brew shellenv` inside the sandbox.
## Model Pricing
<AgentOnly variant="openclaw">
OpenClaw's gateway fetches reference pricing from LiteLLM and OpenRouter on every start to populate `usage.cost` in session JSONL records.
The default-strict egress policy denies both hosts.
The fetch fails closed, the gateway logs `[gateway/model-pricing] LiteLLM pricing fetch failed: TypeError: fetch failed` (and the matching OpenRouter line) on every startup, and every session record records `usage.cost = 0` even though the input and output token counts populate correctly.
Tools that read the session log to display per-turn cost (audit dashboards, compliance review surfaces) cannot distinguish a real free run from this silent failure.
Apply the `openclaw-pricing` preset to allow both pricing endpoints.
The preset pins each host to a single read-only path so it does not widen egress beyond the pricing fetch:
```bash
nemoclaw my-assistant policy-add openclaw-pricing --dry-run
nemoclaw my-assistant policy-add openclaw-pricing --yes
```
After the next gateway restart, the WARN entries stop and `usage.cost` populates from the fetched pricing tables.
</AgentOnly>
<AgentOnly variant="hermes">
Hermes does not use OpenClaw's model-pricing reference fetch.
</AgentOnly>
## 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:
```bash
nemoclaw my-assistant policy-add local-inference --dry-run
nemoclaw my-assistant policy-add local-inference --yes
```
Then verify the sandbox status:
```bash
nemoclaw my-assistant status
```
## Inspect or Replace the Live Policy
Use `policy-list` for normal preset state:
```bash
nemoclaw my-assistant policy-list
```
Use OpenShell when you need the full enforced YAML:
```bash
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:
```bash
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](approve-network-requests.md) for the interactive OpenShell TUI flow.
- [Customize the Sandbox Network Policy](../SKILL.md) for static policy edits and raw OpenShell policy files.
- Messaging Channels (use the `nemoclaw-user-manage-sandboxes` skill) for Telegram, Discord, Slack, WeChat, and WhatsApp channel configuration.
- Commands (use the `nemoclaw-user-reference` skill) for the full `policy-add`, `policy-list`, `policy-remove`, and `channels` command reference.

291
.agents/skills/nemoclaw-user-manage-sandboxes/SKILL.md
View file

@ -1,291 +0,0 @@
---
name: "nemoclaw-user-manage-sandboxes"
description: "Explains operational tasks after the quickstart: listing sandboxes, status and health checks, logs, diagnostics, port forwards, multiple sandboxes, credential reset, rebuilds, network presets, upgrades, and uninstall. Trigger keywords - manage nemoclaw sandboxes, nemoclaw status, nemoclaw list, nemoclaw dashboard port, nemoclaw rebuild, nemoclaw upgrade sandboxes, nemoclaw uninstall, sandbox mutability, sandbox runtime configuration, sandbox rebuild, nemoclaw backup, nemoclaw restore, workspace backup, openshell sandbox download upload, nemoclaw messaging channels, nemoclaw telegram, nemoclaw discord, nemoclaw slack, nemoclaw wechat, nemoclaw whatsapp, openshell channel messaging, install hermes plugins, hermes plugins nemoclaw, nemoclaw hermes plugins, nemohermes dockerignore, nemoclaw workspace files, soul.md, user.md, identity.md, agents.md, sandbox persistence."
license: "Apache-2.0"
---
# Manage Sandbox Lifecycle
import { AgentOnly } from "../_components/AgentGuide";
<AgentOnly variant="openclaw">
Use this guide after you finish the OpenClaw quickstart (use the `nemoclaw-user-get-started` skill).
</AgentOnly>
<AgentOnly variant="hermes">
Use this guide after you finish Quickstart with Hermes (use the `nemoclaw-user-get-started` skill).
</AgentOnly>
It covers day-two sandbox operations such as listing sandboxes, checking health, managing ports, rebuilding safely, upgrading, and uninstalling.
<AgentOnly variant="openclaw">
When a workflow uses the lower-level OpenShell CLI, see CLI Selection Guide (use the `nemoclaw-user-reference` skill) for the boundary between `nemoclaw` and `openshell`.
</AgentOnly>
<AgentOnly variant="hermes">
When a workflow uses the lower-level OpenShell CLI, see CLI Selection Guide (use the `nemoclaw-user-reference` skill) for the boundary between `nemoclaw`, `nemoclaw`, and `openshell`.
</AgentOnly>
## List Sandboxes
List every sandbox registered on this host:
```bash
nemoclaw list
```
The list shows each sandbox's model, provider, policy presets, active SSH session indicator, and dashboard URL when NemoClaw records a dashboard port.
Use JSON output for scripts:
```bash
nemoclaw list --json
```
## Check Sandbox Health
Check a specific sandbox's health, inference route, active connections, live policy, update status, and messaging-channel overlap warnings:
```bash
nemoclaw my-assistant status
```
Use the host-level status command when you want the sandbox inventory plus host auxiliary service state, such as cloudflared:
```bash
nemoclaw status
```
## Inspect Logs
View recent sandbox logs:
```bash
nemoclaw my-assistant logs
```
Stream logs while you reproduce a problem:
```bash
nemoclaw my-assistant logs --follow
```
<AgentOnly variant="openclaw">
The log command reads both OpenClaw gateway output and OpenShell audit events, so policy denials appear beside gateway logs.
</AgentOnly>
<AgentOnly variant="hermes">
The log command reads both Hermes gateway output and OpenShell audit events, so policy denials appear beside gateway logs.
</AgentOnly>
## Collect Diagnostics
Collect diagnostics for bug reports or support handoff:
```bash
nemoclaw debug --sandbox my-assistant --output nemoclaw-debug.tar.gz
```
Use `--quick` for a smaller local summary:
```bash
nemoclaw debug --quick --sandbox my-assistant
```
The debug command gathers system information, Docker state, gateway logs, and sandbox status.
## Manage Dashboard Ports
If the forward stopped, or the installer reported that no active forward was found and the URL does not load, restart it manually with the port from the install summary.
```bash
openshell forward start --background <dashboard-port> my-gpt-claw
```
To list active forwards across all sandboxes, run the following command.
```bash
openshell forward list
```
## Run Multiple Sandboxes
Each sandbox needs its own dashboard port, since `openshell forward` refuses to bind a port that another sandbox is already using.
<AgentOnly variant="openclaw">
When the default port is already held by another sandbox, `nemoclaw onboard` scans ports `18789` through `18799` and uses the next free port.
</AgentOnly>
<AgentOnly variant="hermes">
When the default API port is already held by another sandbox, `nemoclaw onboard` scans for the next free port and records it for the sandbox.
</AgentOnly>
If you intentionally run separate OpenShell gateways on the same host, set a different `NEMOCLAW_GATEWAY_PORT` before each onboarding run.
NemoClaw isolates the gateway name and local state by port so one port-specific gateway does not replace another.
Gateway and dashboard cleanup is scoped by sandbox name and port.
A later onboarding run that uses a different `NEMOCLAW_GATEWAY_PORT` or `--control-ui-port` does not tear down the first sandbox's gateway or dashboard forward.
```bash
nemoclaw onboard # first sandbox uses 18789
nemoclaw onboard # second sandbox uses the next free port, such as 18790
```
To choose a specific port, pass `--control-ui-port`:
```bash
nemoclaw onboard --control-ui-port 19000
```
You can also set `CHAT_UI_URL` or `NEMOCLAW_DASHBOARD_PORT` before onboarding:
```bash
CHAT_UI_URL=http://127.0.0.1:19000 nemoclaw onboard
NEMOCLAW_DASHBOARD_PORT=19000 nemoclaw onboard
```
For full details on port conflicts and overrides, refer to Port already in use (use the `nemoclaw-user-reference` skill).
## Reconfigure or Recover
Recover from a misconfigured sandbox without re-running the full onboard wizard or destroying workspace state.
### Change Inference Model or API
Change the active model or provider at runtime without rebuilding the sandbox:
```bash
nemoclaw inference set --model <model> --provider <provider>
```
Refer to Switch Inference Providers (use the `nemoclaw-user-configure-inference` skill) for provider-specific model IDs and API compatibility notes.
### Restart the Gateway and Port Forward
<AgentOnly variant="openclaw">
If `nemoclaw <name> status` reports the sandbox is alive but the gateway is not running, run the recover command instead of opening a shell.
</AgentOnly>
<AgentOnly variant="hermes">
If `nemoclaw <name> status` reports the sandbox is alive but the Hermes gateway is not running, run the recover command instead of opening a shell.
</AgentOnly>
```bash
nemoclaw <sandbox-name> recover
```
The command restarts the in-sandbox gateway and re-establishes the dashboard port-forward in one step.
It is idempotent and safe to script.
Refer to `nemoclaw <name> recover` (use the `nemoclaw-user-reference` skill) for details.
### Reset a Stored Credential
If you entered a provider credential incorrectly during onboarding, clear the gateway-registered value and re-enter it on the next onboard run:
```bash
nemoclaw credentials list # see which providers are registered
nemoclaw credentials reset <PROVIDER> # clear a single provider, for example nvidia-prod
nemoclaw onboard # re-run to re-enter the cleared provider
```
The command reference documents `nemoclaw credentials reset <PROVIDER>` (use the `nemoclaw-user-reference` skill) in full.
### Rebuild a Sandbox While Preserving Workspace State
<AgentOnly variant="openclaw">
If you changed the underlying Dockerfile, upgraded OpenClaw, or want to pick up a new base image without losing your sandbox's workspace files, use `rebuild` instead of destroying and recreating:
</AgentOnly>
<AgentOnly variant="hermes">
If you changed the underlying Dockerfile, upgraded Hermes, or want to pick up a new base image without losing your sandbox's state files, use `rebuild` instead of destroying and recreating:
</AgentOnly>
```bash
nemoclaw <sandbox-name> rebuild
```
Rebuild preserves the mounted workspace and registered policies while recreating the container.
If NemoClaw cannot archive any requested state path, it reports the backup failure and stops before deleting the original sandbox.
Refer to `nemoclaw <name> rebuild` (use the `nemoclaw-user-reference` skill) for flag details.
### Add a Network Preset After Onboarding
Apply an additional preset, such as Telegram or GitHub, to a running sandbox without re-onboarding:
```bash
nemoclaw <sandbox-name> policy-add
```
Refer to `nemoclaw <name> policy-add` (use the `nemoclaw-user-reference` skill) for usage details and flags.
Non-interactive re-onboards in the default `suggested` policy mode preserve presets added this way.
To make a re-onboard authoritative, set `NEMOCLAW_POLICY_MODE=custom` and provide `NEMOCLAW_POLICY_PRESETS` with the exact list to apply; onboarding removes anything else.
See `NEMOCLAW_POLICY_MODE` (use the `nemoclaw-user-reference` skill) for the full table.
## Update to the Maintained Version
When a maintained NemoClaw release becomes available, update the host CLI and then check whether existing sandboxes need rebuilds.
The standard installer follows the admin-promoted `lkg` release tag by default.
If you need a specific release, set `NEMOCLAW_INSTALL_TAG` on the `bash` side of the install pipeline.
```bash
curl -fsSL https://www.nvidia.com/nemoclaw.sh | NEMOCLAW_INSTALL_TAG=v0.0.63 bash
nemoclaw upgrade-sandboxes --check
```
Before upgrade work, the installer runs `nemoclaw backup-all` when the installed CLI supports it.
For manual upgrade flows, create a snapshot first and then run the update or rebuild command you need:
```bash
nemoclaw <sandbox-name> snapshot create --name pre-upgrade
nemoclaw update --yes
nemoclaw upgrade-sandboxes --check
```
Each rebuild destroys the old container and creates a new one, while preserving the manifest-defined workspace or agent state that NemoClaw knows how to snapshot.
`upgrade-sandboxes --check` can report a sandbox as stale because the running agent version is behind, because the managed NemoClaw image fingerprint differs from the current CLI, or both.
Custom-image sandboxes created with `--from <Dockerfile>` are not marked stale solely by image fingerprint, so an upgrade check does not accidentally replace them with the default image.
Runtime changes outside those state paths, such as packages installed manually in the running container, are not preserved.
For the full state-preservation contract, snapshot restore behavior, and manual backup workflow, refer to [Backup and Restore](references/backup-restore.md).
For command flags, refer to `nemoclaw update` (use the `nemoclaw-user-reference` skill), `nemoclaw upgrade-sandboxes` (use the `nemoclaw-user-reference` skill), and `nemoclaw <name> rebuild` (use the `nemoclaw-user-reference` skill).
## Uninstall
To remove NemoClaw and all resources created during setup, run the CLI's built-in uninstall command:
```bash
nemoclaw uninstall
```
| Flag | Effect |
|--------------------|------------------------------------------------------|
| `--yes` | Skip the confirmation prompt. |
| `--keep-openshell` | Leave OpenShell binaries installed. |
| `--delete-models` | Also remove NemoClaw-pulled Ollama models. |
**Note:**
The uninstall command preserves `~/.nemoclaw/rebuild-backups/` (host-side snapshots that snapshot and `backup-all` commands write), `~/.nemoclaw/backups/` (workspace backups that `scripts/backup-workspace.sh` writes), and `~/.nemoclaw/sandboxes.json` (the sandbox registry) by default.
Uninstall removes every other entry under `~/.nemoclaw/`.
Interactive runs prompt before they remove the preserved entries; the default answer keeps them.
For non-interactive runs (`--yes`, `NEMOCLAW_NON_INTERACTIVE=1`, or a non-TTY shell), set `NEMOCLAW_UNINSTALL_DESTROY_USER_DATA=1` to acknowledge data loss and remove the preserved entries as well.
See the Commands reference (use the `nemoclaw-user-reference` skill) for the full preservation contract.
The CLI uninstall command runs the version-pinned `uninstall.sh` that shipped with your installed CLI, so it does not fetch anything over the network at uninstall time.
If the CLI is missing or broken, fall back to the hosted script:
```bash
curl -fsSL https://raw.githubusercontent.com/NVIDIA/NemoClaw/refs/heads/main/uninstall.sh | bash
```
The same `--yes`, `--keep-openshell`, and `--delete-models` flags listed above also apply to the hosted script. Pass them after `bash -s --`.
```bash
curl -fsSL https://raw.githubusercontent.com/NVIDIA/NemoClaw/refs/heads/main/uninstall.sh | bash -s -- --yes --delete-models
```
For a full comparison of the two forms, including what they fetch, what they trust, and when to prefer each, refer to `nemoclaw uninstall` vs. the hosted `uninstall.sh` (use the `nemoclaw-user-reference` skill).
## References
- **[references/runtime-controls.md](references/runtime-controls.md)** — Single page that answers what can change at runtime versus what requires a rebuild for NemoClaw sandboxes.
- **Load [references/backup-restore.md](references/backup-restore.md)** when downloading workspace files from a sandbox, uploading restored files into a new sandbox, or preserving sandbox state across rebuilds. Backs up and restores OpenClaw workspace files before destructive operations such as sandbox rebuilds.
- **Load [references/messaging-channels.md](references/messaging-channels.md)** when setting up messaging channels, chat interfaces, or integrations without relying on nemoclaw tunnel start for bridges. Explains how Telegram, Discord, Slack, WeChat, and WhatsApp reach sandboxed OpenClaw and Hermes agents through OpenShell-managed processes and NemoClaw channel commands.
- **Load [references/install-plugins-hermes.md](references/install-plugins-hermes.md)** when users ask how to install, build, or configure Hermes plugins under NemoClaw. Explains how to install Hermes plugins in NemoClaw-managed sandboxes, including custom Dockerfile build-directory layout and `.dockerignore` handling.
- **Load [references/workspace-files.md](references/workspace-files.md)** when users ask about `SOUL.md`, `USER.md`, `IDENTITY.md`, `AGENTS.md`, or other workspace files, or when preparing to back up or restore workspace state. Explains what workspace personality and configuration files are, where they live, and how they persist across sandbox restarts.
## Related Skills
- [Set Up Messaging Channels](references/messaging-channels.md) to connect Telegram, Discord, or Slack.
- [Workspace Files](references/workspace-files.md) for persistent OpenClaw files inside the sandbox.
- [Backup and Restore](references/backup-restore.md) for snapshot and restore workflows.
- `nemoclaw-user-monitor-sandbox` — Monitor Sandbox Activity (use the `nemoclaw-user-monitor-sandbox` skill) for observability tools

11
.agents/skills/nemoclaw-user-manage-sandboxes/evals/evals.json
View file

@ -1,11 +0,0 @@
[
{
"id": "docs-manage-sandboxes-lifecycle-001",
"question": "I'm managing a NemoClaw sandbox. Help me check status, health, logs, ports, providers, upgrades, and uninstall paths so I can operate the sandbox safely after quickstart.",
"expected_skill": "nemoclaw-user-manage-sandboxes",
"ground_truth": "A NemoClaw-specific answer that helps the user check status, health, logs, ports, providers, upgrades, and uninstall paths and gives enough concrete guidance, decision criteria, verification steps, or risk framing to operate the sandbox safely after quickstart.",
"expected_behavior": [
"Uses the expected_skill and does not make up answers if it cannot find the answer from the skill."
]
}
]

266
.agents/skills/nemoclaw-user-manage-sandboxes/references/backup-restore.md
View file

@ -1,266 +0,0 @@
# Backup and Restore Workspace Files
import { AgentOnly } from "../_components/AgentGuide";
Workspace and state files define your agent's personality, memory, user context, and durable runtime state.
They persist across sandbox restarts, but destroying the sandbox **permanently deletes** them.
This guide covers snapshot commands, all-sandbox backups, and manual backup with CLI commands.
## When to Back Up
<AgentOnly variant="openclaw">
- Before running `nemoclaw <name> destroy`
- Before major NemoClaw version upgrades
- Periodically, if you've invested time customizing your agent
</AgentOnly>
<AgentOnly variant="hermes">
- Before running `nemoclaw <name> destroy`
- Before major NemoClaw version upgrades
- Periodically, if you've invested time customizing your agent or paired messaging channels
</AgentOnly>
## Snapshot Commands
The fastest way to back up and restore sandbox state is with the built-in snapshot commands.
Snapshots capture all workspace state directories defined in the agent manifest and store them in `~/.nemoclaw/rebuild-backups/<name>/`.
Agent manifests can also declare durable top-level state files.
For Hermes, snapshots include `SOUL.md` and the SQLite database behind `.hermes/state.db` using SQLite's online backup API, then restore that database through SQLite instead of copying a live raw database file.
Treat snapshot directories as private local data: the Hermes database can contain session metadata and message history needed for a faithful restore.
Snapshots also preserve sandbox registry metadata that affects rebuild behavior, including custom policy presets applied with `policy-add --from-file` or `policy-add --from-dir`.
When you restore a snapshot, NemoClaw replays those recorded custom presets with their stored YAML content, so you do not need the original preset files on disk for the restored sandbox to keep the same policy state.
```bash
nemoclaw my-assistant snapshot create
nemoclaw my-assistant snapshot list
nemoclaw my-assistant snapshot restore
```
`snapshot list` prints a table of version, name, timestamp, and path.
NemoClaw computes versions (`v1`, `v2`, ..., `vN`) from timestamp order, so `vN` is always the newest snapshot.
To tag a snapshot with a human-readable label, pass `--name`:
```bash
nemoclaw my-assistant snapshot create --name before-upgrade
```
To restore a specific snapshot instead of the latest, pass a version, name, or timestamp prefix:
```bash
nemoclaw my-assistant snapshot restore v3
nemoclaw my-assistant snapshot restore before-upgrade
nemoclaw my-assistant snapshot restore 2026-04-14T
```
To clone a snapshot into a different sandbox name, pass `--to <name>`.
If the destination sandbox already exists, NemoClaw refuses to overwrite it unless you pass `--force`:
```bash
nemoclaw my-assistant snapshot restore before-upgrade --to my-assistant-clone
nemoclaw my-assistant snapshot restore before-upgrade --to my-assistant-clone --force --yes
```
<AgentOnly variant="openclaw">
The `nemoclaw <name> rebuild` command uses the same snapshot mechanism automatically.
Snapshot restore performs a targeted repair for legacy `.openclaw-data` symlinks that older images created.
NemoClaw rejects unsafe symlinks and hard links inside sandbox state during backup creation before they can enter a snapshot.
Snapshots also preserve user-owned `openclaw.json` settings.
During rebuild or restore, NemoClaw merges those restored settings with the freshly generated runtime config so current provider placeholders, messaging enablement, and gateway state win over stale snapshot values.
If the restored config cannot be parsed or applied safely, NemoClaw stops the restore instead of replacing the generated config with an unsafe fallback.
</AgentOnly>
<AgentOnly variant="hermes">
The `nemoclaw <name> rebuild` command uses the same snapshot mechanism automatically.
NemoClaw rejects unsafe symlinks and hard links inside sandbox state during backup creation before they can enter a snapshot.
Credential-bearing Hermes files such as `auth.json` are intentionally excluded
from snapshots. NemoClaw-regenerated Hermes config files (`config.yaml` and
`.env`) are also excluded; model/provider and messaging credentials are
recreated from host-side onboarding and OpenShell provider state during rebuild.
</AgentOnly>
For full details, see the Commands reference (use the `nemoclaw-user-reference` skill).
## Manual Backup
Use `openshell sandbox download` to copy files from the sandbox to your host.
<AgentOnly variant="openclaw">
```bash
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/"
```
</AgentOnly>
<AgentOnly variant="hermes">
```bash
SANDBOX=my-hermes
BACKUP_DIR=~/.nemoclaw/backups/$(date +%Y%m%d-%H%M%S)
mkdir -p "$BACKUP_DIR"
openshell sandbox download "$SANDBOX" /sandbox/SOUL.md "$BACKUP_DIR/"
openshell sandbox download "$SANDBOX" /sandbox/.hermes/state.db "$BACKUP_DIR/"
openshell sandbox download "$SANDBOX" /sandbox/.hermes/platforms/ "$BACKUP_DIR/platforms/"
```
</AgentOnly>
## Manual Restore
Use `openshell sandbox upload` to push files back into a sandbox.
<AgentOnly variant="openclaw">
```bash
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/
```
</AgentOnly>
<AgentOnly variant="hermes">
```bash
SANDBOX=my-hermes
BACKUP_DIR=~/.nemoclaw/backups/20260320-120000 # pick a timestamp
openshell sandbox upload "$SANDBOX" "$BACKUP_DIR/SOUL.md" /sandbox/
openshell sandbox upload "$SANDBOX" "$BACKUP_DIR/state.db" /sandbox/.hermes/
openshell sandbox upload "$SANDBOX" "$BACKUP_DIR/platforms/" /sandbox/.hermes/platforms/
```
</AgentOnly>
## Back Up All Running Sandboxes
To back up every registered, running sandbox in one step, run `nemoclaw backup-all`.
This is the recommended host-installed command before broad maintenance such as `nemoclaw update`, `nemoclaw upgrade-sandboxes`, or an OpenShell gateway migration.
```bash
nemoclaw backup-all
```
`backup-all` walks the sandboxes registered on the host, creates a snapshot for each running sandbox, and stores the snapshot bundles under `~/.nemoclaw/rebuild-backups/<name>/`.
Use `nemoclaw <name> snapshot list` and `nemoclaw <name> snapshot restore` to inspect or restore one sandbox's bundles later.
## Using the Backup Script
<AgentOnly variant="openclaw">
**Source-tree helper script:**
The [`scripts/backup-workspace.sh`](https://github.com/NVIDIA/NemoClaw/blob/main/scripts/backup-workspace.sh) helper exists only in the NemoClaw source repository for engineering workflows.
It is not installed by the standard `curl -fsSL https://www.nvidia.com/nemoclaw.sh | bash` installer, so host installs should use `nemoclaw backup-all` or the snapshot commands above.
### Backup
```bash
./scripts/backup-workspace.sh backup my-assistant
```
Expected output:
```text
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:
```bash
./scripts/backup-workspace.sh restore my-assistant
```
Restore from a specific timestamp:
```bash
./scripts/backup-workspace.sh restore my-assistant 20260320-120000
```
## Verifying a Backup
List backed-up files to confirm completeness:
```bash
ls -la ~/.nemoclaw/backups/20260320-120000/
```
Expected output:
```text
AGENTS.md
IDENTITY.md
MEMORY.md
SOUL.md
USER.md
memory/
```
</AgentOnly>
<AgentOnly variant="hermes">
For Hermes, prefer the built-in snapshot commands for faithful restore of `state.db`.
Use manual `openshell sandbox download` / `openshell sandbox upload` only when you need to inspect or transfer a specific file.
</AgentOnly>
<AgentOnly variant="openclaw">
## Multi-Agent Deployments
When you configure OpenClaw with multiple named agents, each agent has its own workspace directory (`workspace-main/`, `workspace-support/`, `workspace-ops/`, and so on).
Refer to [Multi-Agent Deployments](workspace-files.md#multi-agent-deployments).
`nemoclaw <name> snapshot create` automatically discovers every `workspace-*/` directory under the sandbox state tree and includes it in the snapshot bundle alongside the default `workspace/`.
`nemoclaw <name> snapshot restore` reapplies the full per-agent set.
You do not need a manual per-workspace backup pattern.
The sandbox entrypoint ensures every per-agent workspace lives directly under the persistent `.openclaw/` tree, so state also survives `openshell sandbox restart`.
### Shared files across agents
Files that operators typically want consistent across every per-agent workspace
(`AGENTS.md`, shared skills, common templates) are **not** synced automatically.
Each workspace is independent, and changes in one do not propagate.
Operators that need this either copy the shared files explicitly to each workspace after editing or maintain a host-side sync layer.
NVIDIA tracks shared-file tooling (shared mount, `workspaces list` command) in [#1260](https://github.com/NVIDIA/NemoClaw/issues/1260).
</AgentOnly>
<AgentOnly variant="hermes">
## Hermes State
Hermes does not use OpenClaw per-agent workspace directories.
NemoClaw snapshots preserve the Hermes manifest-defined state tree and durable top-level files instead.
Refer to [Workspace Files](workspace-files.md) for the Hermes state layout.
</AgentOnly>
## Next Steps
- [Workspace Files overview](workspace-files.md) to learn what each file does.
- Commands reference (use the `nemoclaw-user-reference` skill)

117
.agents/skills/nemoclaw-user-manage-sandboxes/references/install-plugins-hermes.md
View file

@ -1,117 +0,0 @@
# Install Hermes Plugins
Hermes plugins extend the Hermes runtime inside a NemoClaw-managed sandbox.
They are different from NemoClaw skills and from OpenClaw plugins, so install them through the Hermes plugin path instead of `skill install`.
## How Hermes Loads Plugins
NemoClaw sets `HERMES_HOME` to `/sandbox/.hermes` when it starts the Hermes gateway.
Hermes plugin directories live under `/sandbox/.hermes/plugins/<plugin-name>`.
NemoClaw uses the same mechanism for its built-in Hermes integration, which the sandbox image bakes into `/sandbox/.hermes/plugins/nemoclaw`.
The built-in NemoClaw Hermes plugin provides sandbox status tools, skill reload support, managed-tool broker patches, and runtime grounding for the OpenShell sandbox.
Do not replace or remove `/sandbox/.hermes/plugins/nemoclaw` when you add your own plugin.
## Choose an Install Path
Today, the supported path for custom Hermes plugins is to bake the plugin into a custom sandbox image and onboard from that Dockerfile.
Use this path when the plugin adds Python code, runtime hooks, or dependencies that Hermes must see at gateway startup.
`nemohermes <name> skill install <path>` is only for `SKILL.md` agent skills.
It uploads skill instructions and refreshes skill discovery, but it does not install Hermes runtime plugins.
## Prepare a Build Directory
Put the custom Dockerfile and everything it needs to `COPY` in one directory.
`nemohermes onboard --from <Dockerfile>` sends the Dockerfile's parent directory as the Docker build context.
Add a `.dockerignore` next to the Dockerfile to keep local caches, generated artifacts, model files, or other unneeded paths out of the staged context.
NemoClaw still excludes credential-like paths such as `.env*`, `.ssh/`, `.aws/`, `.npmrc`, `secrets/`, `*.pem`, and `*.key`, even if `.dockerignore` tries to include them.
```text
my-hermes-plugin-sandbox/
├── Dockerfile
└── my-hermes-plugin/
├── __init__.py
└── requirements.txt
```
If you start from the stock NemoClaw Hermes Dockerfile, keep the NemoClaw Hermes image contract intact.
The image must still include the generated Hermes config, NemoClaw Hermes plugin, blueprint files, and `nemoclaw-start` entrypoint.
**Warning:**
A custom `--from` Dockerfile replaces the normal NemoClaw Hermes Dockerfile.
Starting from `ghcr.io/nvidia/nemoclaw/hermes-sandbox-base:latest` alone is not enough unless your Dockerfile also preserves the NemoClaw Hermes layers from `agents/hermes/Dockerfile`.
## Install the Plugin in the Image
Add your plugin after the Dockerfile has created `/sandbox/.hermes`.
The example below shows the layer that copies a plugin directory into the Hermes plugin tree.
```dockerfile
COPY my-hermes-plugin/ /opt/my-hermes-plugin/
USER root
RUN mkdir -p /sandbox/.hermes/plugins/my-hermes-plugin \
&& cp -a /opt/my-hermes-plugin/. /sandbox/.hermes/plugins/my-hermes-plugin/ \
&& if [ -f /opt/my-hermes-plugin/requirements.txt ]; then \
/opt/hermes/.venv/bin/python -m pip install --no-cache-dir -r /opt/my-hermes-plugin/requirements.txt; \
fi \
&& chown -R sandbox:sandbox /sandbox/.hermes/plugins/my-hermes-plugin \
&& chmod -R a+rX /sandbox/.hermes/plugins/my-hermes-plugin
USER sandbox
WORKDIR /sandbox
```
Keep plugin code and dependency files inside the build directory.
Avoid copying host credentials, local caches, or broad home-directory contents into the image.
## Create the Sandbox
Run onboarding with the custom Dockerfile and an explicit sandbox name.
NemoClaw requires a name for `--from` builds so a custom image cannot silently replace the default sandbox.
```bash
nemohermes onboard --name my-hermes-build --from ./my-hermes-plugin-sandbox/Dockerfile
```
For non-interactive onboarding, set the same values through environment variables.
```bash
NEMOCLAW_NON_INTERACTIVE=1 \
NEMOCLAW_SANDBOX_NAME=my-hermes-build \
NEMOCLAW_FROM_DOCKERFILE=./my-hermes-plugin-sandbox/Dockerfile \
nemohermes onboard
```
If you resume an interrupted onboarding run, use the same Dockerfile path that started the session.
NemoClaw records the custom Dockerfile path and rejects a resume that points at a different image source.
## Network Access
Hermes plugins still run inside the OpenShell sandbox boundary.
If a plugin calls an external API at runtime, add a policy preset for the required hostnames and binaries before you recreate the sandbox.
Hermes uses Python for plugin execution, so policy entries usually need to allow the Hermes Python runtime, such as `/opt/hermes/.venv/bin/python`, in addition to any command-line wrapper your plugin starts.
For package downloads during sandbox runtime, use the `pypi` preset or a custom preset that allows the package hosts you need.
For policy concepts, refer to Network Policies (use the `nemoclaw-user-reference` skill).
For custom preset workflows, refer to Customize Network Policy (use the `nemoclaw-user-manage-policy` skill).
## Common Mistakes
These are the most common places where Hermes plugin installation gets mixed up with other NemoClaw extension paths.
- Do not use `skill install` for Hermes runtime plugins.
- Do not install Hermes plugins into `/sandbox/.openclaw/extensions`; that path is for OpenClaw plugins.
- Do not remove `/sandbox/.hermes/plugins/nemoclaw`; NemoClaw depends on that plugin for managed Hermes behavior.
- Do not put the Dockerfile in a broad directory unless you intend to send that whole directory as the Docker build context.
- Do not rely on `.dockerignore` to include credential-like paths; NemoClaw excludes those from staged custom build contexts for safety.
- Do not assume OpenShell policy allows Python package downloads during runtime by default.
## Next Steps
- Review NemoHermes Command Reference (use the `nemoclaw-user-reference` skill) for `nemohermes onboard --from` details.
- Review Customize Network Policy (use the `nemoclaw-user-manage-policy` skill) if the plugin needs runtime network egress.
- Review [Runtime Controls](runtime-controls.md) before changing shields or mutability settings for a plugin-enabled sandbox.

342
.agents/skills/nemoclaw-user-manage-sandboxes/references/messaging-channels.md
View file

@ -1,342 +0,0 @@
# Messaging Channels
import { AgentOnly } from "../_components/AgentGuide";
Telegram, Discord, Slack, WeChat, and WhatsApp reach your OpenClaw or Hermes agent through OpenShell-managed processes and gateway constructs.
For token-based channels, NemoClaw registers credentials with OpenShell providers.
WeChat captures a token through a host-side QR scan during onboarding.
WhatsApp pairs inside the sandbox through a QR scan and intentionally stores mutable session state there.
NemoClaw bakes the selected channel configuration into the sandbox image and keeps runtime delivery under OpenShell control.
**Experimental Channels:**
WeChat and WhatsApp are experimental.
Both rely on QR-based pairing flows that are more fragile than token-based bots, and the upstream client libraries can change behavior without notice.
Interfaces, defaults, and supported features can change, and NVIDIA does not recommend these channels for production use.
<AgentOnly variant="openclaw">
You can enable channels during `nemoclaw onboard` or add them later with host-side `nemoclaw <sandbox> channels` commands.
Do not run agent-specific channel mutation commands such as `openclaw channels add` or `openclaw channels remove` inside the sandbox because NemoClaw generates `/sandbox/.openclaw/openclaw.json` at image build time, and changes inside the running container do not persist across rebuilds.
</AgentOnly>
<AgentOnly variant="hermes">
You can enable channels during `nemoclaw onboard` or add them later with host-side `nemoclaw <sandbox> channels` commands.
Do not mutate messaging configuration directly inside the sandbox because NemoClaw generates `/sandbox/.hermes/.env` and Hermes config at image build time, and changes inside the running container do not persist across rebuilds.
</AgentOnly>
<AgentOnly variant="openclaw">
`nemoclaw tunnel start` does not start Telegram, Discord, Slack, or other chat bridges.
It only starts optional host services such as the cloudflared tunnel when that binary is present. (`nemoclaw start` is kept as a deprecated alias.)
</AgentOnly>
<AgentOnly variant="hermes">
`nemoclaw tunnel start` does not start Telegram, Discord, Slack, or other chat bridges.
It only starts optional host services such as the cloudflared tunnel when that binary is present.
</AgentOnly>
For details, refer to Commands (use the `nemoclaw-user-reference` skill).
## Prerequisites
- A machine where you can run `nemoclaw onboard` (local or remote host that runs the gateway and sandbox).
- A token for each token-based messaging platform you want to enable, a personal WeChat account on your phone for the host-side QR scan during onboarding, or a phone you can use to scan the QR code for WhatsApp pairing.
- A network policy preset for each enabled channel, or equivalent custom egress rules.
## Channel Requirements
| Channel | Required tokens | Optional settings |
|---------|-----------------|-------------------|
| Telegram | `TELEGRAM_BOT_TOKEN` | `TELEGRAM_ALLOWED_IDS` for DM allowlisting, `TELEGRAM_REQUIRE_MENTION` for group-chat replies |
| Discord | `DISCORD_BOT_TOKEN` | `DISCORD_SERVER_ID`, `DISCORD_USER_ID`, `DISCORD_REQUIRE_MENTION` |
| Slack | `SLACK_BOT_TOKEN`, `SLACK_APP_TOKEN` | `SLACK_ALLOWED_USERS` for DM and channel `@mention` user allowlisting, `SLACK_ALLOWED_CHANNELS` for channel ID allowlisting |
| WeChat (experimental) | None. Captured through host-side QR scan during `nemoclaw onboard` | `WECHAT_ALLOWED_IDS` for DM allowlisting |
| WhatsApp (experimental) | None. Pair through QR after rebuild | None |
Telegram uses a bot token from [BotFather](https://t.me/BotFather).
Open Telegram, send `/newbot` to [@BotFather](https://t.me/BotFather), follow the prompts, and copy the token.
For Telegram group chats, disable privacy mode before testing group replies: in @BotFather, run `/setprivacy`, choose the bot, then choose **Disable**.
After changing privacy mode, remove the bot from each Telegram group and add it back so Telegram applies the new delivery setting to that group.
`TELEGRAM_ALLOWED_IDS` is a comma-separated list of Telegram user or private-chat IDs for DM access.
For compatibility with older QA scripts, NemoClaw also treats `TELEGRAM_AUTHORIZED_CHAT_IDS` and `TELEGRAM_CHAT_ID` as aliases, but new automation should use `TELEGRAM_ALLOWED_IDS`.
Keep these aliases until QA automation and public repro templates have stopped exporting them for at least one full release.
Group chats stay open by default so rebuilt sandboxes do not silently drop Telegram group messages because of an empty group allowlist.
Set `TELEGRAM_REQUIRE_MENTION=1` to make the bot reply in Telegram groups only when users mention it.
Pairing and `TELEGRAM_ALLOWED_IDS` still govern direct messages.
Discord uses a bot token from the Discord Developer Portal.
For server channels, enable Developer Mode in Discord, right-click the server, and copy the Server ID into `DISCORD_SERVER_ID`.
By default, NemoClaw configures the bot to reply only when mentioned.
Set `DISCORD_REQUIRE_MENTION=0` if you want it to reply to all messages in the configured server.
Set `DISCORD_USER_ID` to restrict access to one user; otherwise, any member of the configured server can message the bot.
Slack uses Socket Mode and requires two tokens.
Use `SLACK_BOT_TOKEN` for the bot user OAuth token (`xoxb-...`) and `SLACK_APP_TOKEN` for the app-level Socket Mode token (`xapp-...`).
NemoClaw validates both tokens before it saves Slack credentials or enables the channel.
This validation calls the live Slack API (`auth.test` and `apps.connections.open`), so the tokens must belong to a real Slack app.
If Slack rejects the tokens (for example, `invalid_auth` for placeholder or fake values), NemoClaw skips the Slack channel.
Because the `slack` network policy preset is only applied for channels that are actually enabled, a skipped Slack channel also means the `slack` preset is not applied, so it does not appear as applied (`●`) in `nemoclaw <name> policy-list`.
To exercise Slack channel setup and the `slack` policy preset with placeholder tokens in a restricted network or hermetic test environment, set `NEMOCLAW_SKIP_SLACK_AUTH_VALIDATION=1` to skip the live credential probes; Slack token format checks still apply.
Set `SLACK_ALLOWED_USERS` to comma-separated Slack member IDs to authorize those users for DMs and for channel `@mention` events in channels where the Slack app is present.
Set `SLACK_ALLOWED_CHANNELS` to comma-separated Slack channel IDs to restrict channel `@mention` handling to those channels.
When both Slack allowlists are set, NemoClaw requires the mention to come from one of the allowed channels and one of the allowed members.
Channel messages still require an explicit bot mention.
When a Slack channel `@mention` is denied by these allowlists, NemoClaw sends a denial notice back to the sender instead of dropping the message silently.
During sandbox startup, NemoClaw normalizes OpenShell credential placeholders into the environment shape expected by the Slack runtime, so post-rebuild Slack starts use the gateway-managed tokens instead of literal placeholder strings.
Slack Socket Mode allows one active connection per app-level token.
If another sandbox on the same gateway already uses the same Slack app token, onboarding and `channels add slack` warn before continuing in interactive mode and abort in non-interactive mode.
Use `--force` only when you intentionally want to move the Slack Socket Mode session to the new sandbox.
WeChat (experimental) delivers messages over Tencent's iLink gateway through the upstream `@tencent-weixin/openclaw-weixin` plugin installed into WeChat-enabled OpenClaw sandbox images and the built-in Hermes iLink WeChat adapter.
The supported mode in this release is **personal WeChat** (`bot_type=3`).
WeChat Official Account and WeCom/Enterprise WeChat are not wired up.
Because the bot token only exists after a successful iLink QR handshake, NemoClaw runs the QR login on the host during `nemoclaw onboard`.
You scan the QR with WeChat on your phone (Discover → Scan), confirm the login, and NemoClaw captures the token, `accountId`, `baseUrl`, and `userId` from the iLink response.
NemoClaw registers the token as the `<sandbox>-wechat-bridge` OpenShell provider and substitutes the `openshell:resolve:env:WECHAT_BOT_TOKEN` placeholder for it inside the sandbox, so the token never lands in the image or on disk inside the running container.
NemoClaw bakes the non-secret per-account metadata (`WECHAT_ACCOUNT_ID`, `WECHAT_BASE_URL`, `WECHAT_USER_ID`) into the sandbox image so the in-sandbox bridge can pre-seed the per-account context tokens without re-running the QR handshake.
WeChat is DM-only (`allowIdsMode: "dm"`).
NemoClaw adds the operator who scanned the QR to `WECHAT_ALLOWED_IDS` automatically, and you can append more comma-separated WeChat user IDs through the same env var.
You can silence the host-side `[wechat]` diagnostic lines (poll status, IDC redirects, swallowed gateway errors) by exporting `NEMOCLAW_WECHAT_QUIET=1` after the flow is stable in your environment.
Tencent's iLink gateway is a third-party service.
Review your organization's terms-of-service, compliance, and data-residency constraints before enabling WeChat.
WhatsApp (experimental) Web does not use a host-side token or OpenShell credential provider.
NemoClaw advertises WhatsApp for both OpenClaw and Hermes sandboxes, and each agent completes pairing with its own in-sandbox command.
Pairing happens inside the sandbox after the rebuild completes and creates mutable session credentials there.
Connect to the sandbox and then use the agent-specific pairing command to render the QR code in the terminal:
```bash
openclaw channels login --channel whatsapp # OpenClaw sandboxes
hermes whatsapp # Hermes sandboxes
```
For OpenClaw sandboxes, NemoClaw validates the gateway URL before pairing and renders the WhatsApp QR code in a compact terminal form so it fits in smaller terminal windows.
If pairing exits with a gateway close such as `1008`, rerun the login command one time and then check `nemoclaw <sandbox> channels status --channel whatsapp` so you can diagnose the gateway/session path separately from QR rendering.
The sandbox generates and stores session credentials inside durable agent state (`whatsapp` for OpenClaw, `platforms/whatsapp` for Hermes), so they survive rebuilds without re-pairing.
This is the runtime tradeoff of enabling WhatsApp without a host bridge: a paired sandbox can use that WhatsApp account until you unpair it or clear the durable state.
NemoClaw cannot detect cross-sandbox WhatsApp conflicts the way it does for token-based channels.
Pair only one sandbox per WhatsApp account at a time.
## Enable Channels During Onboarding
When the wizard reaches **Messaging channels**, it lists Telegram, Discord, Slack, WeChat, and WhatsApp.
Press a channel number to toggle it on or off, then press **Enter** when done.
If you select no channels, pressing **Enter** skips messaging setup.
If a token-based channel token is not already in the environment or credential store, the wizard prompts for it and saves it.
If you enable WeChat (experimental), the wizard does not prompt for a paste token.
Instead, it renders a QR code in your terminal, polls Tencent's iLink gateway, and captures the bot token after you scan the QR with WeChat on your phone.
The login has an eight-minute deadline, refreshes the QR up to three times on expiry, and follows iLink's IDC redirects automatically.
Keep the terminal in the foreground until you see `✓ WeChat login confirmed`.
WhatsApp (experimental) uses QR pairing instead of a host-side token, so the wizard does not prompt.
It prints pairing instructions and you complete the pairing inside the sandbox after rebuild.
NemoClaw also selects the matching network policy preset during policy setup so the channel can reach its provider API.
For scripted setup, export the credentials and optional settings for the channels you want to enable before you run onboarding:
```bash
export TELEGRAM_BOT_TOKEN=<your-bot-token>
export TELEGRAM_REQUIRE_MENTION=1
export DISCORD_BOT_TOKEN=<your-discord-bot-token>
export DISCORD_SERVER_ID=<your-discord-server-id>
export SLACK_BOT_TOKEN=<your-slack-bot-token>
export SLACK_APP_TOKEN=<your-slack-app-token>
export SLACK_ALLOWED_USERS=<your-slack-member-id>
export SLACK_ALLOWED_CHANNELS=<your-slack-channel-id>
```
This release does not support non-interactive WeChat configuration because the iLink QR handshake requires a human to scan the QR on a paired phone.
Run `nemoclaw onboard` interactively when you want to enable WeChat.
Then run onboarding:
```bash
nemoclaw onboard
```
Complete the rest of the wizard so the blueprint can create OpenShell providers where needed (for example `<sandbox>-telegram-bridge` or `<sandbox>-wechat-bridge`), bake channel configuration into the image (`NEMOCLAW_MESSAGING_CHANNELS_B64`), and start the sandbox.
## Add Channels After Onboarding
Run channel commands from the host, not from inside the sandbox.
Use `channels list` to see the supported channel names:
```bash
nemoclaw my-assistant channels list
```
Add the channel you want:
```bash
nemoclaw my-assistant channels add telegram
nemoclaw my-assistant channels add discord
nemoclaw my-assistant channels add slack
nemoclaw my-assistant channels add wechat
nemoclaw my-assistant channels add whatsapp
```
`channels add` collects whatever each channel needs.
It prompts for Telegram, Discord, and Slack tokens, runs an interactive host-side QR scan for WeChat, and collects nothing for WhatsApp because pairing happens in-sandbox after rebuild.
It registers bridge providers with the OpenShell gateway when it captures tokens, records the channel in the sandbox registry, and asks whether to rebuild immediately.
The command accepts mixed-case input such as `Telegram`, then stores and prints the canonical lowercase channel name.
`channels add` requires the matching built-in network policy preset YAML to be present.
A missing or malformed preset YAML (no `network_policies:` section) aborts the command before any token prompt, registry write, or rebuild prompt, so the sandbox never advertises a channel without a matching network policy.
With the preset file in place, `channels add` applies it to the sandbox before the rebuild so the bridge has egress to its upstream API.
When the apply step itself fails after the registry write on a fresh add, NemoClaw attempts to roll back the bridge providers, the `messagingChannels` entry, and any staged environment credentials, then exits without prompting for a rebuild; if any gateway-side step (provider detach or delete) fails the rollback continues and prints a `Rollback could not fully clean <surfaces>` warning so the operator can clean up manually.
When the same failure happens on a re-add of an already-enabled channel, NemoClaw restores the prior `messagingChannels` entry, restores staged environment credentials when available, restores registry credential hashes, and attempts to re-upsert the prior bridge providers.
It flags `gateway-providers` as residual because the in-flight upsert can leave the gateway with the new token.
Verify the gateway bridge before relying on the channel.
Restore the preset YAML and re-run `nemoclaw <sandbox> channels add <channel>`.
Choose the rebuild so the running sandbox image picks up the new channel.
For Telegram, Discord, and Slack, `channels add` also checks the rebuilt runtime for the selected bridge and reports startup, credential, or missing-plugin warnings before returning.
If you need optional channel settings such as `TELEGRAM_ALLOWED_IDS`, `TELEGRAM_REQUIRE_MENTION`, `DISCORD_SERVER_ID`, `DISCORD_USER_ID`, `DISCORD_REQUIRE_MENTION`, `SLACK_ALLOWED_USERS`, or `SLACK_ALLOWED_CHANNELS`, export them before the rebuild starts.
Telegram Bot API `sendMessage` calls prove outbound delivery from the bot; to test inbound agent replies, send a message from the Telegram client as an allowed user.
For a repeatable live Telegram reply check, run `test/e2e/test-messaging-providers.sh` with `TELEGRAM_BOT_TOKEN_REAL`, `TELEGRAM_AUTHORIZED_CHAT_IDS` or `TELEGRAM_CHAT_ID`, and `NEMOCLAW_TELEGRAM_INBOUND_REPLY_E2E=1`.
If you defer the rebuild, apply the change later:
```bash
nemoclaw my-assistant rebuild
```
In non-interactive mode, set the required environment variables before running `channels add`.
Missing credentials fail fast, and the command queues the change for a manual rebuild:
```bash
NEMOCLAW_NON_INTERACTIVE=1 TELEGRAM_BOT_TOKEN=<your-bot-token> \
nemoclaw my-assistant channels add telegram
nemoclaw my-assistant rebuild
```
For Discord server access after onboarding, include the server settings when you add the channel and rebuild:
```bash
DISCORD_BOT_TOKEN=<your-discord-bot-token> \
DISCORD_SERVER_ID=<your-discord-server-id> \
DISCORD_REQUIRE_MENTION=1 \
nemoclaw my-assistant channels add discord
```
### `channels add wechat`
`channels add wechat` (experimental) follows the same shape as the other channels with two differences driven by the iLink QR handshake.
First, the command does not prompt for a paste token.
Instead, it renders a QR code in your terminal, polls Tencent's iLink gateway, and captures both the bot token and the per-account metadata (`accountId`, `baseUrl`, `userId`) after you scan the QR with WeChat on your phone (**Discover** > **Scan**).
The login has an eight-minute deadline and refreshes the QR up to three times on expiry.
Keep the terminal in the foreground until you see `✓ WeChat login confirmed`.
Second, the command requires an interactive terminal.
Non-interactive mode (`NEMOCLAW_NON_INTERACTIVE=1`) fails fast with a clear error because the QR handshake needs a paired phone.
```bash
nemoclaw my-assistant channels add wechat
```
If `WECHAT_BOT_TOKEN` is already cached for this sandbox (the operator onboarded with WeChat earlier), `channels add wechat` reuses the cached token and skips the QR scan to keep the upstream plugin's existing iLink session intact.
Re-running QR would invalidate that session.
Use `channels remove wechat` first if you intend to acquire a fresh account.
## Rotate or Remove Credentials
Running `channels add` for a channel that is already configured overwrites the stored tokens and registers the updated bridge provider.
For WeChat the cached-token short-circuit applies.
See [`channels add wechat`](#channels-add-wechat) for how to acquire a fresh account.
Rebuild the sandbox after the update so the image reflects the current channel set.
To remove a channel and clear its stored credentials, run:
```bash
nemoclaw my-assistant channels remove telegram
nemoclaw my-assistant channels remove wechat
```
`channels remove wechat` clears the bot token, deletes the `<sandbox>-wechat-bridge` OpenShell provider, and drops `wechat` from the sandbox's enabled-channel set.
The next rebuild produces an image without the WeChat channel block in `openclaw.json` and without the per-account state files under `/sandbox/.openclaw/openclaw-weixin/`.
For in-sandbox QR-paired channels (today: WhatsApp), `channels remove` destructively clears the in-sandbox session directory before the rebuild so the next rebuild does not restore stale auth files and reconnect the channel.
The cleanup targets `/sandbox/.openclaw/<channel>/` for OpenClaw and `/sandbox/.hermes/platforms/<channel>/` for Hermes.
The cleanup tries `openshell sandbox exec` and falls back to SSH if that does not produce the success sentinel.
If neither transport can reach a running sandbox for a QR-paired channel, the command exits non-zero and asks you to start the sandbox and re-run.
NemoClaw deliberately leaves the registry, policy preset, and `session.policyPresets` unchanged on that failure path, so a follow-up re-run completes the removal cleanly.
`channels remove whatsapp` clears the client-side Baileys session inside the sandbox.
It cannot deregister the linked device with WhatsApp's servers because that requires an active Baileys connection to issue the logout RPC, and the command no longer has that connection after it removes the session files.
The phone account will continue to list the sandbox as a Linked Device until you remove it manually from your phone (Settings → Linked Devices → tap the entry → Log out) or until WhatsApp's 14-day inactivity timeout expires.
Remove the entry from the phone if you plan to re-pair the same phone with a different sandbox.
Use `channels stop` when you want to pause a bridge without deleting credentials:
```bash
nemoclaw my-assistant channels stop telegram
nemoclaw my-assistant channels start telegram
nemoclaw my-assistant channels stop wechat
nemoclaw my-assistant channels start wechat
```
<AgentOnly variant="openclaw">
For WeChat specifically, `channels stop wechat` followed by a rebuild keeps the per-account state files under `/sandbox/.openclaw/openclaw-weixin/accounts/` intact even though the bridge is no longer wired up in `openclaw.json`.
</AgentOnly>
<AgentOnly variant="hermes">
For WeChat specifically, `channels stop wechat` followed by a rebuild keeps the per-account state files under `/sandbox/.hermes/` intact even though the bridge is no longer wired up in Hermes config.
</AgentOnly>
A subsequent `channels start wechat` plus rebuild revives the bridge against the same iLink account without a fresh QR scan.
The bot token is held by the OpenShell provider across the stop/start cycle.
Telegram, Discord, Slack, and WeChat each allow only one active consumer per channel credential.
Multiple sandboxes can use the same channel type at the same time when each sandbox uses a distinct bot/app token (or a distinct WeChat iLink bot account).
For example, two Telegram sandboxes can DM the same `TELEGRAM_ALLOWED_IDS` account as long as they use different `TELEGRAM_BOT_TOKEN` values.
For WeChat, each sandbox must own a distinct iLink `accountId` (bot identity).
Running two sandboxes against the same WeChat account causes one of them to lose messages.
If you enable a messaging channel and another sandbox already uses the same token, onboarding prompts you to confirm before continuing in interactive mode and exits non-zero in non-interactive mode.
For Slack, NemoClaw checks both the bot token and the Socket Mode app token so duplicate Socket Mode sessions do not compete silently.
If NemoClaw only has legacy channel metadata and cannot compare credential hashes, it keeps the conservative warning.
Re-run `channels add <channel>` with the intended token to refresh the stored non-secret hash.
`nemoclaw status` reports cross-sandbox overlaps so you can resolve duplicates before messages start dropping.
## Stop Messaging Delivery
Use `channels stop` when you want to pause one bridge and keep the sandbox running.
<AgentOnly variant="openclaw">
Use `nemoclaw tunnel stop` or its deprecated alias `nemoclaw stop` when you want to stop host auxiliary services and also ask NemoClaw to stop the OpenClaw gateway inside the selected sandbox.
</AgentOnly>
<AgentOnly variant="hermes">
Use `nemoclaw tunnel stop` when you want to stop host auxiliary services and also ask NemoClaw to stop the Hermes gateway inside the selected sandbox.
</AgentOnly>
Stopping the in-sandbox gateway stops Telegram, Discord, Slack, WeChat, and WhatsApp polling for that sandbox until you restart the sandbox or gateway.
## Confirm Delivery
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`, `slack`, `wechat`, or `whatsapp`) or review Common Integration Policy Examples (use the `nemoclaw-user-manage-policy` skill).
## Tunnel Command
<AgentOnly variant="openclaw">
When the host has `cloudflared`, `nemoclaw tunnel start` starts a cloudflared tunnel that can expose the dashboard with a public URL.
</AgentOnly>
<AgentOnly variant="hermes">
When the host has `cloudflared`, `nemoclaw tunnel start` starts a cloudflared tunnel that can expose the forwarded Hermes endpoint with a public URL.
</AgentOnly>
Set `CLOUDFLARE_TUNNEL_TOKEN` before running the command when you want to use a Cloudflare named tunnel instead of a generated quick-tunnel URL.
<AgentOnly variant="openclaw">
`nemoclaw tunnel stop` stops the tunnel and asks NemoClaw to stop the in-sandbox gateway for the selected or default sandbox.
The older `nemoclaw start` still works as a deprecated alias.
</AgentOnly>
<AgentOnly variant="hermes">
`nemoclaw tunnel stop` stops the tunnel and asks NemoClaw to stop the in-sandbox gateway for the selected or default sandbox.
</AgentOnly>
```bash
nemoclaw tunnel start
```
## Related Topics
<AgentOnly variant="openclaw">
- Deploy NemoClaw to a Remote GPU Instance (use the `nemoclaw-user-deploy-remote` skill) for remote deployment with messaging.
</AgentOnly>
- Architecture (use the `nemoclaw-user-reference` skill) for how providers, the gateway, and the sandbox fit together.
- Commands (use the `nemoclaw-user-reference` skill) for `channels add`, `channels remove`, `channels start`, `channels stop`, `tunnel start`, `tunnel stop`, and `status`.

82
.agents/skills/nemoclaw-user-manage-sandboxes/references/runtime-controls.md
View file

@ -1,82 +0,0 @@
# Runtime Controls and Sandbox Mutability
import { AgentOnly } from "../_components/AgentGuide";
This page explains which parts of a running NemoClaw sandbox can change immediately and which changes require a rebuild or re-onboard.
## What You Can Change at Runtime
NemoClaw applies its security posture in three layers: what onboarding bakes into the sandbox image, what the running sandbox can hot-reload, and what requires a rebuild or re-onboard.
The table below maps each commonly changed item to the layer that owns it and the command that changes it.
<AgentOnly variant="openclaw">
| Item | When the change takes effect | How to change it |
|---|---|---|
| Inference provider (cloud, NVIDIA Endpoints, local Ollama / vLLM, compatible-endpoint, …) | Rebuild required (`openclaw.json` is locked at sandbox creation) | `nemoclaw <name> rebuild` after picking a different provider with `nemoclaw inference set` |
| Inference model on the current provider | Rebuild required for OpenClaw; hot-reloadable for managed routers | `nemoclaw <name> rebuild` (OpenClaw) or `nemoclaw inference set` (router-based) |
| Sub-agent (Hermes / OpenClaw / …) | Re-onboard required (the sub-agent and its workspace are baked at onboard) | `nemoclaw onboard --recreate-sandbox` |
| Network policy preset (slack, discord, telegram, brave, …) | Runtime. Applies on the next request; rebuild only required if the preset adds bind-mounted secrets | `nemoclaw <name> policy-add <preset>` / `policy-remove <preset>` |
| Network allow-list (custom hosts) | Runtime. Picks up at next request | `openshell policy set` or interactive approval prompt at the gateway |
| Channel tokens (Slack / Discord / Telegram bot credentials) | Rebuild required (tokens are baked into the sandbox image at onboard so they never leave the host clear-text) | `nemoclaw <name> channels add <channel>` then accept the rebuild prompt |
| Channel enable/disable (turn a configured channel off without removing the token) | Rebuild required (`openclaw.json` is the source of truth at runtime, see #3453) | `nemoclaw <name> channels stop <channel>` then rebuild |
| Dashboard forward port | Runtime. Port is re-resolved on next `connect` | `NEMOCLAW_DASHBOARD_PORT=<port> nemoclaw <name> connect` |
| Dashboard bind address (loopback compared to all interfaces) | Runtime. Applies on next `connect` | `NEMOCLAW_DASHBOARD_BIND=0.0.0.0 nemoclaw <name> connect` (see #3259) |
| Default OpenClaw workspace template seed (`AGENTS.md`, `SOUL.md`, `IDENTITY.md`, `USER.md`, `TOOLS.md`, `HEARTBEAT.md`) | Locked at first sandbox boot. Re-onboard required to change the bake-time choice. | Set `NEMOCLAW_MINIMAL_BOOTSTRAP=1` before `nemoclaw onboard` to skip default template seeding for new/pristine workspaces. **Does not delete files already present.** Partial mitigation for #2598 (cuts ~3k tokens of project-context overhead off OpenClaw's per-turn bootstrap injection). |
| Web search backend (Brave, Tavily, and so on) | Runtime through `web.backend` config flag; rebuild only if `web.fetchEnabled` flips | `nemoclaw <name> config set --key web.backend --value tavily` |
| Filesystem layout (Landlock zones, read-only mounts, container caps) | **Locked at creation**. No runtime change | Re-onboard with `nemoclaw onboard --recreate-sandbox` |
| Sandbox name | **Locked at creation** | Re-onboard with a different `--name` |
| GPU passthrough enable / device selector | **Locked at creation** | Re-onboard with `--gpu` / `--sandbox-gpu-device` |
| Agents allow-list (`agents.list` in `openclaw.json`) | Runtime. OpenClaw hot-reloads on config change | Prefer agent or NemoClaw commands that keep host and sandbox state aligned |
| `openclaw.json` keys (general: model, agents.list, web.backend, channel config, and so on) | Mixed. Individual keys still follow the rebuild rules in the rows above, such as provider switch requiring rebuild even after editing the JSON. | Prefer NemoClaw host commands so the host registry and rebuilt image stay aligned |
If a row above conflicts with what you observe, the runtime source of truth inside the sandbox is `/opt/nemoclaw/openclaw.json`; the host registry caches metadata but the image and OpenClaw read from the in-sandbox file.
</AgentOnly>
<AgentOnly variant="hermes">
| Item | When the change takes effect | How to change it |
|---|---|---|
| Inference provider (cloud, NVIDIA Endpoints, local Ollama / vLLM, compatible-endpoint, …) | Runtime route changes apply immediately; rebuild if you need to rebake model metadata into the image | `nemoclaw inference set` for route changes, or `nemoclaw <name> rebuild` after changing build-time settings |
| Inference model on the current provider | Hot-reloadable through the Hermes config sync path | `nemoclaw inference set` |
| Agent runtime (Hermes compared to OpenClaw) | Re-onboard required (the agent and its state layout are baked at onboard) | `nemoclaw onboard --recreate-sandbox` or `nemoclaw onboard --agent openclaw --recreate-sandbox` |
| Network policy preset (slack, discord, telegram, brave, …) | Runtime. Applies on the next request; rebuild only required if the preset adds bind-mounted secrets | `nemoclaw <name> policy-add <preset>` / `policy-remove <preset>` |
| Network allow-list (custom hosts) | Runtime. Picks up at next request | `openshell policy set` or interactive approval prompt at the gateway |
| Channel tokens (Slack / Discord / Telegram bot credentials) | Rebuild required (tokens are baked into the sandbox image at onboard so they never leave the host clear-text) | `nemoclaw <name> channels add <channel>` then accept the rebuild prompt |
| Channel enable/disable (turn a configured channel off without removing the token) | Rebuild required (`/sandbox/.hermes/.env` and Hermes config are baked at image build time) | `nemoclaw <name> channels stop <channel>` then rebuild |
| API/dashboard forward port | Runtime. Port is re-resolved on next `connect` | `nemoclaw <name> connect` or `openshell forward start` |
| Filesystem layout (Landlock zones, read-only mounts, container caps) | **Locked at creation**. No runtime change | Re-onboard with `nemoclaw onboard --recreate-sandbox` |
| Sandbox name | **Locked at creation** | Re-onboard with a different `--name` |
| GPU passthrough enable / device selector | **Locked at creation** | Re-onboard with `--gpu` / `--sandbox-gpu-device` |
| Hermes `config.yaml` keys | Mixed. Inference keys can be patched by `nemoclaw inference set`; image, policy, and channel changes still require rebuild. | Prefer NemoClaw host commands so the host registry and rebuilt image stay aligned |
If a row above conflicts with what you observe, the runtime source of truth for
Hermes is `/sandbox/.hermes/config.yaml` plus `/sandbox/.hermes/.env`; the host
registry caches metadata but the image and Hermes runtime read from the
in-sandbox files.
</AgentOnly>
## See Also
The mutability table above is a consolidated index of information that lives in more detail on per-topic pages:
<AgentOnly variant="openclaw">
- [Manage Sandbox Lifecycle](../SKILL.md) for the full rebuild, re-onboard, and upgrade workflow.
- Switch Inference Providers (use the `nemoclaw-user-configure-inference` skill) for the rebuild path for provider and model changes.
- Customize Network Policy (use the `nemoclaw-user-manage-policy` skill) and Approve Network Requests (use the `nemoclaw-user-manage-policy` skill) for runtime policy editing and operator approval flow.
- Security Best Practices (use the `nemoclaw-user-configure-security` skill) for the per-attack-surface posture table that this page complements.
- OpenClaw Security Controls (use the `nemoclaw-user-configure-security` skill) for application-layer controls that operate independently of NemoClaw.
- CLI Commands Reference (use the `nemoclaw-user-reference` skill) for the full flag surface for every `nemoclaw` command, including the environment variables that affect runtime behavior.
</AgentOnly>
<AgentOnly variant="hermes">
- [Manage Sandbox Lifecycle](../SKILL.md) for the full rebuild, re-onboard, and upgrade workflow.
- Switch Inference Providers (use the `nemoclaw-user-configure-inference` skill) for the runtime route and rebuild paths for provider and model changes.
- Customize Network Policy (use the `nemoclaw-user-manage-policy` skill) and Approve Network Requests (use the `nemoclaw-user-manage-policy` skill) for runtime policy editing and operator approval flow.
- Security Best Practices (use the `nemoclaw-user-configure-security` skill) for the per-attack-surface posture table that this page complements.
- CLI Commands Reference (use the `nemoclaw-user-reference` skill) for the full flag surface for every `nemoclaw` and `nemoclaw` command, including the environment variables that affect runtime behavior.
</AgentOnly>

126
.agents/skills/nemoclaw-user-manage-sandboxes/references/workspace-files.md
View file

@ -1,126 +0,0 @@
# Workspace Files
import { AgentOnly } from "../_components/AgentGuide";
<AgentOnly variant="openclaw">
OpenClaw stores its personality, user context, and behavioral configuration in a set of Markdown files inside the sandbox.
These files live at `/sandbox/.openclaw/workspace/` and are collectively called **workspace files**.
## File Reference
| File | Purpose |
|---|---|
| `SOUL.md` | Defines the agent's persona, tone, and communication style. |
| `USER.md` | Stores information about the human the agent assists. |
| `IDENTITY.md` | Short identity card with name, language, emoji, and creature type. |
| `AGENTS.md` | Behavioral rules, memory conventions, safety guidelines, and session workflow. |
| `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
```
## Multi-Agent Deployments
A single NemoClaw sandbox can host more than one OpenClaw agent.
When you configure OpenClaw with multiple named agents (for example, a shared `main` agent
plus per-user agents for a Teams-integrated deployment), each agent gets its own
workspace directory alongside the default `workspace/`:
```text
/sandbox/.openclaw/
├── workspace/ # default agent (single-agent deployments)
├── workspace-main/ # named agent "main"
├── workspace-support/ # named agent "support"
└── workspace-ops/ # named agent "ops"
```
Each per-agent workspace contains the same Markdown file structure as the default
(`SOUL.md`, `USER.md`, `IDENTITY.md`, `AGENTS.md`, `MEMORY.md`, `memory/`).
Files are per-agent. Changes in `workspace-main/AGENTS.md` are not visible to
`workspace-support/`.
NemoClaw handles persistence and snapshots automatically for per-agent workspaces:
the sandbox entrypoint provisions each `workspace-<name>/` directly under the writable `.openclaw/` tree so state survives sandbox restart, and `nemoclaw <name> snapshot create` discovers every `workspace-<name>/` directory and includes it in the snapshot bundle alongside the default `workspace/`.
**Note:**
Files that operators typically want consistent across every agent workspace
(`AGENTS.md`, shared skills, common templates) are not synced automatically.
Each workspace is independent, and changes in one do not propagate.
NVIDIA tracks shared-file tooling (shared mount, `workspaces list` command) in [#1260](https://github.com/NVIDIA/NemoClaw/issues/1260).
## Persistence Behavior
Workspace files live in the sandbox's persistent state volume, not in the container image.
They survive normal container restarts, but NemoClaw deletes them when you destroy the sandbox.
### Preserved During Restart, Rebuild, and Upgrade
Sandbox restarts preserve workspace files because the persistent state volume outlives individual container restarts.
The `nemoclaw <name> rebuild` command and the sandbox upgrade flow also preserve workspace state.
Before replacing the container, NemoClaw snapshots the workspace state directories and restores them into the rebuilt sandbox.
If NemoClaw cannot archive any requested state file or directory, it reports the backup failure and stops before replacing the sandbox.
It does not continue with a partial backup.
### Deleted During Sandbox Destroy
Running `nemoclaw <name> destroy` deletes the sandbox and its persistent state volume.
NemoClaw removes workspace files from the sandbox unless you created a snapshot or backup first.
**Warning:**
Back up your workspace files before running `nemoclaw <name> destroy`.
See [Backup and Restore](backup-restore.md) for instructions.
## Editing Workspace Files
The agent reads these files at the start of every session.
You can edit them in two ways:
1. Ask your agent to update its persona, memory, or user context.
2. Use `nemoclaw <name> 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
- Set Up Task-Specific Sub-Agents (use the `nemoclaw-user-configure-inference` skill)
- [Backup and Restore workspace files](backup-restore.md)
- Commands reference (use the `nemoclaw-user-reference` skill)
</AgentOnly>
<AgentOnly variant="hermes">
Hermes stores durable agent state under `/sandbox/.hermes/` instead of the OpenClaw workspace directory.
The main Hermes configuration lives in `/sandbox/.hermes/config.yaml`, environment settings live in `/sandbox/.hermes/.env`, and runtime state such as logs, memory, platform sessions, and the SQLite state database lives under the same `.hermes` tree.
## Important Hermes State
| Path | Purpose |
|---|---|
| `/sandbox/.hermes/config.yaml` | NemoClaw-generated Hermes runtime configuration. |
| `/sandbox/.hermes/.env` | NemoClaw-generated environment and messaging placeholders. |
| `/sandbox/.hermes/state.db` | Hermes SQLite state database. |
| `/sandbox/.hermes/platforms/` | Messaging platform state, including QR-paired sessions such as WhatsApp. |
| `/sandbox/.hermes/logs/` | Hermes runtime logs. |
| `/sandbox/SOUL.md` | Durable top-level Hermes persona file preserved by NemoClaw snapshots. |
## Editing State
Prefer NemoClaw host commands for generated configuration such as model, provider, messaging, and policy settings.
Direct edits to `/sandbox/.hermes/config.yaml` or `/sandbox/.hermes/.env` can be overwritten by rebuilds.
Use `nemoclaw <name> connect` when you need to inspect runtime files interactively, or use `openshell sandbox download` and `openshell sandbox upload` for manual file transfer.

129
.agents/skills/nemoclaw-user-monitor-sandbox/SKILL.md
View file

@ -1,129 +0,0 @@
---
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. Trigger keywords - monitor nemoclaw sandbox, debug nemoclaw agent issues."
license: "Apache-2.0"
---
# Monitor Sandbox Activity and Debug Issues
## Prerequisites
- A running NemoClaw sandbox.
- The OpenShell CLI on your `PATH`.
import { AgentOnly } from "../_components/AgentGuide";
Use the NemoClaw status, logs, and TUI tools together to inspect sandbox health, trace agent behavior, and diagnose problems.
## Check Sandbox Health
Run the status command to view the sandbox state, gateway health, and active inference configuration:
```bash
nemoclaw <name> status
```
For local Ollama and local vLLM routes, `nemoclaw <name> status` also probes the host-side health endpoint directly.
This check catches a stopped local backend before you retry `inference.local` from inside the sandbox.
Key output fields include:
- Sandbox details show the configured model, provider, GPU mode, and applied policy presets.
- Gateway and process health show whether NemoClaw can still reach the OpenShell gateway and whether the in-sandbox agent process is running.
- Inference health for local Ollama and local vLLM shows `healthy` or `unreachable` together with the probed local URL.
- NIM status shows whether a NIM container is running and healthy when that path is in use.
Run `nemoclaw <name> status` on the host to check sandbox state.
Use `openshell sandbox list` for the underlying sandbox details.
## View Blueprint and Sandbox Logs
Stream the most recent log output from the blueprint runner and sandbox:
```bash
nemoclaw <name> logs
```
To follow the log output in real time:
```bash
nemoclaw <name> logs --follow
```
The `logs` command shows lifecycle and gateway output.
It does not export the structured per-session agent state that OpenClaw stores under `.openclaw/agents/`.
## Inspect Agent Session State
OpenClaw stores structured session state inside the sandbox.
Use these files when you need an audit trail, a compliance review surface, or replay tooling that includes assistant messages and tool activity.
| File | Purpose |
|---|---|
| `/sandbox/.openclaw/agents/main/sessions/<session-id>.jsonl` | Per-session event log. Use this file for audit trails and compliance dashboards. Records can include assistant messages, `thinking` blocks, tool calls, tool results, token usage, and cost metadata. |
| `/sandbox/.openclaw/agents/main/sessions/<session-id>.trajectory.jsonl` | Lower-level trajectory data for fine-grained replay. This file can be large, so avoid using it for routine audit summaries. |
| `/sandbox/.openclaw/agents/main/sessions/sessions.json` | Session index that maps known session keys to their persisted state. |
To inspect the session directory from the host, run a sandbox command:
```bash
nemoclaw sandbox exec <name> -- ls -lh /sandbox/.openclaw/agents/main/sessions
```
To copy a session log for offline review, use the OpenShell sandbox download command:
```bash
openshell sandbox download <name> /sandbox/.openclaw/agents/main/sessions/<session-id>.jsonl .
```
Treat exported session logs as sensitive data.
They can contain prompts, tool inputs, tool outputs, file paths, and cost metadata from the agent run.
## Monitor Network Activity in the TUI
Open the OpenShell terminal UI for a live view of sandbox network activity and egress requests:
```bash
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 (use the `nemoclaw-user-manage-policy` skill) for details on handling blocked requests.
## Test Inference
Run a test inference request to verify that the provider is responding:
<AgentOnly variant="openclaw">
```bash
nemoclaw my-assistant connect
openclaw agent --agent main -m "Test inference" --session-id debug
```
</AgentOnly>
<AgentOnly variant="hermes">
```bash
nemoclaw my-hermes connect
hermes
```
</AgentOnly>
If the request fails, check the following:
1. Run `nemoclaw <name> status` to confirm the active provider and endpoint.
For local Ollama and local vLLM, check the `Inference` line first.
If it shows `unreachable`, restart the local backend before retrying from inside the sandbox.
2. Run `nemoclaw <name> 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 (use the `nemoclaw-user-reference` skill) for common issues and resolution steps
- `nemoclaw-user-manage-policy` — Approve or Deny Agent Network Requests (use the `nemoclaw-user-manage-policy` skill) for the operator approval flow
- `nemoclaw-user-configure-inference` — Switch Inference Providers (use the `nemoclaw-user-configure-inference` skill) to change the active provider

11
.agents/skills/nemoclaw-user-monitor-sandbox/evals/evals.json
View file

@ -1,11 +0,0 @@
[
{
"id": "docs-monitoring-monitor-sandbox-activity-001",
"question": "I'm monitoring sandbox activity. Help me understand what the agent and sandbox are doing now so I can detect unhealthy or unexpected behavior early.",
"expected_skill": "nemoclaw-user-monitor-sandbox",
"ground_truth": "A NemoClaw-specific answer that helps the user understand what the agent and sandbox are doing now and gives enough concrete guidance, decision criteria, verification steps, or risk framing to detect unhealthy or unexpected behavior early.",
"expected_behavior": [
"Uses the expected_skill and does not make up answers if it cannot find the answer from the skill."
]
}
]

15
.agents/skills/nemoclaw-user-overview/SKILL.md
View file

@ -1,15 +0,0 @@
---
name: "nemoclaw-user-overview"
description: "Explains what NemoClaw covers: onboarding, lifecycle management, and agent operations within OpenShell containers, plus capabilities and why it exists. Use when users ask what NemoClaw is or what the project provides. For ecosystem placement or OpenShell-only paths, use the Ecosystem page; for internal mechanics, use How It Works. Trigger keywords - nemoclaw overview, openclaw always-on assistants, hermes agent, nvidia openshell, nvidia nemotron, nemoclaw ecosystem, nemohermes, nemoclaw vs openshell, run hermes openshell sandbox, openclaw openshell, sandboxed openclaw, how nemoclaw works, nemoclaw sandbox lifecycle blueprint, nemoclaw release notes, nemoclaw changelog."
license: "Apache-2.0"
---
# NemoClaw User Overview
## References
- **Load [references/overview.md](references/overview.md)** 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. Explains what NemoClaw covers: onboarding, lifecycle management, and agent operations within OpenShell containers, plus capabilities and why it exists.
- **Load [references/ecosystem-hermes.md](references/ecosystem-hermes.md)** when users ask about Hermes, OpenShell, and NemoClaw together, or when to use NemoClaw versus OpenShell for Hermes. Explains how Hermes, OpenShell, and NemoClaw form the ecosystem, NemoClaw's position in the stack, what NemoClaw adds beyond integrating OpenShell yourself, and when to prefer NemoHermes versus OpenShell.
- **Load [references/ecosystem.md](references/ecosystem.md)** when users ask about the relationship between OpenClaw, OpenShell, and NemoClaw, or when to use NemoClaw versus OpenShell. Explains how OpenClaw, OpenShell, and NemoClaw form the ecosystem, NemoClaw's position in the stack, what NemoClaw adds beyond the community sandbox, and when to prefer NemoClaw versus integrating OpenShell and OpenClaw directly.
- **Load [references/how-it-works.md](references/how-it-works.md)** for sandbox lifecycle and architecture mechanics; not for product definition (Overview) or multi-project placement (Ecosystem). Describes how NemoClaw works internally: CLI, plugin, blueprint runner, OpenShell orchestration, inference routing, and protection layers.
- **Load [references/release-notes.md](references/release-notes.md)** when users ask about recent changes, the release cadence, or where to track versioned assets on GitHub. Includes the NemoClaw release notes.

11
.agents/skills/nemoclaw-user-overview/evals/evals.json
View file

@ -1,11 +0,0 @@
[
{
"id": "docs-index-001",
"question": "I'm first arriving at the NemoClaw docs. Help me understand what NemoClaw helps me run and why it exists so I can decide whether it is worth installing before I spend time on setup.",
"expected_skill": "nemoclaw-user-overview",
"ground_truth": "A NemoClaw-specific answer that helps the user understand what NemoClaw helps me run and why it exists and gives enough concrete guidance, decision criteria, verification steps, or risk framing to decide whether it is worth installing before I spend time on setup.",
"expected_behavior": [
"Uses the expected_skill and does not make up answers if it cannot find the answer from the skill."
]
}
]

94
.agents/skills/nemoclaw-user-overview/references/ecosystem-hermes.md
View file

@ -1,94 +0,0 @@
# Ecosystem
NemoClaw provides onboarding, lifecycle management, and Hermes operations within OpenShell containers.
Use the `nemohermes` CLI alias when you work from the Hermes agent guide; it is equivalent to `nemoclaw` with the Hermes agent pre-selected.
This page describes how these projects form the ecosystem, where NemoClaw sits relative to [OpenShell](https://github.com/NVIDIA/OpenShell) and [Hermes](https://hermes-agent.nousresearch.com/docs/), and how to choose between NemoHermes and OpenShell alone.
## How the Stack Fits Together
A NemoClaw for Hermes deployment combines three pieces with distinct scopes: Hermes, OpenShell, and NemoClaw.
The following diagram shows how they fit together.
```mermaid
flowchart TB
NC["🦞 NVIDIA NemoClaw<br/>CLI, blueprint"]
OS["🐚 NVIDIA OpenShell<br/>Gateway, policy, inference routing"]
HM["Hermes<br/>Agent in sandbox"]
NC -->|orchestrates| OS
OS -->|isolates and runs| HM
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 HM nvDark
linkStyle 0 stroke:#76b900,stroke-width:2px
linkStyle 1 stroke:#76b900,stroke-width:2px
```
NemoClaw sits above OpenShell in the operator workflow.
It drives OpenShell APIs and CLI to create and configure the sandbox that runs Hermes.
Models and endpoints sit behind OpenShell's inference routing.
NemoClaw onboarding wires provider choice into that routing, including the Hermes Provider route when you onboard through `nemohermes`.
The following table shows the scope of each component in the stack.
| Project | Scope |
|---------|--------|
| [Hermes](https://hermes-agent.nousresearch.com/docs/) | The agent: runtime, tools, messaging adapters, and an OpenAI-compatible API 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, filesystem, and process policy, inference routing, and the operator-facing `openshell` CLI for those primitives. |
| NemoClaw | The NVIDIA reference stack on the host: `nemohermes` / `nemoclaw` CLI, versioned blueprint, channel messaging configured for OpenShell-managed delivery, and state migration helpers so Hermes runs inside OpenShell in a documented, repeatable way. |
## 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 Hermes blueprint encodes a hardened image, default policies, and orchestration so `nemohermes onboard` can create a known-good Hermes-on-OpenShell setup with less custom glue. |
| **OpenShell path** | You use OpenShell as the platform and supply your own container, Hermes install steps, policy YAML, provider setup, and any host bridges. OpenShell stays the sandbox and policy engine; nothing requires NemoClaw's blueprint or CLI. |
## What NemoClaw Adds Beyond Custom OpenShell
You can run Hermes inside OpenShell without NemoClaw by building your own image, writing policy YAML, registering providers, and wiring inference routes yourself.
That path is valid when you need full control over the container layout.
NemoClaw builds on OpenShell with additional security hardening, automation, and lifecycle tooling for Hermes.
The following table compares custom OpenShell integration with `nemohermes onboard`.
| Capability | Custom OpenShell + Hermes | `nemohermes onboard` |
|---|---|---|
| Sandbox isolation | Yes, when you apply OpenShell seccomp, Landlock, network namespace isolation, and no-new-privileges enforcement through your policy. | Yes. NemoClaw applies these through the blueprint and layers a Hermes-specific restrictive policy on top. |
| Credential handling | You create OpenShell providers manually with `openshell provider create` and configure placeholder resolution at egress. | NemoClaw creates OpenShell providers during onboarding and filters sensitive host environment variables from the sandbox creation command to reduce accidental leakage through build args. |
| Image hardening | Depends on your base image and install steps. | NemoClaw strips build toolchains (`gcc`, `g++`, `make`) and network probes (`netcat`) from the runtime image to reduce attack surface. |
| Filesystem policy | You define read-only and read-write paths in policy YAML. | NemoClaw defines a targeted layout: system paths (`/usr`, `/lib`, `/etc`) are read-only; `/sandbox` and `/sandbox/.hermes` are writable for agent state and configuration. |
| Inference setup | You configure OpenShell inference routing and Hermes `config.yaml` manually. | NemoClaw validates credentials from the host, configures the OpenShell route, and bakes model settings into `/sandbox/.hermes/config.yaml`. Hermes Provider onboarding is available through `nemohermes`. |
| Channel messaging | OpenShell delivers channel tokens through its provider system and L7 proxy; you configure Hermes platform adapters manually. | NemoClaw automates supported channel setup during onboarding and bakes Hermes env/config with placeholder tokens that OpenShell resolves at egress. |
| Blueprint versioning | No NemoClaw blueprint; your image tag is whatever you built locally. | NemoClaw downloads the blueprint artifact, checks version compatibility, and verifies its digest before applying. Running `nemohermes onboard` on different machines produces the same sandbox. |
| State migration | Not included unless you build it. | NemoClaw migrates agent state across machines with credential stripping and integrity verification. |
| Process count limits | You set process count limits manually with `--ulimit` or orchestrator config. | NemoClaw applies `ulimit -u 512` in the container entrypoint on top of OpenShell's seccomp and privilege dropping. |
## When to Use Which
Use the following table to decide when to use NemoHermes versus OpenShell alone.
| Situation | Prefer |
|-----------|--------|
| You want Hermes with minimal assembly, NVIDIA defaults, and the documented install and onboard flow. | NemoClaw (`nemohermes`) |
| You need maximum flexibility for custom images, a layout that does not match the NemoClaw Hermes blueprint, or a workload outside this reference stack. | OpenShell with your own integration |
| You are standardizing on the NVIDIA reference for always-on Hermes agents with policy and inference routing. | NemoClaw (`nemohermes`) |
| You are building internal platform abstractions where the NemoClaw CLI or blueprint is not the right fit. | OpenShell (and your orchestration) |
## Related Topics
- [Overview](overview.md) describes what NemoClaw is, including capabilities, benefits, and use cases.
- [How It Works](how-it-works.md) describes how NemoClaw runs, the blueprint, sandbox creation, routing, and protection layers for Hermes.
- Architecture (use the `nemoclaw-user-reference` skill) shows the repository structure and technical diagrams.
- Quickstart with Hermes (use the `nemoclaw-user-get-started` skill) installs NemoClaw and launches your first Hermes sandbox.
- [NemoClaw Community](https://github.com/NVIDIA/nemoclaw-community) collects community-driven examples, showcases, and integrations that demonstrate complete blueprint patterns.

93
.agents/skills/nemoclaw-user-overview/references/ecosystem.md
View file

@ -1,93 +0,0 @@
# Ecosystem
NemoClaw provides onboarding, lifecycle management, and OpenClaw operations within OpenShell containers.
This page describes how these projects form the ecosystem, 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
A NemoClaw for OpenClaw deployment combines three pieces with distinct scopes: OpenClaw, OpenShell, and NemoClaw.
The following diagram shows how they fit together.
```mermaid
flowchart TB
NC["🦞 NVIDIA NemoClaw<br/>CLI, plugin, blueprint"]
OS["🐚 NVIDIA OpenShell<br/>Gateway, policy, inference routing"]
OC["🦞 OpenClaw<br/>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 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.
The following table shows the scope of each component in the stack.
| 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, filesystem, and process 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 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 create 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. |
## What NemoClaw Adds Beyond the OpenShell Community Sandbox
OpenShell ships a community sandbox for OpenClaw.
Running `openshell sandbox create --from openclaw` pulls that package, builds the image, applies the bundled policy, and starts a working sandbox.
This is a valid path, and it produces a running OpenClaw environment with OpenShell isolation.
NemoClaw builds on that foundation with additional security hardening, automation, and lifecycle tooling.
The following table compares the two paths.
| Capability | `openshell sandbox create --from openclaw` | `nemoclaw onboard` |
|---|---|---|
| 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. |
| 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 OpenShell's provider system delivers them. |
| Channel messaging | OpenShell provides the credential provider system and L7 proxy that delivers channel tokens securely (including path-based resolution for Telegram's `/bot<token>/` 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. |
| State migration | Not included. | NemoClaw migrates agent state across machines with credential stripping and integrity verification. |
| Process count limits | OpenShell applies seccomp and privilege dropping. You set process count limits manually with `--ulimit` or orchestrator config. | NemoClaw applies `ulimit -u 512` in the container entrypoint to cap the process count and mitigate fork-bomb attacks, on top of OpenShell's seccomp and privilege dropping. |
## 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 for 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
- [Overview](overview.md) describes what NemoClaw is, including capabilities, benefits, and use cases.
- [How It Works](how-it-works.md) describes how NemoClaw runs, including the plugin, blueprint, sandbox creation, routing, and protection layers.
- Architecture (use the `nemoclaw-user-reference` skill) shows the repository structure and technical diagrams.
- [NemoClaw Community](https://github.com/NVIDIA/nemoclaw-community) collects community-driven examples, showcases, and integrations that demonstrate complete blueprint patterns.

137
.agents/skills/nemoclaw-user-overview/references/how-it-works.md
View file

@ -1,137 +0,0 @@
# NemoClaw Architecture Overview
import { AgentCli, AgentOnly } from "../_components/AgentGuide";
This page explains how NemoClaw runs supported agents inside an OpenShell sandbox and how the gateway connects the agent to inference, integrations, and policy.
NemoClaw does not replace OpenShell or your chosen agent runtime.
It packages them into a repeatable setup with a host CLI, a versioned blueprint, default policies, inference setup, and state helpers.
<AgentOnly variant="openclaw">
OpenClaw sandboxes also load the NemoClaw plugin for managed inference metadata and the `/nemoclaw` slash command.
</AgentOnly>
<AgentOnly variant="hermes">
Hermes sandboxes receive agent configuration under `/sandbox/.hermes` during onboarding instead of the OpenClaw plugin path.
</AgentOnly>
You can use that setup directly or adapt it for your own OpenShell integration.
## High-Level Flow
NemoClaw keeps the user workflow on the host while OpenShell enforces the sandbox boundary.
The gateway sits between NemoClaw control, the sandbox, inference providers, and external integrations.
That placement lets NemoClaw configure the environment without giving the agent direct access to host credentials or uncontrolled network egress.
![NemoClaw High-Level Component Diagram](images/nemoclaw-highlevel-component-diagram.png)
The diagram has the following components:
| Component | Role in the flow |
|-------|------------------|
| Users and operators | Start from the CLI, installer, dashboard, or an end-user channel. |
| NemoClaw control | Collects configuration, runs onboarding, prepares the blueprint, and asks OpenShell to create or update resources. |
| OpenShell gateway | Owns sandbox lifecycle, networking, policy enforcement, inference routing, and integration egress. |
| NemoClaw sandbox | Runs the onboarded agent with the selected blueprint contents and supporting tools. |
| Inference | Receives model requests through the gateway, using NVIDIA endpoints, NIM, or compatible APIs. |
| Integrations | Reach messaging services, MCP servers, GitHub, package indexes, or model hubs through gateway-managed egress. |
| State and artifacts | Store configuration, credentials, logs, workspace files, policies, and transcripts outside the running agent process. |
For repository layout, file paths, and deeper diagrams, see Architecture (use the `nemoclaw-user-reference` skill).
## Design Principles
NemoClaw follows these architecture principles.
Versioned blueprint
: Host-side orchestration uses a versioned blueprint and runner that can evolve on its own release cadence.
<AgentOnly variant="openclaw"> The OpenClaw sandbox plugin stays small and stable inside the container.</AgentOnly>
Respect CLI boundaries
: The <AgentCli /> 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 <AgentCli /> 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.
## CLI, Plugin, and Blueprint
NemoClaw is split into integration pieces on the host and in the sandbox image:
- The _host CLI_ runs onboarding, validates provider choices, stores configuration, and calls OpenShell commands for gateway, provider, sandbox, and policy operations.
<AgentOnly variant="openclaw">
- The _plugin_ is a TypeScript package that runs with OpenClaw inside the sandbox.
It registers the managed inference provider metadata, the `/nemoclaw` slash command, and runtime context hooks.
Runtime context is prepended as system guidance, so sandbox and policy instructions stay active without appearing in the visible chat transcript.
</AgentOnly>
<AgentOnly variant="hermes">
- NemoClaw writes Hermes runtime configuration into `/sandbox/.hermes` during onboarding, including `config.yaml`, environment files, and platform adapter settings for supported messaging channels.
</AgentOnly>
- The _blueprint_ is a versioned YAML package with the sandbox image, policy, inference profile, and supporting assets.
The runner resolves and verifies the blueprint before applying it through OpenShell.
This separation keeps agent-specific sandbox assets focused while allowing host orchestration and blueprint contents to evolve on their own release cadence.
## Sandbox Creation
When you run <AgentCli /> onboard, NemoClaw creates an OpenShell sandbox that runs your selected agent in an isolated container.
The host CLI and blueprint runner orchestrate this process through the OpenShell CLI:
1. NemoClaw resolves the blueprint, checks version compatibility, and verifies the digest.
2. The onboarding flow determines which OpenShell resources to create or update, such as the gateway, inference providers, sandbox, and network policy.
3. The runner 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.
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.
<AgentOnly variant="hermes">
For Hermes, runtime model switches through <AgentCli /> inference set update `/sandbox/.hermes/config.yaml` without rebuilding the sandbox.
</AgentOnly>
## 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 | Restricts system paths to read-only; `/sandbox` and `/tmp` are writable. | 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.
NemoClaw's runtime context tells supported agents to try allowed network and filesystem actions first, then report whether a failure came from policy denial, DNS, timeout, TLS, or filesystem access.
## Next Steps
<AgentOnly variant="openclaw">
- Read [Ecosystem](ecosystem.md) for stack-level relationships and NemoClaw versus OpenShell-only paths.
- Follow Quickstart with OpenClaw (use the `nemoclaw-user-get-started` skill) to launch your first sandbox.
- Refer to the Architecture (use the `nemoclaw-user-reference` skill) for the full technical structure, including file layouts and the blueprint lifecycle.
- Refer to Inference Options (use the `nemoclaw-user-configure-inference` skill) for detailed provider configuration.
- For details on the baseline rules, refer to Network Policies (use the `nemoclaw-user-reference` skill).
- For container-level hardening, refer to Sandbox Hardening.
</AgentOnly>
<AgentOnly variant="hermes">
- Read [Ecosystem](ecosystem.md) for stack-level relationships and NemoClaw versus OpenShell-only paths.
- Follow Quickstart with Hermes (use the `nemoclaw-user-get-started` skill) to launch your first sandbox.
- Refer to the Architecture (use the `nemoclaw-user-reference` skill) for the full technical structure, including file layouts and the blueprint lifecycle.
- Refer to Inference Options (use the `nemoclaw-user-configure-inference` skill) for detailed provider configuration.
- For details on the baseline rules, refer to Network Policies (use the `nemoclaw-user-reference` skill).
</AgentOnly>

BIN
.agents/skills/nemoclaw-user-overview/references/images/nemoclaw-highlevel-component-diagram.png
View file

Binary file not shown.
Side by side

Before

Width:  |  Height:  |  Size: 860 KiB

81
.agents/skills/nemoclaw-user-overview/references/overview.md
View file

@ -1,81 +0,0 @@
# Overview of NVIDIA NemoClaw
import { AgentCli, AgentOnly } from "../_components/AgentGuide";
NVIDIA NemoClaw is an open-source reference stack for running always-on AI agents more safely inside OpenShell containers.
NemoClaw provides onboarding, lifecycle management, and agent operations for supported runtimes in OpenShell sandboxes.
It incorporates policy-based privacy and security guardrails, giving you control over your agents' behavior and data handling.
These controls help self-evolving agents run more safely in clouds, on-premises environments, RTX PCs, and DGX Spark.
NemoClaw pairs hosted models on inference providers or local endpoints 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, <AgentCli /> CLI, onboarding, and related tooling as the reference way to run supported agents there.
| Capability | Description |
|-------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------|
| Sandbox supported agents | Creates an OpenShell sandbox pre-configured for your selected agent, with filesystem and network policies applied from the first boot. |
| 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. |
| Agent skills | Packages NemoClaw documentation as user skills so AI coding assistants can guide setup, inference configuration, policy management, monitoring, deployment, security review, and troubleshooting. |
| 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. |
| Messaging channels | OpenShell-managed processes connect Telegram, Discord, Slack, and similar platforms to the sandboxed agent. NemoClaw configures channels during onboarding; OpenShell supplies the native constructs, credential flow, and runtime supervision. |
| 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. |
## Benefits of Using NemoClaw
Autonomous AI agents 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.
NemoClaw provides the following benefits to mitigate these risks.
| Benefit | Description |
|----------------------------|------------------------------------------------------------------------------------------------------------------------|
| Sandboxed execution | Every agent runs inside an OpenShell sandbox with Landlock, seccomp, and network namespace isolation. The sandbox grants no access by default. |
| Routed inference | The OpenShell gateway routes model traffic to your selected provider, transparent to the agent. You can switch providers or models. Refer to Inference Options (use the `nemoclaw-user-configure-inference` skill). |
| Declarative network policy | YAML defines egress rules. OpenShell blocks unknown hosts and surfaces them to the operator for approval. |
| Single CLI | The <AgentCli /> 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 use cases such as the following.
| Use Case | Description |
|---------------------------|----------------------------------------------------------------------------------------------|
| Always-on assistant | Run a sandboxed agent 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
Navigate to the following topics to learn more about NemoClaw and how to install and use it.
<AgentOnly variant="openclaw">
- [Architecture Overview](how-it-works.md) to understand how NemoClaw works.
- [Ecosystem](ecosystem.md) to understand how your agent, OpenShell, and NemoClaw relate in the wider stack, and when to use NemoClaw versus OpenShell.
- Quickstart with OpenClaw (use the `nemoclaw-user-get-started` skill) to install NemoClaw and run your first OpenClaw sandbox.
- Agent Skills (use the `nemoclaw-user-agent-skills` skill) to load NemoClaw guidance into an AI coding assistant.
- [NemoClaw Community](https://github.com/NVIDIA/nemoclaw-community) to explore community-driven blueprint examples, showcases, and integrations.
- Inference Options (use the `nemoclaw-user-configure-inference` skill) to check the inference providers that NemoClaw supports and how inference routing works.
</AgentOnly>
<AgentOnly variant="hermes">
- [Architecture Overview](how-it-works.md) to understand how NemoClaw works.
- [Ecosystem](ecosystem.md) to understand how Hermes, OpenShell, and NemoClaw relate in the wider stack, and when to use NemoClaw versus OpenShell.
- Quickstart with Hermes (use the `nemoclaw-user-get-started` skill) to install NemoClaw and run your first Hermes sandbox with `nemoclaw`.
- Agent Skills (use the `nemoclaw-user-agent-skills` skill) to load NemoClaw guidance into an AI coding assistant.
- [NemoClaw Community](https://github.com/NVIDIA/nemoclaw-community) to explore community-driven blueprint examples, showcases, and integrations.
- Inference Options (use the `nemoclaw-user-configure-inference` skill) to check the inference providers that NemoClaw supports and how inference routing works.
</AgentOnly>

378
.agents/skills/nemoclaw-user-overview/references/release-notes.md
View file

@ -1,378 +0,0 @@
# Release Notes
import { AgentOnly } from "../_components/AgentGuide";
NVIDIA NemoClaw is available in early preview starting March 16, 2026.
Use this page to track the highlights of the latest release.
For more detailed release notes, refer to the [NemoClaw GitHub announcements](https://github.com/NVIDIA/NemoClaw/discussions/categories/announcements?discussions_q=is%3Aopen+category%3AAnnouncements).
## v0.0.65
NemoClaw v0.0.65 improves gateway recovery, sandbox state restore, local inference setup, and messaging activation:
- Gateway and sandbox recovery now wait for sustained serving state, recover sandboxes whose active gateway has lost its spec, preserve gateway routing state across more rebuilds, and allocate dashboard ports across multiple NemoClaw gateways. For more information, refer to Manage Sandbox Lifecycle (use the `nemoclaw-user-manage-sandboxes` skill) and Troubleshooting (use the `nemoclaw-user-reference` skill).
- Rebuild and restore flows preserve more OpenClaw and registry state. Config restore fails closed when a merge cannot be applied safely, reporter-owned model metadata survives rebuild restore, Shields auto-restore locks are re-confirmed after settle, and persisted agents survive registry recovery. For more information, refer to Backup and Restore (use the `nemoclaw-user-manage-sandboxes` skill) and NemoClaw CLI Commands Reference (use the `nemoclaw-user-reference` skill).
- Onboarding and inference setup fail earlier with clearer diagnostics. NemoClaw now handles Docker Desktop WSL CDI injection failures, surfaces silent OpenClaw runtime fallback, preflights managed vLLM model selection before side effects, accepts managed vLLM extra serve arguments, bounds compatible-endpoint probes, summarizes inference validation failures, and recomputes context windows after runtime model switches. For more information, refer to Troubleshooting (use the `nemoclaw-user-reference` skill), NemoClaw Inference Options (use the `nemoclaw-user-configure-inference` skill), and Switch Inference Providers (use the `nemoclaw-user-configure-inference` skill).
- Day-two CLI operations gained safer file and session workflows. `nemoclaw <name> download`, `nemoclaw <name> upload`, and `nemoclaw <name> sessions export` wrap the underlying sandbox file transfer and OpenClaw session export paths, while uninstall handles TTY confirmation and model-router teardown more predictably. For more information, refer to NemoClaw CLI Commands Reference (use the `nemoclaw-user-reference` skill) and Manage Sandbox Lifecycle (use the `nemoclaw-user-manage-sandboxes` skill).
- Messaging activation stores and exposes less credential-adjacent state. NemoClaw avoids logging WeChat QR poll tokens, resolves Discord per-account proxy settings for gateway WebSocket connections, compacts persisted messaging plans, completes manifest-based channel migration, and removes provider credential hashes from sandbox registry entries. For more information, refer to Messaging Channels (use the `nemoclaw-user-manage-sandboxes` skill) and Credential Storage (use the `nemoclaw-user-configure-security` skill).
- Hermes defaults and sandbox compatibility are narrower and easier to recover. The Hermes baseline policy no longer includes GitHub by default, NemoClaw reserves Hermes port `8642` across agent variants, and spawned OpenClaw sub-agents dial back through the sandbox interface instead of blocked loopback paths. For more information, refer to Network Policies (use the `nemoclaw-user-reference` skill), NemoClaw Quickstart with Hermes (use the `nemoclaw-user-get-started` skill), and Set Up Task-Specific Sub-Agents (use the `nemoclaw-user-configure-inference` skill).
## v0.0.64
NemoClaw v0.0.64 improves sandbox restore, onboarding stability, inference routing, messaging setup, and release validation:
- Snapshot restore preserves custom policy presets applied with `policy-add --from-file` or `policy-add --from-dir`, so restored sandboxes keep the custom egress rules that were recorded with the source sandbox. For more information, refer to Backup and Restore (use the `nemoclaw-user-manage-sandboxes` skill) and Customize the Network Policy (use the `nemoclaw-user-manage-policy` skill).
- OpenClaw onboarding keeps Brave Search pinned to the NemoClaw-managed runtime and preserves the `BRAVE_API_KEY` placeholder through build doctor. Docker-driver gateway health checks now follow the entrypoint path that actually launches the in-container gateway, which avoids misleading health reports on host-gateway setups. For more information, refer to NemoClaw CLI Commands Reference (use the `nemoclaw-user-reference` skill).
- Inference routes choose chat completions for providers that do not expose `/v1/responses`, including NVIDIA Endpoints, NVIDIA NIM, and Gemini-compatible routes. NemoClaw also adds a targeted Nemotron Ultra 550B compatibility fix for tool-less requests. For more information, refer to NemoClaw Inference Options (use the `nemoclaw-user-configure-inference` skill).
- Messaging setup refreshes stale render plans during rebuild, recovers replaced OpenClaw scope-upgrade approvals, and preinstalls Hermes WhatsApp bridge dependencies when the upstream lockfile is present. For more information, refer to Messaging Channels (use the `nemoclaw-user-manage-sandboxes` skill).
## v0.0.63
NemoClaw v0.0.63 improves sandbox recovery, OpenClaw configuration restore safety, local inference onboarding, messaging safeguards, and release validation:
- Sandbox lifecycle commands preserve and recover more state. `rebuild --yes` can recreate a locally registered sandbox that is missing from a healthy gateway, Docker-driver sandboxes can restart from OpenShell container labels after a host reboot, and `upgrade-sandboxes` detects recorded NemoClaw image drift even when the agent version itself matches. For more information, refer to Manage Sandbox Lifecycle (use the `nemoclaw-user-manage-sandboxes` skill).
- Snapshot-backed rebuilds preserve OpenClaw configuration more safely. Rebuilds now carry forward user-owned `openclaw.json` settings, merge restored config with freshly generated runtime state, and fail when restored config cannot be applied safely. For more information, refer to Backup and Restore (use the `nemoclaw-user-manage-sandboxes` skill).
- Onboarding diagnoses host setup and local inference issues earlier. The installer reports unusual Docker daemon access when a Linux user is outside the `docker` group, host DNS blocks are caught before NVIDIA provider validation, Ollama auth-proxy port conflicts recover during startup, and managed vLLM offers an interactive model picker for supported host profiles. For more information, refer to Use a Local Inference Server (use the `nemoclaw-user-configure-inference` skill).
- Messaging and Hermes startup paths enforce clearer runtime boundaries. Slack setup validates Socket Mode credentials and warns or blocks duplicate Slack Socket Mode sandboxes on a shared gateway, while Hermes direct gateway launch keeps environment-secret protections active and handles wrapped gateway arguments. For more information, refer to Messaging Channels (use the `nemoclaw-user-manage-sandboxes` skill).
## v0.0.62
NemoClaw v0.0.62 improves onboarding reliability for GPU sandboxes, local inference, gateway pairing, Hermes configuration, and release validation:
- GPU sandbox creation and local inference checks now match the runtime paths agents use. Docker-driver recreation prefers NVIDIA CDI when the host advertises a CDI spec, Jetson/Tegra sandboxes inherit the device-node group needed for CUDA, and local GPU inference is verified through `inference.local` from inside the sandbox runtime before onboarding reports success. For more information, refer to Use a Local Inference Server (use the `nemoclaw-user-configure-inference` skill).
- Onboarding and recovery fail earlier and stay quieter on common host drift. NemoClaw no longer requires `nc` for port readiness checks, clears pending gateway scope approvals after onboard and recover, preserves install-version fingerprints in package installs without `.git`, and suppresses fresh-sandbox provider cleanup probe noise. For more information, refer to NemoClaw CLI Commands Reference (use the `nemoclaw-user-reference` skill).
<AgentOnly variant="openclaw">
- Sandbox state and OpenClaw operations recover better after direct in-sandbox changes. Startup restores mutable OpenClaw config permissions after a raw in-sandbox `openclaw doctor --fix`, and the host CLI can now run `nemoclaw <name> agents list` alongside the existing agent add and delete passthrough commands. For more information, refer to NemoClaw CLI Commands Reference (use the `nemoclaw-user-reference` skill).
- WhatsApp pairing uses the compact QR renderer used by the real pairing flow. For more information, refer to Messaging Channels (use the `nemoclaw-user-manage-sandboxes` skill).
</AgentOnly>
<AgentOnly variant="hermes">
- Hermes setup exposes clearer operator state. Generated Hermes config records the upstream NemoClaw provider and model while still presenting Hermes as a custom proxy route, the provider menu labels Hermes choices more clearly, and NemoClaw rejects the reserved Hermes API port as a dashboard port before sandbox creation. For more information, refer to Messaging Channels (use the `nemoclaw-user-manage-sandboxes` skill).
</AgentOnly>
## v0.0.61
NemoClaw v0.0.61 improves sandbox network visibility, onboarding recovery, Hermes isolation, local inference restart behavior, and release validation:
- Agents and operators can inspect a redacted policy context that lists active presets, allowed host categories, approval paths, and policy drift states. Strict SSRF fetches now route through the sandbox proxy, stale `sandboxes.json` locks held by recycled PIDs are reclaimed, and dashboard tool-scope approvals can recover through doctor after sandbox startup. For more information, refer to Customize the Network Policy (use the `nemoclaw-user-manage-policy` skill).
- Sandbox hardening now caps open file descriptors at entrypoint, preserves the tunnel service PID directory across restarts, and keeps build-time plugin install state from forcing runtime npm calls offline. NemoClaw also closed coordinated code-scanning findings and consolidated HTTP probe policy handling without changing the operator contract. For more information, refer to Security Best Practices (use the `nemoclaw-user-configure-security` skill).
- Onboarding and rebuild paths recover more reliably across host and provider drift. ARM64 image-tar upload failures receive a clear classification with an image-reference workaround, rebuild detaches sandbox providers before delete, rebuilt resume snapshots keep session state, and messaging selector key sequences work during onboarding. For more information, refer to NemoClaw CLI Commands Reference (use the `nemoclaw-user-reference` skill).
- Local inference and Hermes setup cover more restart and configuration edge cases. Managed inference hostnames bypass host proxies, managed vLLM restarts after host reboot, DGX Station managed vLLM defaults to `Qwen/Qwen3.6-27B-FP8`, Hermes rejects dashboard port collisions during configuration, and Hermes recovery enforces the environment-secret boundary. For more information, refer to Use a Local Inference Server (use the `nemoclaw-user-configure-inference` skill).
- Messaging setup gives clearer feedback and stores more deterministic state. Slack now notifies the sender when a channel `@mention` is denied, operator-supplied placeholder keys can be registered during onboarding, `messagingPlan` persists into resume state, and channel conflict detection now uses the manifest-plan architecture. For more information, refer to Messaging Channels (use the `nemoclaw-user-manage-sandboxes` skill).
- Release validation now runs real shell-boundary assertions through Vitest E2E support, includes an opt-in live scenario project, shards CLI coverage, adds a docs-only PR fast path, and trims slow CLI subprocess coverage.
## v0.0.60
NemoClaw v0.0.60 improves runtime guidance, sandbox lifecycle reliability, local inference setup, messaging enrollment, and maintainer safeguards:
- OpenClaw runtime guidance stays active without appearing in the visible chat transcript, and sandbox network and filesystem context now tells agents to try allowed in-sandbox actions before reporting them unavailable. OpenClaw device-approval policy also uses the same allowlist and scope behavior during startup and connect. For more information, refer to Architecture (use the `nemoclaw-user-reference` skill).
- Onboarding and sandbox lifecycle paths preserve more host state. NemoClaw uses the package-managed OpenShell gateway user service when available, scopes gateway and dashboard cleanup by sandbox instance, detects Docker-driver sandboxes without writing the local gateway marker, rolls back failed Docker GPU patches, honors `.dockerignore` for custom `--from <Dockerfile>` contexts, and can skip default workspace-template seeding with `NEMOCLAW_MINIMAL_BOOTSTRAP=1`. For more information, refer to NemoClaw CLI Commands Reference (use the `nemoclaw-user-reference` skill).
- Local inference setup is more predictable across NVIDIA NIM, Ollama, vLLM, DGX Spark, DGX Station, Anthropic-compatible routes, and Hermes. NemoClaw pulls NIM images by platform digest, uses stable managed-vLLM images and updated DGX model profiles, tightens Ollama fit checks, synchronizes Anthropic route metadata, preserves Hermes proxy API-key placeholders, and serves the prebuilt Hermes dashboard assets from the sandbox image. For more information, refer to NemoClaw Inference Options (use the `nemoclaw-user-configure-inference` skill).
- Messaging and day-two CLI operations share more common plumbing. Messaging enrollment uses manifest hooks across Telegram, Discord, Slack, WeChat, and WhatsApp, `nemoclaw tunnel status` reports Cloudflare tunnel state directly, global `status` and `list` honor sandbox environment overrides consistently, and installed OpenClaw skills are mirrored into the agent home directory for session startup. For more information, refer to Messaging Channels (use the `nemoclaw-user-manage-sandboxes` skill).
- Policy and secret-handling safeguards cover more edge cases. Non-interactive `NEMOCLAW_POLICY_TIER` validation fails before side effects, interactive onboarding ignores invalid environment values and prompts normally, safe common egress presets are available where supported, persistent-memory scanning catches additional OpenAI and Slack token shapes, and Hermes remote secrets stay out of sandbox-visible surfaces. For more information, refer to Security Best Practices (use the `nemoclaw-user-configure-security` skill).
## v0.0.59
NemoClaw v0.0.59 improves OpenClaw runtime compatibility, inference setup, credential reuse, messaging safeguards, and sandbox startup diagnostics:
- OpenClaw sandboxes stay aligned with the live gateway and current runtime layout. Sandbox startup reconciles the agent model from the live gateway, refreshes the OpenClaw plugin registry after gateway startup, pins OpenClaw home, state, and workspace paths inside the sandbox, and handles OpenClaw 2026.5.27 approval compatibility. For more information, refer to NemoClaw CLI Commands Reference (use the `nemoclaw-user-reference` skill).
- Inference setup has newer model choices and longer first-start budgets for local runtimes. NVIDIA Endpoints includes the Nemotron 3 Ultra 550B option, Local Ollama uses `qwen3.5:9b` as the starter fallback, managed vLLM on DGX Spark uses a 128K context window for `nvidia/Qwen3.6-35B-A3B-NVFP4`, and Local NVIDIA NIM waits longer for first container startup while still failing fast when the container exits. For more information, refer to NemoClaw Inference Options (use the `nemoclaw-user-configure-inference` skill).
- Hermes sandboxes can route Anthropic Messages API traffic through managed inference, and runtime model switches keep the Hermes config synchronized with the OpenShell route. For more information, refer to Switch Inference Models at Runtime (use the `nemoclaw-user-configure-inference` skill).
- Credential and messaging boundaries are clearer during day-two operations. Rebuild and remote-provider update paths can reuse credentials already stored in the OpenShell gateway when the host environment is empty, `channels add` warns or aborts before multiple sandboxes compete for the same token-based messaging credential, and `status` reports cross-sandbox channel overlaps. For more information, refer to Messaging Channels (use the `nemoclaw-user-manage-sandboxes` skill).
- Sandbox startup and host preflight failures provide more actionable recovery guidance. NemoClaw heals `~/.nemoclaw` directory and config-file permissions on read paths, detects missing or stale NVIDIA CDI specs before GPU containers fail, probes legacy gateway containers before host-alias operations, and preserves argument validation before runtime probing. For more information, refer to Troubleshooting (use the `nemoclaw-user-reference` skill).
## v0.0.58
NemoClaw v0.0.58 improves GPU proof reporting, local-inference metadata, policy failure handling, Hermes messaging reliability, OpenClaw diagnostics, and release-prep documentation:
- GPU and local-inference setup report more accurate state. WSL Docker Desktop on ARM64 can accept a reported NVIDIA GPU only after a bounded Docker CUDA proof succeeds, `nemoclaw <name> status` shows whether sandbox CUDA usability is verified, unverified, or failed, managed vLLM uses runtime `max_model_len` metadata for the baked context window when available, and DeepSeek managed-vLLM startup receives the runtime keyword arguments it expects. For more information, refer to Use a Local Inference Server (use the `nemoclaw-user-configure-inference` skill).
- Onboarding and installer failures stop earlier with clearer recovery guidance. The installer checks for `strings` from `binutils` before clone, build, or OpenShell download work; Docker-driver gateway startup fails fast when Docker is unreachable; WSL Docker Desktop diagnostics explain unsupported native Docker-in-WSL routes; Windows-host Ollama detection also checks the installed Windows process when the daemon is stopped; and custom proxy host and port settings are forwarded into the runtime container. For more information, refer to Prerequisites (use the `nemoclaw-user-get-started` skill).
- Policy and sandbox hardening paths avoid misleading success. `policy-add` refuses to merge a preset when the live policy read returns unparseable output, custom preset application reports when the gateway accepted a preset but the sandbox registry could not record it, and `NEMOCLAW_REQUIRE_CAP_DROP=1` lets operators make entrypoint capability dropping fail closed. For more information, refer to NemoClaw CLI Commands Reference (use the `nemoclaw-user-reference` skill).
- OpenClaw runtime diagnostics can export conversation traces through the `diagnostics-otel` plugin. Set `NEMOCLAW_OPENCLAW_OTEL=1` before onboarding or rebuilding an OpenClaw sandbox to bake the plugin config and apply the local OTLP policy preset. For more information, refer to NemoClaw CLI Commands Reference (use the `nemoclaw-user-reference` skill).
- Hermes sandboxes are more reliable across messaging, inference, and startup repair paths. Slack channel rebuilds enable the Hermes Slack platform block, `inference.local` routes include the placeholder API key LiteLLM expects, Telegram pseudo-tool text is normalized only for the active chat platform, the messaging response patch preserves Hermes method binding, retry markers are cleared before explicit command dispatch, and Hermes state repair preserves writable history and background dispatcher behavior in locked runtime state. For more information, refer to Messaging Channels (use the `nemoclaw-user-manage-sandboxes` skill).
## v0.0.57
NemoClaw v0.0.57 improves multi-agent command workflows, local inference setup, messaging channel reliability, sandbox diagnostics, policy persistence, and installer pinning:
- OpenClaw sandboxes can manage conversation sessions and secondary agents from the host CLI. Use `nemoclaw <name> sessions` to list sessions, reset a session key through the OpenClaw gateway, or delete a non-main session, and use `nemoclaw <name> agents add` or `nemoclaw <name> agents delete` to invoke the in-sandbox OpenClaw agent commands. Build-time config also accepts `NEMOCLAW_EXTRA_AGENTS_JSON` so operators can bake validated secondary-agent entries into `agents.list` without replacing the primary `main` agent. For more information, refer to NemoClaw CLI Commands Reference (use the `nemoclaw-user-reference` skill).
- Local inference setup is more observable and more resilient. Managed vLLM on DGX Spark defaults to `nvidia/Qwen3.6-35B-A3B-NVFP4`, streams Hugging Face model-download progress, polls `/v1/models` for readiness, and uses a progress-aware Docker pull watchdog. Local Ollama routes request streaming usage metadata so OpenClaw token counters can update, and `connect` warns when the recorded inference route diverges from the live gateway route instead of reverting silently. For more information, refer to Use a Local Inference Server (use the `nemoclaw-user-configure-inference` skill).
- Onboarding and re-onboarding preserve more operator intent. Linux Docker-driver onboarding can auto-apply a narrow UFW rule for the sandbox-to-gateway bridge when `NEMOCLAW_AUTO_FIX_FIREWALL=1`, verifies host-network local-inference reachability before reporting success, reuses healthy containerized gateways, binds gateway state by port, rolls back a freshly-created sandbox when setup is cancelled at the policy preset step, and carries finalized policy preset selections across later re-onboard runs. For more information, refer to NemoClaw CLI Commands Reference (use the `nemoclaw-user-reference` skill).
- Messaging channel setup fails earlier and leaves fewer partial changes. Slack setup validates both Socket Mode tokens before saving credentials, `channels add` checks the matching built-in policy preset before prompting or persisting channel state, failed preset application rolls back staged bridge changes when possible, WhatsApp pairing renders a compact QR code with clearer gateway diagnostics, and Slack runtime placeholders are normalized before OpenClaw starts. For more information, refer to Messaging Channels (use the `nemoclaw-user-manage-sandboxes` skill).
- Sandbox status and repair output are more actionable. `nemoclaw <name> status` reports Docker daemon, stopped-container, dashboard-port-conflict, and paused-container layers without running misleading inference probes, `doctor` skips stale Kubernetes-only gateway container checks on Docker-driver installs, and stale local registry entries are preserved so the suggested `rebuild --yes` recovery path still has the metadata it needs. For more information, refer to NemoClaw CLI Commands Reference (use the `nemoclaw-user-reference` skill).
- Installer and policy guidance tightened. Piped installs show the correct `NEMOCLAW_INSTALL_TAG` placement and fail clearly when a requested ref is unavailable, the `pypi` preset allows the `uv` package manager binary, and Jira validation now uses a body-visible Atlassian API probe so operators can distinguish blocked and approved curl traffic. For more information, refer to Common NemoClaw Integration Policy Examples (use the `nemoclaw-user-manage-policy` skill).
## v0.0.56
NemoClaw v0.0.56 improves install safety, local-inference validation, messaging diagnostics, sandbox lifecycle reporting, and day-two command behavior:
- Public installer and `nemoclaw update` flows now follow the admin-promoted `lkg` release tag by default, so curl-piped installs and update checks target the maintained build while validation catches up to newer semver tags. Non-interactive Linux installs can also reactivate Docker group membership through `sg docker` and continue in the same installer run when that path is available. For more information, refer to Manage Sandbox Lifecycle (use the `nemoclaw-user-manage-sandboxes` skill).
- `nemoclaw <name> status`, `nemoclaw <name> connect`, and `nemoclaw upgrade-sandboxes` now probe the live sandbox agent version before deciding whether a rebuild is needed, instead of trusting stale host metadata. Status output reports when the version cannot be verified and points at rebuild when the running agent may predate the current install. For more information, refer to NemoClaw CLI Commands Reference (use the `nemoclaw-user-reference` skill).
- GPU Docker-driver local-inference onboarding now verifies that host-network sandboxes can reach the selected Ollama or vLLM health endpoint before onboarding reports success. Failures now include the provider endpoint, container network mode, and recovery guidance, which avoids discovering the broken route only after the first agent prompt. For more information, refer to Use a Local Inference Server (use the `nemoclaw-user-configure-inference` skill).
- Messaging setup is more diagnosable. Slack setup validates both required Slack credentials before enabling the channel, WhatsApp pairing renders a compact scan-friendly QR for OpenClaw sandboxes and separates gateway close errors from QR rendering, and Telegram DM allowlist aliases continue to work for existing automation. For more information, refer to Messaging Channels (use the `nemoclaw-user-manage-sandboxes` skill).
- Command ergonomics are clearer for common day-two paths. `nemoclaw inference set` without both `--provider` and `--model` now points users to the underlying `openshell inference set` command, `nemoclaw <name> skill remove <skill>` removes uploaded skills by `SKILL.md` name, `nemoclaw <name> status --json` supports per-sandbox automation, and `nemoclaw debug --sandbox` validates explicit sandbox names before writing diagnostics. For more information, refer to NemoClaw CLI Commands Reference (use the `nemoclaw-user-reference` skill).
- Policy and sandbox base-image compatibility improved. The `pypi` preset allows the `uv` package manager binary, the sandbox base image includes `tmux` for OpenClaw's bundled tmux-session flow, and Jira preset validation docs now use observable status probes. For more information, refer to Common NemoClaw Integration Policy Examples (use the `nemoclaw-user-manage-policy` skill).
- Uninstall, rebuild, and snapshot flows protect user state more consistently. `nemoclaw uninstall` preserves host-side backups and the sandbox registry by default, rebuilds preserve explicit CPU-only sandbox intent, and snapshot restore blocks ambiguous existing-destination rollbacks unless you opt in with `--force`. For more information, refer to Manage Sandbox Lifecycle (use the `nemoclaw-user-manage-sandboxes` skill).
## v0.0.55
NemoClaw v0.0.55 improves local Ollama onboarding reliability, plugin secret-scanner resilience, and messaging-channel prompt clarity:
- Local Ollama validation retries host-side curl process timeouts with a larger timeout before failing, and Docker runtime detection retries `docker info` before choosing the local inference route. For more information, refer to Use a Local Inference Server (use the `nemoclaw-user-configure-inference` skill).
- The NemoClaw OpenClaw plugin keeps the memory secret scanner active when OpenClaw runs in embedded fallback mode without a usable path resolver. The scanner falls back to literal memory and workspace-relative paths instead of crashing before the first write-tool call. For more information, refer to Security Best Practices (use the `nemoclaw-user-configure-security` skill).
- The onboarding messaging-channel picker now states that pressing Enter with no channels selected skips messaging setup. For more information, refer to Messaging Channels (use the `nemoclaw-user-manage-sandboxes` skill).
## v0.0.54
NemoClaw v0.0.54 updates messaging activation, Windows WSL onboarding, NemoHermes dashboard access, and sandbox repair paths:
- Generated OpenClaw config now marks Telegram, Discord, Slack, and WhatsApp as enabled at the channel level. Selected messaging plugins are pinned during the image build, and `channels add` verifies Telegram, Discord, and Slack bridge startup after the rebuild instead of leaving silent channel failures for later debugging. For more information, refer to Messaging Channels (use the `nemoclaw-user-manage-sandboxes` skill).
- The Windows bootstrap flow waits for Ubuntu account creation before touching Docker settings, enables Docker Desktop WSL integration for the target distro, avoids changing the global WSL default distro, and adds WSL-specific Docker reachability hints during onboarding. For more information, refer to Prepare Windows for NemoClaw.
- Windows-host Ollama setup inside WSL now requires the Docker Desktop WSL integration path. NemoClaw still shows Windows-host Ollama options when it detects them, but labels the Docker Desktop requirement and blocks unsupported native Docker-in-WSL selections before it tries to start or install Ollama. For more information, refer to Use a Local Inference Server (use the `nemoclaw-user-configure-inference` skill).
- NemoHermes can expose the optional native Hermes web dashboard separately from the OpenAI-compatible API. Set `NEMOCLAW_HERMES_DASHBOARD=1` before onboarding to start and forward the dashboard on port `9119`, with `NEMOCLAW_HERMES_DASHBOARD_PORT` and `NEMOCLAW_HERMES_DASHBOARD_TUI` available for port and TUI tab control. For more information, refer to NemoClaw Quickstart with Hermes.
- Onboarding diagnostics include more copy-paste-ready recovery hints. Invalid sandbox names now include a `Try: <suggested-slug>` line when NemoClaw can derive a valid name, and non-interactive NVIDIA Endpoints setup prints the exact `export NVIDIA_INFERENCE_API_KEY=nvapi-...` shape when the key is missing. For more information, refer to NemoClaw CLI Commands Reference (use the `nemoclaw-user-reference` skill).
- Homebrew stays on the Linuxbrew prefix while exposing installed formula commands in sandbox shell sessions, the `/nemoclaw` slash command activates at OpenClaw startup again, Hermes rebuilds tolerate older release tarballs that lack optional UI package lockfiles, and device scope-upgrade approvals recover without being pinned to the old gateway-scoped request. For more information, refer to Common NemoClaw Integration Policy Examples (use the `nemoclaw-user-manage-policy` skill).
- The host-gateway allowance for OpenClaw `web_fetch` is confined to the trusted proxy path, while strict and direct paths continue to block host-gateway names. Hermes Provider onboarding skips the host-side smoke probe only for OAuth-backed setup and keeps direct validation for Nous API key setup. For more information, refer to NemoClaw Inference Options (use the `nemoclaw-user-configure-inference` skill).
## v0.0.53
NemoClaw v0.0.53 focuses on safer sandbox recreation, stricter onboarding preflight defaults, local inference reliability, policy coverage, and day-two repair workflows:
- `nemoclaw onboard` backs up workspace state before deleting an existing sandbox during recreation, including sandboxes that are registered but not ready. If the backup is partial or fails, onboarding aborts before delete so workspace, skills, extensions, identity, memory, messaging state, and credentials are not silently dropped. Set `NEMOCLAW_RECREATE_WITHOUT_BACKUP=1` only when you intentionally want a fresh workspace.
- Under-provisioned container-runtime warnings now default to abort in interactive onboarding. Pressing Enter at the warning stops the run so you can resize Docker Desktop or Colima before the sandbox build stalls. Non-interactive runs continue with a warning, and `NEMOCLAW_IGNORE_RUNTIME_RESOURCES=1` still suppresses the check when you have already accepted the resource trade-off.
- OpenClaw sandboxes can use the new `openclaw-pricing` policy preset for model-pricing reference fetches from LiteLLM and OpenRouter. NemoClaw suggests this preset during OpenClaw onboarding so session JSONL records can populate `usage.cost` without widening egress beyond the two read-only pricing endpoints.
- Local Ollama onboarding is more accurate. NemoClaw validates the `/api/tags` response body through the authenticated proxy, honors accepted no-tools overrides through validation and proxy setup, and uses Ollama's reported runtime context length for `contextWindow` unless you set `NEMOCLAW_CONTEXT_WINDOW`.
- Onboarding and gateway reuse recover from more host-runtime drift. NemoClaw recovers stopped gateways before preserving PVC-backed state, verifies gateway containers before reusing port-conflict state, defers Docker-driver gateway teardown until step `[2/8]`, records Docker-driver sandboxes on macOS, and uses Docker `--gpus` rather than CDI repair on WSL Docker Desktop.
- The sandbox and integration paths handle more common failures cleanly, including Brave Search credential rewrite through OpenShell providers, Telegram placeholder repair, host-gateway `web_fetch` routing, read-only host targets for `share mount`, live gateway drift in `list`, host-alias Kubernetes invocations, Jetson bridge DNS preflight failures, and non-ready sandboxes during maintenance backups.
- Hermes startup no longer treats a fresh root-entrypoint layout as locked state, which avoids false locked-layout detection during sandbox boot.
- Maintainer tooling can export a signed skills catalog, detect untracked files during skills refresh diffs, and run the stale-issue verification workflow added for maintainers.
## v0.0.52
NemoClaw v0.0.52 upgrades the bundled OpenClaw runtime, repairs Hermes sandbox startup, restores onboarding ready output, and hardens Slack onboarding, Windows bootstrap, and private-network handling:
- Bundles OpenClaw 2026.5.22 as the NemoClaw runtime target through `OPENCLAW_VERSION` in the NemoClaw Dockerfiles. The runtime upgrade addresses Telegram, Discord, and Slack channel registration issues seen on the 2026.5.18 runtime. `nemoclaw-blueprint/blueprint.yaml` keeps `min_openclaw_version` as a compatibility floor for direct blueprint consumers, so the blueprint floor can be lower than the Dockerfile target. Run `nemoclaw <name> rebuild` to pick up the new OpenClaw runtime in existing sandboxes.
- Hermes sandbox startup is more reliable on the v0.14 root entrypoint. NemoClaw precreates `hooks`, `image_cache`, `audio_cache`, and `logs/curator` under `HERMES_HOME`, makes `/sandbox/.hermes` sticky group-writable so the `gateway` user can create runtime state without removing sandbox-owned config files, stops precreating `/sandbox/.hermes/gateway.pid` as a symlink that Hermes v0.14 treats as a PID race, and clears legacy PID and lock state before launch.
- `nemoclaw onboard` ready output points users at `nemoclaw <name> dashboard-url --quiet` again, restoring the dashboard guidance that regressed during an earlier onboarding refactor.
- Slack onboarding validates preconfigured Slack tokens before treating Slack as configured. Invalid `SLACK_BOT_TOKEN` values from the environment or stored credentials no longer cause onboarding to skip the Slack prompt, so the wizard re-prompts for a valid `xoxb-...` token instead of silently advancing with a token Slack cannot use.
- The Windows bootstrap script defers first-run Ubuntu account setup to a separate WSL handoff window again, which keeps PowerShell prompt alignment intact during install. The default distro is `Ubuntu-24.04`, and `bootstrap-windows.ps1 -DistroName Ubuntu` reuses an existing `Ubuntu` distribution.
- The blueprint private-network blocklist reloads when `private-networks.yaml` changes on disk, so long-running NemoClaw processes validate SSRF and private-network rules against the current file instead of stale cached data.
## v0.0.51
NemoClaw v0.0.51 improves messaging controls, local inference setup, sandbox diagnostics, policy validation, and onboarding recovery:
- Slack setup now supports channel allowlisting. During onboarding, `channels add slack`, and non-interactive rebuilds, set `SLACK_ALLOWED_CHANNELS` to restrict channel `@mention` handling to selected Slack channel IDs. Combine it with `SLACK_ALLOWED_USERS` when you want both channel and member checks.
- Local Ollama setup now detects host installations that are below the minimum supported version and offers an explicit upgrade path. On macOS, NemoClaw uses Homebrew. On Linux, NemoClaw uses the system installer for upgrades and refuses non-interactive upgrade paths that would require a hidden sudo prompt.
- Non-interactive Linux Ollama setup can use a sudo-free user-local install path when passwordless sudo is unavailable. The docs now describe `NEMOCLAW_OLLAMA_INSTALL_MODE`, the user-local install trade-offs, and the manual `zstd` requirement.
- Managed Ollama model selection now uses a memory-aware registry for starter models. If a known bootstrap model does not fit currently available GPU memory, NemoClaw warns and falls back to the largest known model that does fit instead of starting a model that is likely to fail.
- `nemoclaw onboard` restores the managed vLLM menu entry for DGX Spark and DGX Station hosts, which had been hidden after a previous onboard refactor dropped the `gpu.platform` value the vLLM menu builder relies on.
- `nemoclaw resources` and `NEMOCLAW_RESOURCE_PROFILE` expose sandbox CPU and memory profiles. Profiles can be selected during onboarding, and `NEMOCLAW_CPU` or `NEMOCLAW_RAM` can override the selected profile for scripted runs.
- Cloudflare named tunnels are supported through `CLOUDFLARE_TUNNEL_TOKEN`. `nemoclaw tunnel start` passes the token through the environment and expects the named tunnel route to already point at the dashboard port.
- Jira policy validation guidance now matches the maintained preset. Use a Node HTTPS status probe for Atlassian API access and the body-visible `api.atlassian.com/oauth/token/accessible-resources` curl probe when validating approved requests manually. Plain `curl -s` against `auth.atlassian.com` can return empty output even when reachable, so it is not a pass/fail signal.
- Sandbox logs merge OpenClaw gateway output and OpenShell audit events into one stream, and `--tail` applies once to the merged result so policy denials appear beside gateway logs.
- Onboarding recovers more cleanly across host and runtime edge cases, including root-owned config sync directories, stale dashboard port allocation, unreachable Docker daemons, stale dashboard forwards, default NVIDIA CDI spec directories, and Linux Docker-driver health checks.
## v0.0.50
NemoClaw v0.0.50 focused on onboarding reliability, local inference hardening, messaging diagnostics, and sandbox lifecycle cleanup:
- `nemoclaw onboard` detects DGX Spark hosts where managed Ollama falls back to CPU execution. Local inference setup fails the Ollama validation step with a tailored diagnostic, adds a Spark `OLLAMA_LLM_LIBRARY=cuda_v13` systemd override when that backend is installed, and enables the managed Linux Ollama service so local inference survives reboot.
- Compatible endpoint setup rejects `host.docker.internal` inference URLs because OpenShell sandboxes do not have a portable host-service route through that name. Use Local Ollama's authenticated proxy path or a policy-managed host service instead.
- Telegram setup now surfaces BotFather group privacy guidance. Disable privacy mode, then remove and re-add the bot to each group before testing group delivery.
- Maintenance commands recover the OpenShell gateway before retrying sandbox-list operations, which makes rebuild, recover, upgrade, and backup flows more resilient after gateway drift.
- NemoClaw no longer writes proxy hooks into sandbox shell startup files. Local proxy configuration stays on supported OpenShell and NemoClaw paths rather than mutating user shell rc files.
- Windows bootstrap installs Ubuntu 24.04 when WSL is present but no Ubuntu distribution is registered.
## v0.0.49
NemoClaw v0.0.49 is a hardening release focused on reliability, clearer diagnostics, OpenClaw compatibility, and stronger validation coverage:
- Gateway failures now fail faster and explain more. `nemoclaw status` classifies gateway probe failures by layer, distinguishing a named gateway port that is not accepting connections, a named gateway that is present but not Connected, the active OpenShell gateway pointing at a different name, and a named gateway that is not configured at all. `nemoclaw <name> connect` exits early with recovery guidance when the OpenShell gateway is down.
- Gateway upgrade and fallback paths are more stable. The release hardens older gateway fallback coverage, OpenShell gateway upgrade checks, crash-loop detection tests, and Brev GPU bridge gateway traffic coverage.
- Status and doctor now report a fresh mutable sandbox as not configured instead of `down`, and `nemoclaw <name> logs --tail <lines>` is locked in as a NemoClaw line count rather than OpenShell's follow-flag pun. `nemoclaw debug --quick` reports restricted kernel-log access as a skipped section instead of surfacing raw `dmesg` permission errors.
- OpenClaw compatibility is more resilient across runtime changes. Kimi mixed tool calls are normalized more consistently, compatible OpenClaw JSON envelope changes are tolerated in tests, and OpenClaw patch drift is easier to classify during image builds.
- Messaging channel removal is now a clean teardown. The sandbox registry and onboard session policy preset state stay in sync so removed presets do not return during later `onboard --resume` or rebuild flows; QR-paired channels also have their durable in-sandbox session directory wiped before the rebuild and removal aborts cleanly when that wipe cannot be confirmed; and `~/.nemoclaw/config.json` is re-synced from the host across every rebuild resume path so the OpenClaw plugin no longer crashes on the Dockerfile placeholder.
- Hermes sandboxes apply only the messaging channel policies the operator selects instead of pre-enabling every Hermes messaging provider, and dynamic preset application resolves Hermes-specific policy content so Discord on Hermes no longer falls back to generic Node allowlists.
- `nemoclaw <name> snapshot restore --to <existing-sandbox>` now refuses to overwrite an existing destination unless you pass `--force`, which makes destructive clone restores an explicit opt-in.
- Source-checkout installs bootstrap OpenShell when needed before running preflight, so `git clone` based installs can reach the same managed OpenShell setup path as packaged installs. The Linux installer, onboard preflight, and prerequisites docs also explain why NemoClaw needs Docker group membership and the privilege impact of granting it.
- NVIDIA NIM preflight rejects WDDM placeholder GPU names on hosts without NVIDIA firmware, and Jetson onboarding refuses sandbox GPU passthrough instead of creating a configuration the sandbox cannot use.
- CLI and E2E coverage cover more real user paths. Missing `channels` arguments now print the correct usage, scenario suites use supported sandbox subcommands, scenario tests build against the full repository CLI, and security-sensitive credential paths have broader coverage.
- Release infrastructure now targets Node 24 in GitHub Actions. The E2E advisor also comments with clearer scenario guidance and waits for required PR checks before deciding.
## v0.0.48
NemoClaw v0.0.48 improves onboarding, sandbox builds, local inference, messaging, and day-two sandbox operations:
- Windows WSL onboarding detects Windows-host Ollama through both the HTTP endpoint and a Windows process probe, so the installer can offer start or restart actions even when the daemon is installed but not yet reachable from WSL.
- Onboarding no longer prints a noisy `No active forward found` warning when it performs best-effort dashboard forward cleanup before rebuilding or recovering a sandbox.
- `nemoclaw <name> share mount` verifies the requested remote path against the target sandbox name, so probes for non-default sandboxes no longer accidentally inspect the default sandbox.
- The OpenClaw plugin tolerates an empty or malformed onboard `config.json` by falling back to default onboard status instead of failing during startup.
- Hermes messaging policies are scoped to Hermes-supported channel behavior, keeping unsupported OpenClaw-specific messaging access out of Hermes sandboxes.
- Onboard session snapshots persist machine-readable state for resume flows, which makes provider and policy decisions more durable across retries.
- DGX Spark GPU sandbox recreation restores the startup path for Hermes by patching Docker GPU state and preserving the marker files the Hermes entrypoint needs.
- Discord messaging routes REST and gateway traffic through the sandbox proxy path, including a loopback proxy for gateway traffic, so Discord channels work through the same policy-controlled egress model as other sandbox traffic.
- Sandbox base images now include Homebrew and a `python` to `python3` compatibility symlink, reducing first-run setup for package and script workflows inside the sandbox.
- The NemoClaw sandbox image includes a Docker health check so container runtimes can report whether the in-sandbox gateway is responding.
- Sandbox startup resolves workspace template files from the installed package when source-relative files are not available, which helps package installs seed a fresh workspace consistently.
- Installer checksum verification prefers `sha256sum` and falls back when needed, improving compatibility on Linux hosts where `shasum` is not installed.
- VM-driver snapshot health checks now use gateway metadata instead of stale local assumptions, so snapshot operations fail less often after gateway state changes.
## v0.0.47
NemoClaw v0.0.47 focused on release hardening and validation coverage:
- The Vitest E2E fixture layer gained baseline onboarding coverage for CLI setup, OpenShell gateway creation, sandbox state, inference routing, and smoke tests.
- Messaging provider scenarios now validate provider attachment, placeholder configuration, secret-leak prevention, bridge reachability, Discord gateway routing, Slack provider state, Telegram injection safety, and token-rotation isolation.
- CLI command registration was refactored so public display defaults stay consistent across sandbox channel, host, log, policy, skill, and snapshot commands.
- PR review advisor automation was added for maintainers, with deterministic GitHub context gathering and structured review comments.
- The release refreshed v0.0.46 documentation, generated user skills, navigation, and version metadata.
## v0.0.46
NemoClaw v0.0.46 improves Windows setup, messaging channels, Hermes sandboxes, inference routing, and command compatibility:
- Windows users can start from the bootstrap PowerShell script, and WSL installs can accept express install to use the Windows-host Ollama path automatically.
- Messaging channels add WhatsApp support. `channels add whatsapp` records the channel, rebuilds the sandbox, and then pairs through the agent-specific QR command inside the sandbox.
- `nemoclaw <name> exec` runs non-interactive commands inside a running sandbox through OpenShell and exits with the remote command's status.
- Hermes sandboxes can use the managed tool gateway broker for supported tool routes, and Hermes startup recovers its readiness marker more reliably.
- Compatible Anthropic endpoint setup auto-detects Amazon Bedrock Runtime endpoints and starts the local adapter needed for OpenShell routing.
- Local Ollama setup on WSL native Docker now routes through NemoClaw's authenticated proxy, and subprocesses inherit the proxy bypass settings used by onboarding.
- Model Router setup probes supported host Python interpreters and falls back to the next usable one when virtual environment creation fails.
- The NemoClaw OpenClaw plugin registers the `/nemoclaw` command again after package metadata changes, and sandbox extension backups restore compatibility with current snapshots.
- Sandbox builds patch OpenClaw's tool catalog to reduce startup latency for Nemotron-focused sandboxes.
- `nemoclaw uninstall` docs now show how to pass flags through the hosted install script form.
## v0.0.45
NemoClaw v0.0.45 improves onboarding recovery, local inference behavior, channel cleanup, sandbox sharing diagnostics, and uninstall cleanup:
- `nemoclaw onboard` handles GPU setup failures more directly. It can replace a stale CPU-only gateway when doing so is safe, skips GPU advice when you explicitly pass `--no-gpu`, points working-driver hosts toward NVIDIA Container Toolkit setup, and enforces the 63-character sandbox name limit before names reach OpenShell.
- Preflight checks catch more host setup issues before the sandbox build starts. Container DNS probing uses a fresh `.invalid` lookup so cached DNS answers do not hide blocked resolver egress, and restrictive checkout file modes no longer make model-specific setup manifests unreadable inside the image.
- Local inference setup is more predictable. Managed vLLM accepts `NEMOCLAW_VLLM_MODEL` for supported registry slugs and checks Hugging Face tokens before pulling gated models. Ollama-backed sandboxes now enable streamed usage accounting so OpenClaw token counters update after each turn.
- Messaging channel removal is a clean inverse of channel add. `nemoclaw <name> channels remove <channel>` detaches live bridge providers before deleting them and un-applies the matching built-in network policy preset when it was active.
- `nemoclaw <name> share mount` fails earlier with clearer guidance when the sandbox path cannot be verified or the host mount target is on a read-only filesystem.
- `nemoclaw uninstall` stops host `openshell-gateway` processes, and subprocesses add IPv6 loopback plus wildcard local bind addresses to `NO_PROXY` so local traffic stays off forwarded proxies.
- Diagnostics and internal command output redact more credential-shaped values and use private temporary directories for generated SSH and config files.
## v0.0.44
NemoClaw v0.0.44 improves onboarding reliability, GPU sandbox networking, local inference verification, messaging recovery, and remote dashboard access:
- `nemoclaw onboard` handles DGX Spark and Jetson hosts more conservatively. Unified-memory GPU detection works for Spark, Jetson defaults to CPU-only sandbox passthrough unless you opt in, and local Ollama validation tolerates slow unified-memory model loads that still fit host memory.
- Linux Docker-driver GPU sandboxes preserve `host.openshell.internal` during recreation and inject a reachable DNS resolver when the host uses a systemd-resolved loopback nameserver, which keeps local inference and external DNS working after GPU patching.
- Onboarding and sandbox builds fail less often on first run. Preflight can guide missing NVIDIA Container Toolkit setup, Docker builds force BuildKit for Dockerfile bind mounts, npm installs retry transient registry resets, and compatible-endpoint onboarding runs a final inference smoke check before reporting success.
- `nemoclaw <name> connect` repairs stale `inference.local` routes before opening the shell, reports local Ollama backend and auth-proxy diagnostics when repair fails, and `--probe-only` keeps dashboard and process recovery from failing just because inference repair needs follow-up.
- `nemoclaw <name> channels add <channel>` applies the matching built-in network policy preset before rebuild, and rebuilds preserve paused channel state so stopped messaging channels stay disabled after destroy and recreate.
- Remote hosts can opt into dashboard forwarding on all interfaces with `NEMOCLAW_DASHBOARD_BIND=0.0.0.0`, and gateway drift checks now stop backup, status, rebuild, recover, and upgrade flows before they trust stale OpenShell state.
- Workspace restore uploads backed-up directories file by file, dashboard forwards retry while stopped ports are still releasing, and the in-sandbox OpenClaw gateway respawns after unexpected exits.
## v0.0.43
NemoClaw v0.0.43 improves GPU onboarding and uninstall cleanup on Linux Docker-driver hosts:
- The standard installer can repair missing NVIDIA CDI device specs before onboarding by enabling the NVIDIA CDI refresh service, then falling back to direct `nvidia-ctk` spec generation when needed.
- Linux Docker-driver GPU onboarding handles the Docker flags and sandbox policy needed for NVIDIA GPU proof writes to `/proc/<pid>/task/<tid>/comm`, which fixes DGX Spark installs that previously failed with a permission error during direct GPU proof.
- `nemoclaw uninstall` removes the Linux gateway state directory under `~/.local/state/nemoclaw`, including gateway PID, SQLite, audit log, and VM-driver state left by Docker-driver gateways.
## v0.0.42
NemoClaw v0.0.42 improves onboarding, status diagnostics, local inference checks, and messaging setup:
- `nemoclaw onboard` uses the Docker-driver OpenShell gateway path on macOS and no longer requires VM driver helper assets for standard macOS onboarding.
- Dashboard port selection probes occupied ports more thoroughly, including root-owned listeners on macOS, and rolls back a newly-created sandbox if the dashboard forward cannot start after the image build.
- `nemoclaw status` shows `Inference` and `Connected` fields for each listed sandbox, and cloudflared service output now distinguishes stopped, invalid PID file, and stale PID states with a `nemoclaw tunnel start` recovery hint.
- Local Ollama status and doctor checks now probe the authenticated proxy in addition to the backend, so a broken proxy is reported separately from a healthy `127.0.0.1:11434` backend.
- Compatible OpenAI endpoint validation retries reasoning-only smoke responses with a larger output budget before classifying the setup as a model output budget problem instead of a route failure.
- `channels add` and `channels remove` normalize channel names before saving or rebuilding, and `channels add` hints when a matching built-in policy preset exists but is not applied yet.
- GPU recovery and uninstall output now use registry-aware recovery commands and clearer gateway removal wording.
- Onboarding applies selected built-in policy presets in a single policy update when possible, while preserving the final live policy and registry state.
- The installer handles unchanged user-local CLI shims idempotently, avoiding duplicate shim-creation messages during install-plus-verify flows.
## v0.0.41
NemoClaw v0.0.41 improves Docker-driver onboarding and release compatibility:
- `nemoclaw onboard` can pin fresh OpenShell installs to a published release that fits the blueprint's tested version range, while retaining the installer fallback when release metadata is unavailable.
- Docker-driver gateway startup verifies that sandbox containers can reach `host.openshell.internal` before reporting the gateway healthy, and Linux firewall failures include a targeted `ufw` remediation.
- Local Ollama setup probes sandbox-to-proxy reachability before it commits the inference route, so blocked `11435` traffic stops onboarding with a rerun-safe fix instead of leaving a broken route.
- Linux Docker-driver GPU onboarding can recreate the OpenShell-managed sandbox container with NVIDIA GPU access and leaves diagnostics plus cleanup guidance when GPU readiness fails.
- `nemoclaw uninstall` removes all installer-managed OpenShell helper binaries unless you pass `--keep-openshell`.
## v0.0.40
NemoClaw v0.0.40 improves onboarding reliability, local inference setup, and sandbox recovery:
- `nemoclaw onboard` uses the Docker-driver OpenShell gateway path on macOS with OpenShell 0.0.37, repairs incomplete Docker-driver installs before startup, and installs the platform-specific gateway asset it needs.
- The Docker-driver gateway startup check waits for the gateway port to accept TCP connections before it reports the gateway as healthy, and startup failures now include child process exit details.
- Local Ollama setup requires the authenticated reverse proxy token on every native Ollama API route, including `GET /api/tags`.
- The Linux Ollama install path preflights `zstd` before running the official installer and explains why each sudo-backed setup step needs elevated privileges.
- The onboarding provider menu offers an already-running local vLLM server directly when `localhost:8000` responds. Managed vLLM install and start options now appear by default on DGX Spark and DGX Station, while generic Linux NVIDIA GPU hosts remain behind the experimental opt-in.
- Policy tier defaults are filtered by active agent support, so presets such as Brave Search are not reapplied to agents that do not support that integration.
- `nemoclaw <name> connect` checks dashboard forward reachability with a TCP probe before it reports a forward as stale.
- Sandbox startup captures a known-good OpenClaw config baseline and restores it on restart if `/sandbox/.openclaw/openclaw.json` becomes empty.
- The NemoClaw OpenClaw plugin package declares compatibility metadata for OpenClaw package tooling.
## v0.0.39
NemoClaw v0.0.39 improves several day-two workflows:
- The installer checks Docker earlier on Linux, can install and start Docker when needed, and stops with `newgrp docker` guidance when the current shell has not picked up the `docker` group yet.
- DGX Spark and DGX Station users can accept an express install prompt that preselects the local inference path and suggested policy defaults.
- NemoClaw now creates GPU-capable OpenShell Docker sandboxes by default when an NVIDIA GPU is available, with explicit `--sandbox-gpu`, `--no-sandbox-gpu`, and `--sandbox-gpu-device` controls.
- `nemohermes` supports Hermes Provider onboarding and runtime model switches through `nemohermes inference set`.
- `nemoclaw <name> hosts-add`, `hosts-list`, and `hosts-remove` manage sandbox host aliases for LAN-only services.
- `nemoclaw update` checks and runs the maintained installer flow, while `nemoclaw upgrade-sandboxes` remains responsible for rebuilding existing sandboxes.
- `nemoclaw <name> destroy` preserves the shared gateway by default unless `--cleanup-gateway` is selected.
- `nemoclaw <name> connect` repairs stale `inference.local` DNS proxy routes before opening the session.
- Windows-host Ollama onboarding relaunches the daemon with the reachable binding after install or restart.
- Local NVIDIA NIM onboarding passes `NGC_API_KEY` or `NVIDIA_INFERENCE_API_KEY` into the managed container without putting the secret in process arguments, detects early container exits during health checks, and prints a per-GPU preflight breakdown on mixed-model hosts.
- The sandbox startup path strips additional Linux capabilities before and during privilege step-down.
- OpenClaw workspace template files are seeded when bootstrap is skipped and the workspace is still empty.
- Kimi K2.6 and related NVIDIA-hosted chat-completions paths include model-specific compatibility handling for reasoning output.
## v0.0.38
NemoClaw v0.0.38 improves several day-two workflows:
- `nemoclaw <name> status` shows the gateway's active policy version in the displayed policy YAML when OpenShell reports one.
- `nemoclaw uninstall` stops matching Local Ollama auth proxy processes before it removes `~/.nemoclaw`, which prevents stale listeners from blocking a later reinstall.
- Local Ollama onboarding validates structured chat-completions tool calls and rejects models that leak tool-call payloads as plain text.
- Blueprint policy additions under `components.policy.additions` are validated, merged into the live policy, applied through OpenShell, and recorded in run metadata.
- Rebuild backups tolerate partial archive output when usable data was produced, then report only the manifest-defined paths that could not be archived.
- NemoHermes uninstall output uses NemoHermes-specific help, progress, and completion text.
## v0.0.34
Starting with NemoClaw v0.0.34, the `curl -fsSL https://www.nvidia.com/nemoclaw.sh | bash` installer pipeline no longer auto-accepts the third-party software notice when stdin is piped and `/dev/tty` is unavailable (for example, deeply detached SSH sessions or some container shells).
In environments without a TTY, accept upfront in the pipe:
```bash
curl -fsSL https://www.nvidia.com/nemoclaw.sh | NEMOCLAW_ACCEPT_THIRD_PARTY_SOFTWARE=1 bash
```
Or pass the flag through to the installer:
```bash
curl -fsSL https://www.nvidia.com/nemoclaw.sh | bash -s -- --yes-i-accept-third-party-software
```
Or re-run from a terminal with a controlling TTY:
```bash
bash <(curl -fsSL https://www.nvidia.com/nemoclaw.sh)
```
The installer error message in v0.0.35+ surfaces all three invocations directly so users can copy-paste a recovery without leaving the terminal.
## Component Version Policy
NemoClaw pins the OpenClaw version inside the sandbox at build time via `OPENCLAW_VERSION` in the NemoClaw Dockerfiles.
The `min_openclaw_version` field in `nemoclaw-blueprint/blueprint.yaml` is the compatibility floor for direct blueprint consumers and may be lower than the NemoClaw runtime target.
Existing sandboxes do not auto-upgrade.
Run `nemoclaw <name> status` to see the OpenClaw version currently running in a sandbox, and `nemoclaw <name> rebuild` to pick up a newer pin from a NemoClaw upgrade.
See Checking the OpenClaw version (use the `nemoclaw-user-reference` skill) for the full policy.

15
.agents/skills/nemoclaw-user-reference/SKILL.md
View file

@ -1,15 +0,0 @@
---
name: "nemoclaw-user-reference"
description: "Describes the NemoClaw integration layer and blueprint architecture and how they orchestrate compatible agent sandboxes. Use when looking up architecture, agent integration, plugin structure, or blueprint design. Trigger keywords - nemoclaw architecture, nemoclaw agent architecture, nemoclaw plugin blueprint structure, nemoclaw vs openshell, which cli, nemoclaw cli, openshell cli, sandbox commands, nemoclaw cli commands, nemoclaw command reference, nemoclaw network policy, sandbox egress control operator approval, nemoclaw troubleshooting, nemoclaw debug sandbox issues."
license: "Apache-2.0"
---
# NemoClaw User Reference
## References
- **Load [references/architecture.md](references/architecture.md)** when looking up architecture, agent integration, plugin structure, or blueprint design. Describes the NemoClaw integration layer and blueprint architecture and how they orchestrate compatible agent sandboxes.
- **Load [references/cli-selection-guide.md](references/cli-selection-guide.md)** when user asks to decide whether to use `$$nemoclaw` or `openshell`. Explains when to use `$$nemoclaw` versus `openshell` for NemoClaw-managed sandboxes, including lifecycle, inference, policy, monitoring, file transfer, and gateway operations.
- **Load [references/commands.md](references/commands.md)** when looking up a specific `$$nemoclaw`, `nemohermes`, or `/nemoclaw` subcommand, flag, argument, or exit code. Includes the full CLI reference for standalone NemoClaw commands and agent-specific in-sandbox commands.
- **Load [references/network-policies.md](references/network-policies.md)** when looking up a specific default endpoint, filesystem path, or the runtime approval sequence NemoClaw applies on blocked requests. Covers the baseline network policy, filesystem rules, and operator approval flow.
- **Load [references/troubleshooting.md](references/troubleshooting.md)** when diagnosing a reported NemoClaw error, a failed onboard, or unexpected sandbox behavior. Lists fixes for common installation, onboarding, and runtime issues.

11
.agents/skills/nemoclaw-user-reference/evals/evals.json
View file

@ -1,11 +0,0 @@
[
{
"id": "docs-reference-architecture-001",
"question": "I'm using the architecture reference. Help me verify implementation and operations details so I can make changes or debug behavior from the right mental model.",
"expected_skill": "nemoclaw-user-reference",
"ground_truth": "A NemoClaw-specific answer that helps the user verify implementation and operations details and gives enough concrete guidance, decision criteria, verification steps, or risk framing to make changes or debug behavior from the right mental model.",
"expected_behavior": [
"Uses the expected_skill and does not make up answers if it cannot find the answer from the skill."
]
}
]

257
.agents/skills/nemoclaw-user-reference/references/architecture.md
View file

@ -1,257 +0,0 @@
# Architecture Details
NemoClaw combines a host CLI, an in-sandbox integration layer, and a versioned YAML blueprint that defines the sandbox image, policies, and inference profiles applied through OpenShell.
## System Overview
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, prepares agent-specific integration, 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<br/><small>NVIDIA Endpoints · OpenAI<br/>Anthropic · Ollama · vLLM · Model Router</small>"]:::external
MSGAPI["Messaging Platforms<br/><small>Telegram · Discord · Slack</small>"]:::external
INTERNET["Internet<br/><small>PyPI · npm · GitHub · APIs</small>"]:::external
end
subgraph HOST["Host Machine"]
subgraph NEMOCLAW["NemoClaw"]
direction TB
NCLI["CLI + Onboarding<br/><small>Guided setup · provider selection<br/>credential validation · deploy</small>"]:::nemoclaw
BP["Blueprint<br/><small>Hardened Dockerfile<br/>Network policies · Presets<br/>Security configuration</small>"]:::nemoclaw
MIGRATE["State Management<br/><small>Migration snapshots<br/>Credential stripping<br/>Integrity verification</small>"]:::nemoclaw
end
subgraph OPENSHELL["OpenShell"]
direction TB
GW["Gateway<br/><small>Credential store<br/>Inference proxy<br/>Policy engine<br/>Device auth</small>"]:::openshell
OSCLI["openshell CLI<br/><small>provider · sandbox<br/>gateway · policy</small>"]:::openshell
CHMSG["Channel messaging<br/><small>OpenShell-managed<br/>Telegram · Discord · Slack</small>"]:::openshell
subgraph SANDBOX["Sandbox Container 🔒"]
direction TB
AGENT["Compatible Agent<br/><small>OpenClaw, Hermes,<br/>or another supported runtime</small>"]:::agent
PLUG["NemoClaw Integration<br/><small>Managed configuration<br/>and runtime context</small>"]:::sandbox
end
end
end
USER -->|"nemoclaw onboard<br/>nemoclaw connect"| NCLI
USER -->|"Chat messages"| MSGAPI
NCLI -->|"Orchestrates"| OSCLI
BP -->|"Defines sandbox<br/>shape + policies"| SANDBOX
MIGRATE -->|"Safe state<br/>transfer"| SANDBOX
AGENT -->|"Inference requests<br/><small>no credentials</small>"| GW
GW -->|"Proxied with<br/>credential injected"| INFERENCE
MSGAPI -->|"Platform APIs"| CHMSG
CHMSG -->|"Deliver to agent"| AGENT
AGENT -.->|"Policy-gated"| INTERNET
GW -.->|"Enforced by<br/>gateway"| INTERNET
```
## Deployment Topology
The logical diagram above shows how components relate.
This section shows what actually runs where on the host.
NemoClaw's default Docker-driver topology does not place the sandbox in an embedded k3s cluster.
On Linux, NemoClaw configures and restarts the package-managed OpenShell gateway user service when it is installed, then creates the sandbox as a Docker container.
NemoClaw treats that service as authoritative only when `systemctl --user show openshell-gateway` reports a package/vendor unit path and an `openshell-gateway` `ExecStart`.
Per-user units, partial units, and user-manager or bus outages do not take over gateway ownership; NemoClaw falls back to the standalone gateway process used by earlier installs.
That compatibility fallback remains until supported upgrade paths no longer include pre-service OpenShell installs and the package-managed handoff has direct nightly coverage.
On Apple Silicon macOS, NemoClaw starts the OpenShell Docker-driver gateway and creates the sandbox as a Docker container.
In both Docker-driver modes, the sandbox is a Docker container, not a Kubernetes pod.
The in-container `/tmp/nemoclaw-gateway-local` marker is written only by the entrypoint path that actually launches `openclaw gateway run`;
NemoClaw does not treat sandbox environment hints such as `OPENSHELL_DRIVERS` as authoritative for dashboard-gateway ownership.
Legacy non-Docker-driver installs still use the k3s-based gateway path; the diagram below shows the standard Docker-driver topology.
```mermaid
graph TB
classDef host fill:#fff,stroke:#76b900,stroke-width:2px,color:#1a1a1a,font-weight:bold
classDef cli fill:#76b900,stroke:#5a8f00,color:#fff,stroke-width:2px,font-weight:bold
classDef docker fill:#2496ed,stroke:#1577c2,color:#fff,stroke-width:2px,font-weight:bold
classDef gateway fill:#1a1a1a,stroke:#1a1a1a,color:#fff,stroke-width:2px,font-weight:bold
classDef sandbox fill:#444,stroke:#76b900,color:#fff,stroke-width:2px
classDef external fill:#f5f5f5,stroke:#e0e0e0,color:#1a1a1a,stroke-width:1px
subgraph HOST["Host machine · Linux / Apple Silicon macOS / DGX Spark / DGX Station"]
direction TB
CLI["nemoclaw CLI<br/><small>bin/nemoclaw.js → dist/<br/>onboard · connect · status · logs</small>"]:::cli
GW["OpenShell gateway<br/><small>host process by default<br/>credential store · lifecycle · L7 proxy</small>"]:::gateway
subgraph DOCKER["Docker daemon"]
direction TB
SANDBOX["Sandbox container 🔒<br/><small>Landlock + seccomp + netns<br/>Compatible agent + NemoClaw integration</small>"]:::sandbox
end
end
INFER["Inference provider<br/><small>NVIDIA Endpoints · OpenAI<br/>Anthropic · Ollama · vLLM · Model Router</small>"]:::external
CLI -->|"openshell CLI<br/>(orchestrates)"| GW
GW -->|"creates/recreates<br/>Docker-driver sandbox"| SANDBOX
SANDBOX -->|"inference requests<br/><small>placeholder credentials</small>"| GW
GW -->|"egress with real credentials<br/>injected at the L7 proxy"| INFER
class HOST host
class DOCKER docker
class GW gateway
class SANDBOX sandbox
```
Layering from top to bottom:
| Layer | Runs as | Role |
|---|---|---|
| Host CLI | Host process (`nemoclaw` on Node.js) | Orchestrates OpenShell via `openshell` CLI calls. |
| OpenShell gateway | Host process by default; optional Linux compatibility container when the gateway binary needs a newer host ABI | Hosts the credential store, owns sandbox lifecycle coordination, and provides the L7 proxy. |
| Docker daemon | Host service | Runs the Docker-driver sandbox container and, on affected Linux hosts, the optional gateway compatibility container. |
| Sandbox container | Docker container | Runs the selected compatible agent and NemoClaw integration under Landlock + seccomp + netns. |
| OpenShell L7 proxy | Gateway process | Intercepts agent egress and rewrites `Authorization` headers (Bearer/Bot) and URL-path segments to inject the real credential at the network boundary. |
NemoClaw never gives the sandbox a raw provider key.
At onboard time it registers credentials with OpenShell's provider/placeholder system, and the L7 proxy substitutes the real value into outbound requests at egress.
The CLI helper `isInferenceRouteReady` (in `src/lib/onboard.ts`) is a host-side readiness check used by the resume flow to decide whether the active route already covers the chosen provider and model.
It is not a runtime component.
For the DGX Spark-specific variant of this topology (cgroup v2, aarch64, unified memory), refer to the [NVIDIA Spark playbook](https://build.nvidia.com/spark/nemoclaw).
## NemoClaw Agent Integration
NemoClaw integrates with each supported agent through a runtime layer that adapts the agent to OpenShell-managed providers, policies, and sandbox state.
The concrete files differ by agent because each runtime has its own plugin system, config format, state layout, and startup command.
| Agent | Integration files | Runtime behavior |
|---|---|---|
| OpenClaw | `nemoclaw/openclaw.plugin.json`, `nemoclaw/src/runtime-context.ts`, and the TypeScript package under `nemoclaw/src/` | Registers the `/nemoclaw` slash command, adds the NemoClaw inference provider, and injects sandbox and policy context into OpenClaw turns. |
| Hermes | `agents/hermes/manifest.yaml`, `agents/hermes/plugin/plugin.yaml`, `agents/hermes/generate-config.ts`, `agents/hermes/config/`, and `agents/hermes/start.sh` | Declares the Hermes agent contract, installs the NemoClaw Hermes plugin, writes `/sandbox/.hermes/config.yaml` and `/sandbox/.hermes/.env`, and launches `hermes gateway run` behind the OpenShell proxy. |
The OpenClaw integration is a thin TypeScript plugin that runs in-process with the OpenClaw gateway inside the sandbox.
Before an OpenClaw turn starts, the plugin prepends a short system-context block with the active sandbox name, sandbox phase, network policy summary, and filesystem policy summary.
This guidance stays out of the visible chat transcript.
When the policy or phase changes during a session, the plugin sends a smaller update block instead of repeating the full context.
The context tells the agent to try allowed network and filesystem operations before reporting them unavailable, and to distinguish policy denials from DNS, timeout, TLS, or filesystem errors.
The Hermes integration follows the generic agent-manifest path instead of the OpenClaw plugin package path.
The manifest declares Hermes' binary, health probe, config directory, state directories, messaging support, and OpenAI-compatible API endpoint.
The build-time config generator turns NemoClaw onboarding choices into Hermes YAML and environment files, and the Hermes plugin manifest exposes NemoClaw tools and an `on_session_start` hook.
## NemoClaw Blueprint
The blueprint is a versioned YAML package with its own release stream.
The runner resolves, verifies, and applies the blueprint through the OpenShell CLI.
The blueprint defines the sandbox shape, default policies, and inference profiles; the runner performs the OpenShell operations.
```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 for the OpenClaw profile
```
Hermes keeps its agent-owned image, plugin, config, entrypoint, and policy additions under `agents/hermes/`.
The default Hermes policy starts from `agents/hermes/policy-additions.yaml`.
The current blueprint runner implementation lives in the `nemoclaw/` TypeScript package:
```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 integration layer locates the blueprint artifact and checks the version against the OpenShell and agent runtime constraints in `blueprint.yaml`.
2. Verify. The integration layer 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
Normal NemoClaw onboarding builds from the
[`ghcr.io/nvidia/nemoclaw/sandbox-base`](https://github.com/NVIDIA/NemoClaw/pkgs/container/nemoclaw%2Fsandbox-base)
base image and layers the NemoClaw runtime Dockerfile on top. The direct blueprint
runner still carries a pinned OpenShell Community OpenClaw image for legacy
`openshell sandbox create --from` compatibility. Inside the sandbox:
- The selected compatible agent runs with the NemoClaw integration layer installed or generated for that agent.
- Inference calls are routed through OpenShell to the configured provider.
- Network egress is restricted by the baseline policy for the selected agent profile.
- Filesystem access is confined to `/sandbox` and `/tmp` for read-write access, with system paths read-only.
- NemoClaw injects sandbox and policy context into agent turns when the selected agent supports runtime context hooks, so the agent can attempt allowed actions and report policy blocks or infrastructure failures accurately.
- The image exposes a Docker health check that probes the in-sandbox gateway, so container runtimes can report whether the agent service is responding.
- The image includes common runtime compatibility helpers such as Homebrew and a `python` to `python3` symlink for tools that still invoke `python`.
## Inference Routing
Inference requests from the agent never leave the sandbox directly.
OpenShell intercepts them and routes to the configured provider:
```text
Compatible agent (sandbox) ──▶ OpenShell gateway ──▶ Provider endpoint
```
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/<agent>/` so fixes for each supported agent can be tested and reviewed independently.
Refer to Inference Options (use the `nemoclaw-user-configure-inference` skill) for provider configuration details.
## Provider Credential Storage
Provider credentials live in the OpenShell gateway store, not on the host filesystem.
NemoClaw never writes them to host disk; the OpenShell L7 proxy injects values at egress.
See Credential Storage (use the `nemoclaw-user-configure-security` skill) for the inspection, rotation, and migration flow.
## Host-Side State and Config
NemoClaw keeps non-secret operator-facing state on the host rather than inside the sandbox.
| Path | Purpose |
|---|---|
| `~/.nemoclaw/sandboxes.json` | Registered sandbox metadata, including the default sandbox selection. |
| `~/.openclaw/openclaw.json` | Host OpenClaw configuration that NemoClaw snapshots or restores during migration flows. |
The following environment variables configure optional services and local access.
| Variable | Purpose |
|---|---|
| `TELEGRAM_BOT_TOKEN` | Telegram bot token you provide before `nemoclaw onboard`. OpenShell stores it in a provider; the sandbox receives placeholders, not the raw secret. |
| `TELEGRAM_ALLOWED_IDS` | Comma-separated Telegram user or chat IDs for allowlists when onboarding applies channel restrictions. |
| `SLACK_BOT_TOKEN` | Slack bot token (`xoxb-...`) you provide before `nemoclaw onboard`. Stored as an OpenShell provider; never passed directly to the sandbox. |
| `SLACK_APP_TOKEN` | Slack app-level token (`xapp-...`) required for Socket Mode. Stored alongside `SLACK_BOT_TOKEN` during onboarding. |
| `SLACK_ALLOWED_USERS` | Comma-separated Slack member IDs for DM and channel `@mention` user allowlisting. |
| `SLACK_ALLOWED_CHANNELS` | Comma-separated Slack channel IDs where channel `@mention` events are enabled (e.g. `C012AB3CD,C987ZY6XW`). Baked into the sandbox image at build time. Combine with `SLACK_ALLOWED_USERS` to restrict both channel and member. |
| `CHAT_UI_URL` | URL for the optional chat UI endpoint. |
| `NEMOCLAW_DISABLE_DEVICE_AUTH` | Build-time-only toggle that disables gateway device pairing when set to `1` before the sandbox image is created. |
For normal setup and reconfiguration, prefer `nemoclaw onboard` over editing these files by hand.
Do not treat `NEMOCLAW_DISABLE_DEVICE_AUTH` as a runtime setting for an already-created sandbox.

211
.agents/skills/nemoclaw-user-reference/references/cli-selection-guide.md
View file

@ -1,211 +0,0 @@
# Choose Between NemoClaw and OpenShell CLIs
NemoClaw uses two host-side CLIs.
Use `nemoclaw` for NemoClaw-managed workflows.
Use `openshell` when you need a lower-level OpenShell operation that NemoClaw intentionally exposes.
## Rule of Thumb
If the task changes how NemoClaw creates, rebuilds, preserves, or configures a sandbox, start with `nemoclaw`.
If the task inspects or changes the live OpenShell gateway, TUI, raw policy, port forwarding, inference route, or sandbox file transfer, use `openshell`.
Do not create or recreate NemoClaw-managed sandboxes directly with `openshell sandbox create` unless you intend to manage OpenShell yourself.
Run `nemoclaw onboard` afterward if you need to return to a NemoClaw-managed environment.
## Use `nemoclaw` For NemoClaw Workflows
Use `nemoclaw` for operations where NemoClaw adds product-specific state, safety checks, backup behavior, credential handling, or OpenClaw configuration.
- Install, onboard, or recreate a NemoClaw sandbox:
```bash
nemoclaw onboard
nemoclaw onboard --resume --recreate-sandbox
```
- List, connect to, check, or delete NemoClaw-managed sandboxes:
```bash
nemoclaw list
nemoclaw my-assistant connect
nemoclaw my-assistant status
nemoclaw my-assistant logs --follow
nemoclaw my-assistant destroy
```
- Rebuild or upgrade while preserving workspace state:
```bash
nemoclaw my-assistant rebuild
nemoclaw upgrade-sandboxes --check
```
- Snapshot, restore, or mount sandbox state:
```bash
nemoclaw my-assistant snapshot create --name before-change
nemoclaw my-assistant snapshot restore before-change
nemoclaw my-assistant share mount
```
- Add or remove NemoClaw policy presets:
```bash
nemoclaw my-assistant policy-add pypi --yes
nemoclaw my-assistant policy-list
nemoclaw my-assistant policy-remove pypi --yes
```
- Manage NemoClaw messaging channels, credentials, diagnostics, and cleanup:
```bash
nemoclaw my-assistant channels add slack
nemoclaw credentials list
nemoclaw credentials reset nvidia-prod
nemoclaw debug --sandbox my-assistant
nemoclaw gc --dry-run
```
## Use `openshell` For OpenShell Operations
Use `openshell` when the docs explicitly call for a live OpenShell gateway operation or when you need a lower-level view beneath the NemoClaw wrapper.
- Open the OpenShell TUI for network approvals and live activity:
```bash
openshell term
```
- Manage dashboard or service port forwards:
```bash
openshell forward start --background <port> <sandbox-name>
openshell forward list
```
- Inspect the underlying sandbox state:
```bash
openshell sandbox list
openshell sandbox get <sandbox-name>
openshell logs <sandbox-name> -n 20
openshell doctor check
```
- Move files, or run raw one-off commands when you intentionally want to bypass NemoClaw's sandbox registry and wrappers:
```bash
openshell sandbox upload <sandbox-name> ./local-file /sandbox/
openshell sandbox download <sandbox-name> /sandbox/output ./output
openshell sandbox exec -n <sandbox-name> -- env | grep '^HOME='
```
- Inspect or replace raw OpenShell policy:
```bash
openshell policy get --full <sandbox-name> > live-policy.yaml
openshell policy update <sandbox-name> --add-endpoint api.example.com:443:read-only:rest:enforce
openshell policy set --policy live-policy.yaml <sandbox-name>
```
`openshell policy update` merges specific endpoint and rule changes into the live sandbox policy.
`openshell policy set` replaces the live policy with the file you provide.
For normal NemoClaw network access changes, prefer `nemoclaw <name> policy-add` so NemoClaw preserves presets and records the change for rebuilds.
## Common Decisions
This section covers common decisions when using the NemoClaw CLI and the OpenShell CLI.
### First Setup or Full Recreate
Use `nemoclaw onboard`.
It starts the OpenShell gateway when needed, registers providers, builds the OpenClaw sandbox image, applies NemoClaw policy choices, and creates the sandbox.
Avoid running `openshell gateway start --recreate` or `openshell sandbox create` directly for NemoClaw-managed sandboxes.
Those commands do not update NemoClaw's registry, session metadata, workspace-preservation flow, or OpenClaw-specific configuration.
### Connect to the Sandbox
Use `nemoclaw <name> connect` for an interactive NemoClaw sandbox shell.
It waits for readiness, handles stale SSH host keys after gateway restarts, and prints agent-specific hints.
Use `openshell sandbox connect <name>` only when you intentionally want the raw OpenShell connection path.
For a one-off command in a NemoClaw-managed sandbox, use `nemoclaw <name> exec` instead of opening an interactive shell.
It resolves the sandbox by its NemoClaw registry name and runs through the standard NemoClaw CLI surface.
The command executes as the sandbox user with `HOME=/sandbox` inside the provisioned sandbox, where the agent configuration, inference routing, and policy state are already in place.
```bash
nemoclaw my-assistant exec -- cat /tmp/gateway.log
```
Use `openshell sandbox exec` for the raw OpenShell execution path, for example when addressing a sandbox by its gateway name or intentionally bypassing the NemoClaw CLI and registry.
```bash
openshell sandbox exec -n my-assistant -- cat /tmp/gateway.log
```
### Check Health or Logs
Use `nemoclaw <name> status` and `nemoclaw <name> logs` first.
They combine NemoClaw registry data, OpenShell state, OpenClaw process health, inference health, policy details, and messaging-channel warnings.
Use `openshell sandbox list`, `openshell sandbox get`, `openshell logs <name> -n 20`, or `openshell doctor check` when debugging lower-level OpenShell behavior.
When using `openshell logs` directly, `-n <lines>` controls the line count; use `--tail` only when you want live OpenShell log streaming.
### Approve Blocked Network Requests
Use `openshell term`.
The OpenShell TUI owns live network activity and operator approval prompts.
Approved endpoints are session-scoped unless you also add them to the policy through a NemoClaw preset or raw OpenShell policy update.
### Change Models or Providers
Use the NemoClaw commands for model or provider inspection and switches so the OpenShell route and the running agent config stay consistent:
```bash
nemoclaw inference get
nemoclaw inference set --provider nvidia-prod --model nvidia/nemotron-3-super-120b-a12b
```
For Hermes sandboxes, use the alias; it updates the route and `/sandbox/.hermes/config.yaml` without a rebuild or restart:
```bash
nemohermes inference set --provider hermes-provider --model openai/gpt-5.4-mini
```
For a build-time agent setting change, rerun onboarding so the sandbox configuration is recreated consistently:
```bash
nemoclaw onboard --resume --recreate-sandbox
```
Verify either path with:
```bash
nemoclaw <name> status
```
### Update Network Policy
Use `nemoclaw <name> policy-add` or `policy-remove` for NemoClaw presets and custom preset files.
NemoClaw merges the new policy with the live policy and reapplies presets during rebuilds.
Use `openshell policy update` for precise live endpoint or REST rule changes.
Use `openshell policy get --full` and `openshell policy set` only when you need to edit and replace the raw policy file.
### Move Workspace Files
Use `nemoclaw <name> snapshot create`, `snapshot restore`, or `share mount` for normal workspace preservation and editing.
Use `openshell sandbox upload` and `openshell sandbox download` for manual file copies when you need exact control over source and destination paths.
## Related Topics
- [Commands](commands.md) for the full NemoClaw command reference.
- Manage Sandbox Lifecycle (use the `nemoclaw-user-manage-sandboxes` skill) for day-two operations.
- Switch Inference Models (use the `nemoclaw-user-configure-inference` skill) for inference route examples.
- Customize the Network Policy (use the `nemoclaw-user-manage-policy` skill) for persistent network access changes.
- Approve or Deny Network Requests (use the `nemoclaw-user-manage-policy` skill) for the OpenShell TUI approval flow.

2275
.agents/skills/nemoclaw-user-reference/references/commands.md
View file

File diff suppressed because it is too large Load diff

133
.agents/skills/nemoclaw-user-reference/references/network-policies.md
View file

@ -1,133 +0,0 @@
# 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`.
**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 |
|---|---|
| `/sandbox`, `/tmp`, `/dev/null`, `/dev/pts` | Read-write |
| `/usr`, `/lib`, `/proc`, `/dev/urandom`, `/app`, `/etc`, `/var/log` | Read-only |
`/dev/pts` is the pseudo-terminal (devpts) directory.
It is writable so PTY-based tools (`tmux`, `script`, and interactive shells) can allocate a terminal.
Without it, those tools fail with `fork failed: Permission denied`.
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:
| Policy | Endpoints | Binaries | Rules |
| --- | --- | --- | --- |
| `nvidia` | `integrate.api.nvidia.com:443` | `/usr/local/bin/openclaw` | POST to inference and embedding paths, GET to model listings |
| `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` only (openclaw plugins install) | GET only |
All endpoints use TLS termination and are enforced at port 443.
**Note:**
GitHub access (`github.com`, `api.github.com`) is not included in the baseline policy.
Apply the `github` preset during onboarding if your agent needs GitHub access.
See Customize the Network Policy (use the `nemoclaw-user-manage-policy` skill).
The baseline policy does not include messaging endpoints for Telegram, Discord, Slack, WeChat, or WhatsApp.
Enable the channel during onboarding or apply the matching messaging preset so the sandbox can reach that platform.
WeChat and WhatsApp are experimental.
Review Messaging Channels (use the `nemoclaw-user-manage-sandboxes` skill) before enabling them.
<a id="policy-tiers"></a>
## Policy Tiers
During onboarding, the wizard prompts for a policy tier that determines the default set of presets applied on top of the baseline policy.
The baseline policy is always applied regardless of the selected tier.
| Tier | Presets included | Description |
|------|------------------|-------------|
| Restricted | None | Base sandbox only. No third-party network access beyond inference and core agent tooling. |
| Balanced (default) | `npm`, `pypi`, `huggingface`, `brew`, `brave when supported`, `weather` | Full dev tooling, read-only weather lookups, and web search for agents that support web search. No messaging platform access. |
| Open | `npm`, `pypi`, `huggingface`, `brew`, `brave when supported`, `weather`, `public-reference`, `slack`, `discord`, `telegram`, `wechat` (experimental), `whatsapp` (experimental), `jira`, `outlook` | Broad access across third-party services including messaging, productivity, weather, and public-reference APIs. |
After selecting a tier, a combined preset and access-mode screen lets you include or exclude individual presets and toggle each between read (GET only) and read-write (GET + POST/PUT/PATCH) access.
Tier-default presets are pre-selected; additional presets can be added from the full list.
NemoClaw filters tier defaults by the active agent's supported integrations.
For example, Hermes onboarding omits the Brave Search preset because Hermes does not use NemoClaw's OpenClaw web-search configuration.
Hermes managed-tool gateway selections can add Hermes-specific presets, such as Nous-hosted web, image, audio, browser, or code tools, without applying unsupported OpenClaw-only presets.
Claude Code direct egress is not included in any policy tier.
If you install and run the Claude Code CLI inside the sandbox with its own credentials, apply the `claude-code` preset explicitly.
Normal NemoClaw Anthropic inference still routes through the OpenShell gateway.
Tier definitions are stored in `nemoclaw-blueprint/policies/tiers.yaml`.
In non-interactive mode, set the tier with `NEMOCLAW_POLICY_TIER`:
```bash
NEMOCLAW_POLICY_TIER=open nemoclaw onboard --non-interactive --yes-i-accept-third-party-software
```
Unset, blank, or whitespace-only `NEMOCLAW_POLICY_TIER` values use the `balanced` default.
In non-interactive onboarding, a non-blank value that does not match a known tier exits before preflight, gateway, or inference side effects and lists the valid options.
Interactive onboarding ignores an invalid environment value and shows the normal tier prompt.
### 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:
```bash
./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:
```bash
nemoclaw onboard
```
### Dynamic Changes
Apply policy updates to a running sandbox without restarting:
```bash
openshell policy update <sandbox-name> --add-endpoint api.example.com:443:read-only:rest:enforce
```
To replace the live policy with a complete raw policy file, use `openshell policy set`:
```bash
openshell policy set --policy <policy-file> <sandbox-name>
```

1721
.agents/skills/nemoclaw-user-reference/references/troubleshooting.md
View file

File diff suppressed because it is too large Load diff

4
.github/ISSUE_TEMPLATE/bug_report.yml vendored
View file

@ -8,7 +8,7 @@ body:
value: |
## Agent-First Troubleshooting
NemoClaw is an agent-first project. Before filing this bug, point your coding agent at the repo and have it investigate using the available skills (`nemoclaw-skills-guide`, `nemoclaw-user-monitor-sandbox`, `nemoclaw-user-manage-sandboxes`, etc.). See [CONTRIBUTING.md](https://github.com/NVIDIA/NemoClaw/blob/main/CONTRIBUTING.md) for issue expectations.
NemoClaw is an agent-first project. Before filing this bug, point your coding agent at the repo and have it investigate using the available skills (`nemoclaw-skills-guide`, `nemoclaw-user-guide`, etc.). See [CONTRIBUTING.md](https://github.com/NVIDIA/NemoClaw/blob/main/CONTRIBUTING.md) for issue expectations.
- type: textarea
id: agent-diagnostic
@ -18,7 +18,7 @@ body:
Paste the output from your agent's investigation of this bug. What skills did it load? What did it find? What did it try?
placeholder: |
Example:
- Loaded `nemoclaw-user-monitor-sandbox`
- Loaded `nemoclaw-user-guide`
- Ran `nemoclaw status`, `nemoclaw list`, and `nemoclaw debug --quick`
- Found the sandbox is registered but not ready after onboarding
- Tried `nemoclaw debug --output /tmp/nemoclaw-debug.tar.gz`; the attached bundle still shows the failure

2
.github/actions/ci-static-checks/action.yaml vendored
View file

@ -55,7 +55,7 @@ runs:
shell: bash
run: npm run test-size:check
- name: Run skills YAML tests
- name: Run skill frontmatter tests
shell: bash
run: npx vitest run test/skills-frontmatter.test.ts

47
.github/catalog-skills-signing-flow.md vendored
View file

@ -5,47 +5,50 @@
The `skills/` directory at the repo root is the NVSkills CI watched location.
Whatever lives there is what gets signed and published. There is no
allowlist, manifest, or generator script — adding a skill to the catalog
means copying the source skill into `skills/` and pushing it through
NVSkills CI signing.
allowlist, manifest, or generator script.
NemoClaw hard-copies customer-facing source skills into `skills/` so NVSkills CI
can read the catalog path directly.
NemoClaw currently maintains one customer-facing skill, `nemoclaw-user-guide`.
That skill is a small routing guide to the canonical Fern Markdown docs.
Do not publish copied documentation pages as generated `nemoclaw-user-*` skills.
## Add a skill to the catalog
```bash
mkdir -p skills
cp -R .agents/skills/nemoclaw-user-<name> skills/
git add skills/nemoclaw-user-<name>
git commit -m "chore(skills): publish nemoclaw-user-<name>"
rm -rf skills/nemoclaw-user-guide
cp -R .agents/skills/nemoclaw-user-guide skills/
git add skills/nemoclaw-user-guide
git commit -m "chore(skills): publish nemoclaw-user-guide"
```
Open the PR, comment `/nvskills-ci`, wait for the signing job to push back
`skill.oms.sig` and `skill-card.md`, then merge. Repeat per skill — NVSkills
CI signs one at a time.
`skill.oms.sig` and `skill-card.md`, then merge.
NVSkills CI signs one skill at a time.
## Update an already-published skill
```bash
rm -rf skills/nemoclaw-user-<name>
cp -R .agents/skills/nemoclaw-user-<name> skills/
git add -A skills/nemoclaw-user-<name>
git commit -m "chore(skills): refresh nemoclaw-user-<name>"
rm -rf skills/nemoclaw-user-guide
cp -R .agents/skills/nemoclaw-user-guide skills/
git add -A skills/nemoclaw-user-guide
git commit -m "chore(skills): refresh nemoclaw-user-guide"
```
The `skill.oms.sig` from the previous signing is removed by the `rm -rf`,
so NVSkills CI will re-sign on the next `/nvskills-ci` comment. Use
`git add -A` so newly added files in the refreshed skill are staged
Use `git add -A` so newly added files in the refreshed skill are staged
alongside removals tracked by `git commit -a`.
## Spot-checking for drift
Source (`/.agents/skills/`) and published (`/skills/`) can drift if a
source-side edit lands without a corresponding refresh PR. To check, ask
an agent to compare every subdirectory of `skills/` against its counterpart
under `.agents/skills/` and report any file content differences (ignoring
`skill.oms.sig` and `skill-card.md`).
Source (`/.agents/skills/nemoclaw-user-guide/`) and published
(`/skills/nemoclaw-user-guide/`) can drift if a source-side edit lands without a
corresponding refresh PR.
To check, ask an agent to compare the two directories before requesting signing.
## What goes in the catalog
Only customer-facing skills, identified by the `nemoclaw-user-*` naming
convention. Internal skills (`nemoclaw-maintainer-*`, `nemoclaw-contributor-*`)
must not be copied into `skills/`.
convention.
Internal skills (`nemoclaw-maintainer-*`, `nemoclaw-contributor-*`) must not be
copied into `skills/`.

14
.pre-commit-config.yaml
View file

@ -71,7 +71,7 @@ repos:
name: SPDX license headers (insert if missing)
entry: bash scripts/check-spdx-headers.sh --fix
language: system
files: ^(nemoclaw/src/.*\.ts|scripts/export-catalog-skills\.py|scripts/.*\.ts|nemoclaw-blueprint/.*\.py|.*\.sh)$
files: ^(nemoclaw/src/.*\.ts|scripts/.*\.ts|nemoclaw-blueprint/.*\.py|.*\.sh)$
exclude: ^nemoclaw-blueprint/.*__init__\.py$
pass_filenames: true
priority: 4
@ -203,16 +203,6 @@ repos:
- id: markdownlint-cli2
priority: 10
- repo: local
hooks:
- id: docs-to-skills-dry-run
name: Verify docs-to-skills output
entry: python3 scripts/docs-to-skills.py docs/ .agents/skills/ skills/ --prefix nemoclaw-user --doc-platform fern-mdx --dry-run
language: system
files: ^(docs/.*\.mdx?$|docs/conf\.py$|ci/platform-matrix\.json$|scripts/docs-to-skills\.py$|scripts/generate-platform-docs\.py$)
pass_filenames: false
priority: 10
# ── commit-msg hooks ────────────────────────────────────────────────────────
- repo: https://github.com/alessandrojcm/commitlint-pre-commit-hook
rev: v9.24.0
@ -320,7 +310,7 @@ repos:
entry: npx vitest run test/skills-frontmatter.test.ts
language: system
pass_filenames: false
files: ^(\.agents/skills/|docs/.*\.mdx?$|scripts/docs-to-skills\.py$|test/skills-frontmatter\.test\.js$)
files: ^(\.agents/skills/|skills/|test/skills-frontmatter\.test\.ts$)
priority: 20
default_language_version:

13
AGENTS.md
View file

@ -11,7 +11,9 @@ Status: Active development. 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.
This repo ships agent skills under `.agents/skills/`.
Use `nemoclaw-user-guide` for end-user documentation routing, `nemoclaw-contributor-*` for contributor workflows, and `nemoclaw-maintainer-*` for maintainer workflows.
Load the `nemoclaw-skills-guide` skill for a full catalog and quick decision guide mapping tasks to skills.
## Architecture
@ -28,7 +30,7 @@ This repo ships agent skills under `.agents/skills/`, organized into three audie
| `scripts/` | Bash/JS/TS | Install helpers, setup, automation, E2E tooling |
| `test/` | JavaScript (ESM) | Root-level integration tests (Vitest) |
| `test/e2e/` | Bash/JS/TS | End-to-end tests, scenario-based runner (see `test/e2e/README.md`) |
| `docs/` | MDX/Markdown | User-facing docs (Fern MDX plus legacy MyST source during migration) |
| `docs/` | MDX/Markdown | User-facing Fern docs and Markdown routes for AI documentation clients |
| `fern/` | YAML/CSS/SVG | Fern site configuration and shared assets |
Package-specific guides:
@ -57,7 +59,7 @@ Package-specific guides:
- **CLI and plugin**: TypeScript (`src/`, `nemoclaw/src/`) with a small CommonJS launcher in `bin/`; ESM in `test/`
- **Blueprint**: YAML configuration (`nemoclaw-blueprint/`)
- **Docs**: Fern MDX for migrated pages; legacy MyST Markdown remains during the transition for generated skills and parity checks
- **Docs**: Fern MDX for user-facing pages, with Markdown routes exposed by Fern for AI documentation clients
- **Tooling scripts**: Bash and Python
The `bin/` directory uses CommonJS intentionally for the launcher and a few compatibility helpers so the CLI still has a stable executable entry point. The main CLI implementation lives in `src/` and compiles to `dist/`. The `nemoclaw/` plugin uses TypeScript and requires compilation.
@ -201,8 +203,9 @@ Follow `.agents/skills/_shared/pr-follow-up.md`: after opening or pushing to a P
- Treat `docs/` as the source of truth for user-facing documentation and follow `docs/CONTRIBUTING.md`.
- After completing development changes, run a documentation writer subagent before final handoff. Give it the changed files, behavior summary, and test evidence so it can update docs or report that no doc changes are needed.
- For normal docs changes, include only source pages under `docs/`. Do not edit generated user skills under `.agents/skills/nemoclaw-user-*/`.
- During release prep, run `nemoclaw-contributor-update-docs`, make doc version bumps, regenerate user skills, and open the docs refresh PR with both docs and generated user skills.
- For normal docs changes, include source pages under `docs/`.
- Update `.agents/skills/nemoclaw-user-guide/SKILL.md` only when the AI-agent docs routing guidance changes.
- During release prep, run `nemoclaw-contributor-update-docs`, make doc version bumps, and open the docs refresh PR with the docs changes.
## PR Requirements

8
CONTRIBUTING.md
View file

@ -134,7 +134,7 @@ All git hooks are managed by [prek](https://prek.j178.dev/), a fast, single-bina
| Hook | What runs |
|------|-----------|
| **pre-commit** | File fixers, formatters, linters, docs-to-skills dry-run validation, Vitest (plugin) |
| **pre-commit** | File fixers, formatters, linters, skill frontmatter validation, Vitest (plugin) |
| **commit-msg** | commitlint (Conventional Commits) |
| **pre-push** | TypeScript type check (`tsc --noEmit` for plugin, JS, and CLI) |
@ -192,7 +192,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 `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).
During release prep, run that skill first, make any doc version bumps, regenerate user skills, then open the docs refresh PR.
During release prep, run that skill first, make any doc version bumps, then open the docs refresh PR.
To build and preview docs locally:
@ -206,9 +206,9 @@ Use these npm scripts when validating docs for a PR.
See [docs/CONTRIBUTING.md](docs/CONTRIBUTING.md) for the full style guide and writing conventions.
### Doc-to-Skills Pipeline
### Markdown Docs for AI Agents
For user-skill definitions, docs-to-skills validation, release-prep regeneration, and script flags, see [Doc-to-Skills Pipeline](docs/CONTRIBUTING.md#doc-to-skills-pipeline).
For Markdown docs routing, user-skill guidance, and release-prep documentation workflow, see [Markdown Docs for AI Agents](docs/CONTRIBUTING.md#markdown-docs-for-ai-agents).
## Pull Requests

4
docs/AGENTS.md
View file

@ -4,7 +4,7 @@
# Documentation Agent Guide
You are a documentation engineer and writer for NemoClaw user-facing docs.
Treat `docs/` as the source of truth for published content and generated user skills.
Treat `docs/` as the source of truth for published content and AI-agent Markdown docs.
## Role
@ -19,7 +19,7 @@ Treat `docs/` as the source of truth for published content and generated user sk
- Check `docs/.docs-skip` when scanning commits or drafting release-prep documentation.
- Read the full target page before editing it.
- Map code changes to existing pages before proposing a new page.
- Never edit generated user skills under `.agents/skills/nemoclaw-user-*/`.
- Update `.agents/skills/nemoclaw-user-guide/SKILL.md` only when AI-agent docs routing guidance changes.
## Writing Rules

70
docs/CONTRIBUTING.md
View file

@ -25,42 +25,20 @@ 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 the changes I made in this PR".
During release prep, run the skill first, regenerate user skills, then open the docs refresh PR.
During release prep, run the skill first, make any doc version bumps, then open the docs refresh PR.
The skill lives in `.agents/skills/nemoclaw-contributor-update-docs/` and follows the style guide below automatically.
## Doc-to-Skills Pipeline
## Markdown Docs for AI Agents
User skills are generated agent-skill packages, prefixed with `nemoclaw-user-*`, that help AI agents guide end users through NemoClaw workflows.
The `docs/` directory is the source of truth for user-facing documentation.
The script `scripts/docs-to-skills.py` converts doc pages into user skills under `.agents/skills/`.
These generated skills identically cover the same tasks as the doc pages they were generated from, while reformatting the doc files to match the agent-skill specification in markdown and organizing sibling pages into progressive disclosure for reference files.
NemoClaw publishes Markdown versions of Fern pages plus `llms.txt`, so AI agents can fetch canonical documentation directly.
Always make doc updates in `docs/`.
Never edit generated skill files under `.agents/skills/nemoclaw-user-*/`. Your changes will be overwritten on the next run.
The hand-written `nemoclaw-user-guide` skill only routes agents to the right Markdown docs.
It must stay small and must not copy page content from `docs/`.
### Generated NemoClaw User Skills
The current generated skills and their source pages are:
| Skill | Source docs |
|---|---|
| `nemoclaw-user-overview` | `docs/about/overview.mdx`, `docs/about/ecosystem.mdx`, `docs/about/how-it-works.mdx`, `docs/about/release-notes.mdx` |
| `nemoclaw-user-agent-skills` | `docs/resources/agent-skills.mdx` |
| `nemoclaw-user-deploy-remote` | `docs/deployment/deploy-to-remote-gpu.mdx`, `docs/deployment/brev-web-ui.mdx`, `docs/deployment/install-openclaw-plugins.mdx`, `docs/deployment/sandbox-hardening.mdx` |
| `nemoclaw-user-get-started` | `docs/get-started/prerequisites.mdx`, `docs/get-started/quickstart.mdx`, `docs/get-started/quickstart-hermes.mdx`, `docs/get-started/windows-preparation.mdx` |
| `nemoclaw-user-configure-inference` | `docs/inference/inference-options.mdx`, `docs/inference/use-local-inference.mdx`, `docs/inference/switch-inference-providers.mdx`, `docs/inference/set-up-sub-agent.mdx`, `docs/inference/tool-calling-reliability.mdx` |
| `nemoclaw-user-manage-sandboxes` | `docs/manage-sandboxes/lifecycle.mdx`, `docs/manage-sandboxes/runtime-controls.mdx`, `docs/manage-sandboxes/messaging-channels.mdx`, `docs/manage-sandboxes/workspace-files.mdx`, `docs/manage-sandboxes/backup-restore.mdx` |
| `nemoclaw-user-monitor-sandbox` | `docs/monitoring/monitor-sandbox-activity.mdx` |
| `nemoclaw-user-manage-policy` | `docs/network-policy/customize-network-policy.mdx`, `docs/network-policy/integration-policy-examples.mdx`, `docs/network-policy/approve-network-requests.mdx` |
| `nemoclaw-user-reference` | `docs/reference/architecture.mdx`, `docs/reference/commands.mdx`, `docs/reference/cli-selection-guide.mdx`, `docs/reference/network-policies.mdx`, `docs/reference/troubleshooting.mdx` |
| `nemoclaw-user-configure-security` | `docs/security/best-practices.mdx`, `docs/security/credential-storage.mdx`, `docs/security/openclaw-controls.mdx` |
### Regenerating NemoClaw User Skills after Doc Changes
Most contributor pull requests that change docs should include only the source pages under `docs/`.
Do not regenerate or commit generated `nemoclaw-user-*` skill output in contributor doc PRs.
NemoClaw maintainers refresh generated user skills during release prep.
Always make user-facing doc updates in `docs/`.
Update `docs/resources/agent-skills.mdx` and `.agents/skills/nemoclaw-user-guide/SKILL.md` only when the AI-agent routing guidance changes.
## Building Docs Locally
@ -96,7 +74,8 @@ npm run docs:preview:watch
The preview watcher uses the current Git branch name as the Fern preview ID and watches the `docs/` and `fern/` directories.
Fern `.mdx` pages are the source for generated user skills. Legacy `.md` pages may remain temporarily for parity checks, but release-prep skill generation should pass `--doc-platform fern-mdx`.
Fern `.mdx` pages are the canonical docs source.
Fern publishes Markdown routes for AI agents from the same source pages.
## Agent Variant Generation
@ -145,7 +124,7 @@ Run targeted tests only when the change also touches code, generated behavior, o
- Fern pages use MDX with YAML frontmatter. Use a flat `title`, `description`, optional `sidebar-title`, `description-agent`, `keywords`, and `position`.
- Do not duplicate the page title as a body H1 in MDX pages because Fern renders the title from frontmatter.
- The docs-to-skills pipeline treats Fern `description-agent` as the equivalent of legacy MyST `description.agent`.
- Use `description-agent` as a concise routing summary for AI documentation clients and search indexes.
- Include the SPDX license header in MDX frontmatter as comments:
```yaml
@ -173,35 +152,6 @@ position: 1
---
```
### Legacy Skill Frontmatter Template
Use this nested shape only for legacy `.md` pages when running the pipeline with `--doc-platform myst-md`.
```yaml
---
title:
page: "NemoClaw Page Title: Subtitle with Context"
nav: "Short Nav Title"
description:
main: "One-sentence summary for readers, SEO, and doc search snippets."
agent: "Third-person verb summary for agent routing. Add 'Use when...' with trigger phrases."
keywords: ["primary keyword", "secondary keyword phrase"]
topics: ["generative_ai", "ai_agents"]
tags: ["openclaw", "openshell", "relevant", "tags"]
content:
type: concept | how_to | get_started | tutorial | reference
difficulty: technical_beginner | technical_intermediate | technical_advanced
audience: ["developer", "engineer"]
skill:
priority: 100
status: published
---
```
Use `skill.priority` to choose the lead procedure page when multiple how-to pages generate the same skill.
Lower numbers win.
For example, set the OpenClaw quickstart to `10` and the Hermes quickstart to `20` so `nemoclaw-user-get-started/SKILL.md` leads with the OpenClaw procedure and folds Hermes into `references/`.
### Page Structure
1. Start MDX pages with a one- or two-sentence introduction stating what the page covers.

1
docs/_components/StarterPromptButton.tsx
View file

@ -45,7 +45,6 @@ After I choose, use the matching documentation variant. Do not mix OpenClaw-spec
Use these Markdown documentation pages as the first sources:
- Documentation index for AI clients: https://docs.nvidia.com/nemoclaw/llms.txt
- Full Markdown documentation bundle: https://docs.nvidia.com/nemoclaw/llms-full.txt
- OpenClaw home: https://docs.nvidia.com/nemoclaw/latest/user-guide/openclaw/home.md
- OpenClaw prerequisites: https://docs.nvidia.com/nemoclaw/latest/user-guide/openclaw/get-started/prerequisites.md
- OpenClaw quickstart: https://docs.nvidia.com/nemoclaw/latest/user-guide/openclaw/get-started/quickstart.md

6
docs/about/overview.mdx
View file

@ -35,7 +35,7 @@ NemoClaw provides the following product capabilities.
| Feature | Description |
|---------|-------------|
| Guided onboarding | Validates credentials, selects providers, and creates a working sandbox in one command. |
| Agent skills | Packages NemoClaw documentation as user skills so AI coding assistants can guide setup, inference configuration, policy management, monitoring, deployment, security review, and troubleshooting. |
| AI-agent docs | Publishes Markdown docs and a small routing skill so AI coding assistants can guide setup, inference configuration, policy management, monitoring, deployment, security review, and troubleshooting. |
| Hardened blueprint | A 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. |
| Messaging channels | OpenShell-managed processes connect Telegram, Discord, Slack, and similar platforms to the sandboxed agent. NemoClaw configures channels during onboarding; OpenShell supplies the native constructs, credential flow, and runtime supervision. |
@ -75,7 +75,7 @@ Navigate to the following topics to learn more about NemoClaw and how to install
- [Architecture Overview](how-it-works) to understand how NemoClaw works.
- [Ecosystem](ecosystem) to understand how your agent, OpenShell, and NemoClaw relate in the wider stack, and when to use NemoClaw versus OpenShell.
- [Quickstart with OpenClaw](../get-started/quickstart) to install NemoClaw and run your first OpenClaw sandbox.
- [Agent Skills](../resources/agent-skills) to load NemoClaw guidance into an AI coding assistant.
- [AI Agent Docs](../resources/agent-skills) to let your AI coding assistant fetch NemoClaw Markdown docs.
- [NemoClaw Community](https://github.com/NVIDIA/nemoclaw-community) to explore community-driven blueprint examples, showcases, and integrations.
- [Inference Options](../inference/inference-options) to check the inference providers that NemoClaw supports and how inference routing works.
@ -85,7 +85,7 @@ Navigate to the following topics to learn more about NemoClaw and how to install
- [Architecture Overview](how-it-works) to understand how NemoClaw works.
- [Ecosystem](ecosystem) to understand how Hermes, OpenShell, and NemoClaw relate in the wider stack, and when to use NemoClaw versus OpenShell.
- [Quickstart with Hermes](../get-started/quickstart) to install NemoClaw and run your first Hermes sandbox with `$$nemoclaw`.
- [Agent Skills](../resources/agent-skills) to load NemoClaw guidance into an AI coding assistant.
- [AI Agent Docs](../resources/agent-skills) to let your AI coding assistant fetch NemoClaw Markdown docs.
- [NemoClaw Community](https://github.com/NVIDIA/nemoclaw-community) to explore community-driven blueprint examples, showcases, and integrations.
- [Inference Options](../inference/inference-options) to check the inference providers that NemoClaw supports and how inference routing works.

2
docs/about/release-notes.mdx
View file

@ -261,7 +261,7 @@ NemoClaw v0.0.47 focused on release hardening and validation coverage:
- Messaging provider scenarios now validate provider attachment, placeholder configuration, secret-leak prevention, bridge reachability, Discord gateway routing, Slack provider state, Telegram injection safety, and token-rotation isolation.
- CLI command registration was refactored so public display defaults stay consistent across sandbox channel, host, log, policy, skill, and snapshot commands.
- PR review advisor automation was added for maintainers, with deterministic GitHub context gathering and structured review comments.
- The release refreshed v0.0.46 documentation, generated user skills, navigation, and version metadata.
- The release refreshed v0.0.46 documentation, AI-agent docs guidance, navigation, and version metadata.
## v0.0.46

2
docs/get-started/prerequisites.mdx
View file

@ -86,4 +86,4 @@ The table comes from [`ci/platform-matrix.json`](https://github.com/NVIDIA/NemoC
- [Prepare Windows for NemoClaw](prerequisites/windows-preparation) if you are using Windows.
- [Quickstart](quickstart) to install NemoClaw and launch your first sandboxed agent.
- [Agent Skills](../resources/agent-skills) to load NemoClaw guidance into an AI coding assistant before setup.
- [AI Agent Docs](../resources/agent-skills) to let your AI coding assistant fetch NemoClaw Markdown docs before setup.

10
docs/get-started/quickstart.mdx
View file

@ -17,10 +17,10 @@ Follow these steps to get started with NemoClaw and your first sandboxed OpenCla
Review the [Prerequisites](prerequisites) before following this guide.
</Note>
<Tip title="Use Agent Skills">
NemoClaw ships user skills for AI coding assistants.
Load them when you want your assistant to walk through installation, inference choices, policy approvals, monitoring, or troubleshooting with NemoClaw-specific guidance.
Refer to [Agent Skills](../resources/agent-skills).
<Tip title="Use AI Agent Docs">
NemoClaw publishes Markdown docs and a small docs-routing skill for AI coding assistants.
Use them when you want your assistant to walk through installation, inference choices, policy approvals, monitoring, or troubleshooting with NemoClaw-specific guidance.
Refer to [AI Agent Docs](../resources/agent-skills).
</Tip>
## Install NemoClaw and Onboard an OpenClaw Agent
@ -270,7 +270,7 @@ Navigate to the following topics to learn more about NemoClaw.
- [NemoClaw Overview](../about/overview) to learn what NemoClaw is and its capabilities.
- [Architecture Overview](../about/how-it-works) to understand how NemoClaw works.
- [Ecosystem](../about/ecosystem) to understand how OpenClaw, OpenShell, and NemoClaw relate in the wider stack, and when to use NemoClaw versus OpenShell.
- [Agent Skills](../resources/agent-skills) to load NemoClaw guidance into an AI coding assistant.
- [AI Agent Docs](../resources/agent-skills) to let your AI coding assistant fetch NemoClaw Markdown docs.
Use the following topics to learn how to use NemoClaw.

14
docs/index.mdx
View file

@ -3,8 +3,8 @@
# SPDX-License-Identifier: Apache-2.0
title: "NVIDIA NemoClaw"
sidebar-title: "Home"
description: "NemoClaw is an open-source reference stack for running sandboxed AI agents more safely, with a single command and packaged agent skills."
keywords: "NemoClaw, OpenClaw, Hermes, OpenShell, AI agents, agent skills, sandboxing, inference routing"
description: "NemoClaw is an open-source reference stack for running sandboxed AI agents more safely, with a single command and Markdown docs for AI assistants."
keywords: "NemoClaw, OpenClaw, Hermes, OpenShell, AI agents, Markdown docs, sandboxing, inference routing"
layout: overview
position: 1
---
@ -74,16 +74,16 @@ By default, NemoClaw installs the OpenClaw agent. Use one of the following quick
<section>
## NemoClaw User Skills
## NemoClaw Docs for AI Agents
Load NemoClaw's user skills for your AI coding agent before you install or operate a sandbox.
The skills turn these docs into task-focused guidance that your agent can apply to your local environment.
Use NemoClaw's Markdown docs or the docs-routing skill when you want your AI coding agent to help you install or operate a sandbox.
The assistant fetches the same canonical pages that power this site and applies them to your local environment.
<Cards>
<Card title="Set Up Agent Skills" href="resources/agent-skills">
<Card title="Use AI Agent Docs" href="resources/agent-skills">
Clone the skills or add them to your agent so NemoClaw guidance is available directly in chat.
Give your assistant the docs entry points or optional routing skill so NemoClaw guidance is available directly in chat.
<Badge intent="tip" minimal outlined>Resource</Badge>
</Card>

4
docs/index.yml
View file

@ -166,7 +166,7 @@ navigation:
slug: resources
collapsed: open-by-default
contents:
- page: "Agent Skills"
- page: "AI Agent Docs"
path: _build/agent-variants/resources/agent-skills.openclaw.generated.mdx
slug: agent-skills
- link: "Community Examples"
@ -306,7 +306,7 @@ navigation:
slug: resources
collapsed: open-by-default
contents:
- page: "Agent Skills"
- page: "AI Agent Docs"
path: _build/agent-variants/resources/agent-skills.hermes.generated.mdx
slug: agent-skills
- link: "Community Examples"

114
docs/resources/agent-skills.mdx
View file

@ -1,94 +1,56 @@
---
# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
# SPDX-License-Identifier: Apache-2.0
title: "NemoClaw Agent Skills for Your AI Coding Assistant"
sidebar-title: "Agent Skills"
description: "NemoClaw ships agent skills that let AI coding assistants guide you through installation, configuration, and operation."
description-agent: "Describes the agent skills shipped with NemoClaw and how to access them by cloning the repository. Use when users ask about AI agent support, coding assistant integration, or the .agents/skills/ directory."
keywords: ["nemoclaw agent skills", "ai coding assistant", "cursor", "claude code", "copilot"]
title: "Use NemoClaw Agent Prompts, Docs MCP Server, and Skills with Your AI Coding Agent"
sidebar-title: "Prompts, MCP, and Skills"
description: "NemoClaw exposes an MCP docs server and Markdown documentation that AI coding agents can use when they help you install, configure, or operate a sandbox."
description-agent: "Guides users and their AI coding agents to the NemoClaw docs MCP server, canonical Markdown documentation, llms.txt index, and optional docs-routing skill. Use when users ask about AI agent support, Markdown docs, MCP docs server, agent skills, Cursor, Claude Code, Codex, or Copilot."
keywords: ["nemoclaw ai agent docs", "nemoclaw mcp docs", "nemoclaw markdown docs", "llms.txt", "cursor", "claude code", "copilot"]
content:
type: "how_to"
---
NemoClaw ships agent skills that are generated directly from this documentation.
Each skill is a converted version of one or more doc pages, structured so AI coding assistants can consume it as context.
This means you can interact with the full NemoClaw documentation as skills inside your agent chat session, instead of reading the docs separately.
import { StarterPromptButton } from "../_components/StarterPromptButton";
Ask your assistant a question about NemoClaw and it responds with the same guidance found in these docs, adapted to your current situation.
Skills cover installation, inference configuration, network policy management, monitoring, deployment, security, workspace management, and the CLI reference.
NemoClaw publishes an MCP docs server and clean Markdown versions of its Fern documentation for AI coding agents.
Your agent can search or fetch the same canonical pages that appear on the docs site, then apply that guidance to your local setup.
<Note>
If you are a contributor and have cloned the full NemoClaw repository, the full set of skills including contributor and maintainer skills are already available at the project root.
Open the `NemoClaw` directory in your coding assistant and the skills load automatically.
This page is for users who installed NemoClaw with the installer and do not have a local clone.
</Note>
Use this page when you want your agent to help with installation, inference configuration, network policy management, monitoring, deployment, security, workspace management, or command reference lookup.
## Get the Skills
## Give Your Agent the Starter Prompt
Fetch only the skills from the NemoClaw repository without downloading the full source tree.
The fastest path is to copy the starter prompt from the NemoClaw home page and paste it into your local coding agent.
The prompt tells the agent to use the Markdown docs, ask one question at a time, run commands only with permission, and handle credentials safely.
<StarterPromptButton />
## Configure the Docs MCP Server
If your coding agent supports MCP, configure the NemoClaw docs server before you ask installation or troubleshooting questions.
The server URL is `https://docs.nvidia.com/nemoclaw/_mcp/server`.
It exposes a read-only `searchDocs` tool that searches the NemoClaw documentation and returns source URLs.
For Claude Code, run:
```bash
claude mcp add --transport http fern-docs https://docs.nvidia.com/nemoclaw/_mcp/server
```
For Cursor, add `https://docs.nvidia.com/nemoclaw/_mcp/server` to your MCP server configuration.
For other MCP clients, configure a streamable HTTP MCP server at that URL.
## Optional Docs-Routing Skill
If your coding agent supports local project skills, you can fetch the single user skill that encodes the same routing rules.
This skill is small because it points back to the Markdown docs instead of copying the docs into the repository.
Fetch only the docs-routing skill and root instructions without downloading the full source tree:
```bash
git clone --filter=blob:none --no-checkout https://github.com/NVIDIA/NemoClaw.git
cd NemoClaw
git sparse-checkout set --no-cone '/.agents/skills/nemoclaw-user-*/**' '/.agents/skills/nemoclaw-skills-guide/**' '/.claude/**' '/AGENTS.md' '/CLAUDE.md'
git sparse-checkout set --no-cone '/.agents/skills/nemoclaw-user-guide/**' '/.claude/**' '/AGENTS.md' '/CLAUDE.md'
git checkout
```
Open the `NemoClaw` directory in your AI coding assistant.
The assistant discovers the skills in `.agents/skills/` and uses them to answer NemoClaw questions with project-specific guidance.
You can keep the skills inside the cloned directory or copy `.agents/skills/` to a global location (such as `~/.cursor/skills/` or `~/.claude/skills/`) so they are available across all your projects.
The choice depends on whether you want NemoClaw skills scoped to one workspace or accessible everywhere.
## Update the Skills
The sparse checkout filter is saved, so `git pull` fetches only updated skills without downloading the full source tree.
Run `git pull` after each NemoClaw release to pick up new and updated skills.
## Available Skills
The following user skills ship with NemoClaw.
| Skill | Summary |
|-------|---------|
| `nemoclaw-user-overview` | What NemoClaw is, ecosystem placement (OpenClaw + OpenShell + NemoClaw), how it works internally, and release notes. |
| `nemoclaw-user-agent-skills` | Clone, update, and use NemoClaw's agent skills, including this page and the skills directory layout. |
| `nemoclaw-user-get-started` | Install NemoClaw, launch a sandbox, and run the first agent prompt. |
| `nemoclaw-user-configure-inference` | Choose inference providers during onboarding, switch models without restarting, and set up local inference servers (Ollama, vLLM, TensorRT-LLM, NIM). |
| `nemoclaw-user-manage-policy` | Approve or deny blocked egress requests in the TUI and customize the sandbox network policy (add, remove, or modify allowed endpoints). |
| `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-manage-sandboxes` | Manage day-two sandbox operations, including status, logs, diagnostics, rebuilds, upgrades, messaging channels, workspace files, backup, and restore. |
| `nemoclaw-user-reference` | CLI command reference, plugin and blueprint architecture, baseline network policies, and troubleshooting guide. |
## Example Questions and Triggered Skills
After opening the cloned repository in your coding assistant, ask a NemoClaw question in natural language.
The assistant matches your question to the relevant skill and follows the guidance it contains.
Examples of questions your assistant can answer with these skills:
| Question | Skill triggered |
|----------|-----------------|
| "How do I install NemoClaw?" | `nemoclaw-user-get-started` |
| "Switch my inference provider to Ollama." | `nemoclaw-user-configure-inference` |
| "A network request was blocked. How do I approve it?" | `nemoclaw-user-manage-policy` |
| "Show me the sandbox logs." | `nemoclaw-user-monitor-sandbox` |
| "How do I deploy NemoClaw to a remote GPU?" | `nemoclaw-user-deploy-remote` |
| "What security controls can I configure?" | `nemoclaw-user-configure-security` |
| "Back up my agent workspace files." | `nemoclaw-user-manage-sandboxes` |
| "What CLI commands are available?" | `nemoclaw-user-reference` |
| "What NemoClaw skills are available for my coding assistant?" | `nemoclaw-user-agent-skills` |
You can also reference a skill directly by name if you know which one you need.
## AI Coding Assistants that You Can Use with NemoClaw Skills
The NemoClaw agent skills follow the [Agent Skills best practices](https://agentskills.io/skill-creation/best-practices) and the [Claude Skills best practices](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices).
The following table shows how each AI coding assistant can use the NemoClaw skills.
| Assistant | Skill discovery |
|-----------|----------------|
| Cursor | Reads `AGENTS.md` at the project root, which references `.agents/skills/`. |
| Claude Code | Follows the `.claude/skills/` symlink, which points to `.agents/skills/`. |
| Other assistants | Point the assistant to `.agents/skills/` if it supports project-level skill loading. |
The assistant discovers `nemoclaw-user-guide` and uses it to fetch the relevant Markdown documentation.

2
fern/fern.config.json
View file

@ -1,4 +1,4 @@
{
"organization": "nvidia",
"version": "5.49.2"
"version": "5.50.5"
}

2175
scripts/docs-to-skills.py
View file

File diff suppressed because it is too large Load diff

19
skills/README.md
View file

@ -1,19 +1,14 @@
<!-- SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. -->
<!-- SPDX-License-Identifier: Apache-2.0 -->
# Generated NemoClaw Catalog Skills
# NemoClaw Catalog Skills
This directory is generated from `.agents/catalog-skills.yaml` and `.agents/skills/`.
Do not edit files here directly. The exporter preserves NVSkills signing artifacts (`skill.oms.sig` and `skill-card.md`) when regenerating an already-signed export.
This directory is the optional NVSkills CI watched location for customer-facing skill publication.
NemoClaw keeps source skills under `.agents/skills/` and copies publishable customer-facing skills here.
Do not put generated documentation copies here.
To update this export, edit the source skills or allowlist, then run:
NemoClaw currently maintains one customer-facing source skill:
```bash
python3 scripts/export-catalog-skills.py
```
- `.agents/skills/nemoclaw-user-guide/`, copied to `skills/nemoclaw-user-guide/`.
CI verifies the directory with:
```bash
python3 scripts/export-catalog-skills.py --check
```
When publishing or refreshing it in the catalog, follow `.github/catalog-skills-signing-flow.md`.

24
skills/catalog-metadata.json
View file

@ -1,24 +0,0 @@
{
"exportContentSha256": "9b48c35ea9a9c79fd1c8bfc6503da54cd5aab5b14fefde400feed023cb6309b1",
"generatedBy": "scripts/export-catalog-skills.py",
"metadata": {
"minNemoClawVersion": "0.1.0",
"testedNemoClawVersion": "0.1.0"
},
"schemaVersion": 1,
"skills": [
"nemoclaw-user-agent-skills",
"nemoclaw-user-configure-inference",
"nemoclaw-user-configure-security",
"nemoclaw-user-deploy-remote",
"nemoclaw-user-get-started",
"nemoclaw-user-manage-policy",
"nemoclaw-user-manage-sandboxes",
"nemoclaw-user-monitor-sandbox",
"nemoclaw-user-overview",
"nemoclaw-user-reference"
],
"source": ".agents/skills",
"sourceCommit": "3f4ec9de1be3f24c08fd4de37adf465d7927b871",
"sourceContentSha256": "2b762b00d861677b434a673f72d013f1183d4a42adfd6a0563406f820e6383b3"
}

64
skills/nemoclaw-user-agent-skills/BENCHMARK.md
View file

@ -1,64 +0,0 @@
# Evaluation Report
Evaluation of the `nemoclaw-user-agent-skills` skill before publication through NVSkills-Eval.
This benchmark summarizes 3-Tier Evaluation from NVSkills-Eval results for the skill. The goal is to document whether the skill is safe, discoverable, effective, and useful for agents before it is published for broader workflow use.
## Evaluation Summary
- Skill: `nemoclaw-user-agent-skills`
- Evaluation date: 2026-05-28
- NVSkills-Eval profile: `external`
- Overall verdict: PASS
- Tier 3 live agent evaluation: not available in this report
## Agents Used
- Tier 3 agent details were not available in this report.
## Metrics Used
Reported benchmark dimensions:
- Security: checks whether skill-assisted execution avoids unsafe behavior such as secret leakage, destructive commands, or unauthorized access.
- Correctness: checks whether the agent follows the expected workflow and produces the correct final output.
- Discoverability: checks whether the agent loads the skill when relevant and avoids using it when irrelevant.
- Effectiveness: checks whether the agent performs measurably better with the skill than without it.
- Efficiency: checks whether the agent uses fewer tokens and avoids redundant work.
Underlying evaluation signals used in this run:
- No Tier 3 evaluation signal details were available in this report.
## Test Tasks
Tier 3 evaluation task details were not available in this report.
## Results
Tier 3 dimension rollup was not available in this report.
## Tier 1: Static Validation Summary
Tier 1 validation passed with observations. NVSkills-Eval ran 9 checks and found 13 total findings.
Top findings:
- MEDIUM QUALITY/quality_correctness: Guide-only skill has very little content (8 lines) (`skills/nemoclaw-user-agent-skills/SKILL.md`)
- MEDIUM QUALITY/quality_correctness: SKILL_SPEC recommended field missing: 'metadata.author' (`skills/nemoclaw-user-agent-skills/SKILL.md`)
- MEDIUM QUALITY/quality_correctness: SKILL_SPEC recommended field missing: 'metadata.tags' (`skills/nemoclaw-user-agent-skills/SKILL.md`)
- MEDIUM SCHEMA/body_recommended_section: Missing recommended section: '## Instructions' (`skills/nemoclaw-user-agent-skills/SKILL.md`)
- MEDIUM SCHEMA/body_recommended_section: Missing recommended section: '## Examples' (`skills/nemoclaw-user-agent-skills/SKILL.md`)
## Tier 2: Deduplication Summary
Tier 2 validation passed. NVSkills-Eval ran 2 checks and found 0 total findings.
Notable observations:
- Context Deduplication: Collected 2 file(s)
- Inter-Skill Deduplication: Parsed skill 'nemoclaw-user-agent-skills': 298 char description
## Publication Recommendation
The skill is suitable to proceed toward NVSkills-Eval publication based on this benchmark. Skill owners should keep this file with the skill and refresh it when the evaluation dataset, skill behavior, or target agents materially change.

10
skills/nemoclaw-user-agent-skills/SKILL.md
View file

@ -1,10 +0,0 @@
---
name: "nemoclaw-user-agent-skills"
description: "Describes the agent skills shipped with NemoClaw and how to access them by cloning the repository. Use when users ask about AI agent support, coding assistant integration, or the .agents/skills/ directory. Trigger keywords - nemoclaw agent skills, ai coding assistant, cursor, claude code, copilot."
license: "Apache-2.0"
---
# NemoClaw Agent Skills for Your AI Coding Assistant
## References
- **Load [references/agent-skills.md](references/agent-skills.md)** when users ask about AI agent support, coding assistant integration, or the .agents/skills/ directory. Describes the agent skills shipped with NemoClaw and how to access them by cloning the repository.

20
skills/nemoclaw-user-agent-skills/evals/evals.json
View file

@ -1,20 +0,0 @@
[
{
"id": "docs-resources-agent-skills-001",
"question": "I'm looking at NemoClaw agent skills. Help me find a skill that can guide installation, policy, inference, or operations so I can delegate the right workflow to my AI coding assistant.",
"expected_skill": "nemoclaw-user-agent-skills",
"ground_truth": "A NemoClaw-specific answer that helps the user find a skill that can guide installation, policy, inference, or operations and gives enough concrete guidance, decision criteria, verification steps, or risk framing to delegate the right workflow to my AI coding assistant."
},
{
"id": "docs-resources-agent-skills-002",
"question": "I'm choosing among multiple NemoClaw skills. Help me understand what each skill is designed to do so I can avoid using a broad assistant when a targeted skill exists.",
"expected_skill": "nemoclaw-user-agent-skills",
"ground_truth": "A NemoClaw-specific answer that helps the user understand what each skill is designed to do and gives enough concrete guidance, decision criteria, verification steps, or risk framing to avoid using a broad assistant when a targeted skill exists."
},
{
"id": "docs-resources-agent-skills-003",
"question": "I'm letting an agent follow NemoClaw-specific instructions. Help me see why the skill guidance is trustworthy and scoped so I can use agent assistance without losing operational control.",
"expected_skill": "nemoclaw-user-agent-skills",
"ground_truth": "A NemoClaw-specific answer that helps the user see why the skill guidance is trustworthy and scoped and gives enough concrete guidance, decision criteria, verification steps, or risk framing to use agent assistance without losing operational control."
}
]

83
skills/nemoclaw-user-agent-skills/references/agent-skills.md
View file

@ -1,83 +0,0 @@
# NemoClaw Agent Skills for Your AI Coding Assistant
NemoClaw ships agent skills that are generated directly from this documentation.
Each skill is a converted version of one or more doc pages, structured so AI coding assistants can consume it as context.
This means you can interact with the full NemoClaw documentation as skills inside your agent chat session, instead of reading the docs separately.
Ask your assistant a question about NemoClaw and it responds with the same guidance found in these docs, adapted to your current situation.
Skills cover installation, inference configuration, network policy management, monitoring, deployment, security, workspace management, and the CLI reference.
**Note:**
If you are a contributor and have cloned the full NemoClaw repository, the full set of skills including contributor and maintainer skills are already available at the project root.
Open the `NemoClaw` directory in your coding assistant and the skills load automatically.
This page is for users who installed NemoClaw with the installer and do not have a local clone.
## Get the Skills
Fetch only the skills from the NemoClaw repository without downloading the full source tree.
```console
$ git clone --filter=blob:none --no-checkout https://github.com/NVIDIA/NemoClaw.git
$ cd NemoClaw
$ git sparse-checkout set --no-cone '/.agents/skills/nemoclaw-user-*/**' '/.agents/skills/nemoclaw-skills-guide/**' '/.claude/**' '/AGENTS.md' '/CLAUDE.md'
$ git checkout
```
Open the `NemoClaw` directory in your AI coding assistant.
The assistant discovers the skills in `.agents/skills/` and uses them to answer NemoClaw questions with project-specific guidance.
You can keep the skills inside the cloned directory or copy `.agents/skills/` to a global location (such as `~/.cursor/skills/` or `~/.claude/skills/`) so they are available across all your projects.
The choice depends on whether you want NemoClaw skills scoped to one workspace or accessible everywhere.
## Update the Skills
The sparse checkout filter is saved, so `git pull` fetches only updated skills without downloading the full source tree.
Run `git pull` after each NemoClaw release to pick up new and updated skills.
## Available Skills
The following user skills ship with NemoClaw.
| Skill | Summary |
|-------|---------|
| `nemoclaw-user-overview` | What NemoClaw is, ecosystem placement (OpenClaw + OpenShell + NemoClaw), how it works internally, and release notes. |
| `nemoclaw-user-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-manage-sandboxes` | Manage day-two sandbox operations, including status, logs, diagnostics, rebuilds, upgrades, messaging channels, workspace files, backup, and restore. |
| `nemoclaw-user-reference` | CLI command reference, plugin and blueprint architecture, baseline network policies, and troubleshooting guide. |
## Example Questions and Triggered Skills
After opening the cloned repository in your coding assistant, ask a NemoClaw question in natural language.
The assistant matches your question to the relevant skill and follows the guidance it contains.
Examples of questions your assistant can answer with these skills:
| Question | Skill triggered |
|----------|-----------------|
| "How do I install NemoClaw?" | `nemoclaw-user-get-started` |
| "Switch my inference provider to Ollama." | `nemoclaw-user-configure-inference` |
| "A network request was blocked. How do I approve it?" | `nemoclaw-user-manage-policy` |
| "Show me the sandbox logs." | `nemoclaw-user-monitor-sandbox` |
| "How do I deploy NemoClaw to a remote GPU?" | `nemoclaw-user-deploy-remote` |
| "What security controls can I configure?" | `nemoclaw-user-configure-security` |
| "Back up my agent workspace files." | `nemoclaw-user-manage-sandboxes` |
| "What CLI commands are available?" | `nemoclaw-user-reference` |
You can also reference a skill directly by name if you know which one you need.
## AI Coding Assistants that You Can Use with NemoClaw Skills
The NemoClaw agent skills follow the [Agent Skills best practices](https://agentskills.io/skill-creation/best-practices) and the [Claude Skills best practices](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices).
The following table shows how each AI coding assistant can use the NemoClaw skills.
| Assistant | Skill discovery |
|-----------|----------------|
| Cursor | Reads `AGENTS.md` at the project root, which references `.agents/skills/`. |
| Claude Code | Follows the `.claude/skills/` symlink, which points to `.agents/skills/`. |
| Other assistants | Point the assistant to `.agents/skills/` if it supports project-level skill loading. |

51
skills/nemoclaw-user-agent-skills/skill-card.md
View file

@ -1,51 +0,0 @@
## Description: <br>
Describes the agent skills shipped with NemoClaw and how to access them by cloning the repository. <br>
This skill is ready for commercial/non-commercial use. <br>
## Owner
NVIDIA <br>
### License/Terms of Use: <br>
Apache 2.0 <br>
## Use Case: <br>
Developers and engineers using AI coding assistants who need to discover, load, and leverage NemoClaw agent skills for installation, inference, policy management, and operations workflows. <br>
### Deployment Geography for Use: <br>
Global <br>
## Known Risks and Mitigations: <br>
Risk: Review before execution as proposals could introduce incorrect or misleading guidance into skills. <br>
Mitigation: Review and scan skill before deployment. <br>
## Reference(s): <br>
- [NemoClaw Agent Skills for Your AI Coding Assistant](references/agent-skills.md) <br>
## Skill Output: <br>
**Output Type(s):** [Configuration instructions, Shell commands] <br>
**Output Format:** [Markdown with inline bash code blocks] <br>
**Output Parameters:** [1D] <br>
**Other Properties Related to Output:** [None] <br>
## Evaluation Tasks: <br>
Evaluated via NVSkills-Eval (external profile): Tier 1 static validation (9 checks), Tier 2 deduplication (2 checks). 3 evaluation scenarios defined in evals.json. <br>
## Evaluation Metrics Used: <br>
Reported benchmark dimensions: <br>
- Security: Checks whether skill-assisted execution avoids unsafe behavior such as secret leakage, destructive commands, or unauthorized access. <br>
- Correctness: Checks whether the agent follows the expected workflow and produces the correct final output. <br>
- Discoverability: Checks whether the agent loads the skill when relevant and avoids using it when irrelevant. <br>
- Effectiveness: Checks whether the agent performs measurably better with the skill than without it. <br>
- Efficiency: Checks whether the agent uses fewer tokens and avoids redundant work. <br>
## Skill Version(s): <br>
0.1.0 (source: package.json) <br>
## Ethical Considerations: <br>
NVIDIA believes Trustworthy AI is a shared responsibility and we have established policies and practices to enable development for a wide array of AI applications. When downloaded or used in accordance with our terms of service, developers should work with their internal team to ensure this skill meets requirements for the relevant industry and use case and addresses unforeseen product misuse. <br>
(For Release on NVIDIA Platforms Only) <br>
Please report quality, risk, security vulnerabilities or NVIDIA AI Concerns [here](https://app.intigriti.com/programs/nvidia/nvidiavdp/detail). <br>

1
skills/nemoclaw-user-agent-skills/skill.oms.sig
View file

@ -1 +0,0 @@
{"mediaType":"application/vnd.dev.sigstore.bundle.v0.3+json","verificationMaterial":{"x509CertificateChain":{"certificates":[{"rawBytes":"MIICgzCCAgmgAwIBAgIUKIyS7SxNteQIiWzK1dWj85E6520wCgYIKoZIzj0EAwMwVTELMAkGA1UEBhMCVVMxGzAZBgNVBAoMEk5WSURJQSBDb3Jwb3JhdGlvbjEpMCcGA1UEAwwgTlZJRElBIEFnZW50IENhcGFiaWxpdGllcyBJQ0EgMDEwHhcNMjYwNDAxMDAwMDAwWhcNMjgwNDIyMTUzMzA5WjBUMQswCQYDVQQGEwJVUzEbMBkGA1UECgwSTlZJRElBIENvcnBvcmF0aW9uMSgwJgYDVQQDDB9OVklESUEgQWdlbnQgU2tpbGxzIFNpZ25pbmcgMDAxMHYwEAYHKoZIzj0CAQYFK4EEACIDYgAEYoRM9bQl/dGlwSRNi6bTpIJUXH8Nv9GciP6LSflJYYMLCc296kpyuTSsk5ddbAWiDcFX3C/ydX3jwc+qCLYP6uHy9XphyLjOQ27Yb2J6rBLVtRBS1mgGco/Gr7fL6ODco4GaMIGXMB0GA1UdDgQWBBRQ/5ZW3nJ6lmo9SVk7I15o7UGmpTAfBgNVHSMEGDAWgBRPGpILxMBBleJSsBGjrMKsby1CgjAMBgNVHRMBAf8EAjAAMA4GA1UdDwEB/wQEAwIHgDA3BggrBgEFBQcBAQQrMCkwJwYIKwYBBQUHMAGGG2h0dHA6Ly9vY3NwLm5kaXMubnZpZGlhLmNvbTAKBggqhkjOPQQDAwNoADBlAjAUygu/GiOCIXrgGr4SmLgeEVDcEitfFUv7ALbvLVGVyMysB3mxmO/uInZfXzWcJZsCMQDxuoxj4ZmO30jhkPIcCxGFCOvnUsnfU3TfGcouYm4M6iRpbKvtVnHPiy4bi6pcKf0="},{"rawBytes":"MIICiDCCAg6gAwIBAgIUZsIuSv9NkpJCNqtYEfCouVv5BzowCgYIKoZIzj0EAwMwUTELMAkGA1UEBhMCVVMxGzAZBgNVBAoMEk5WSURJQSBDb3Jwb3JhdGlvbjElMCMGA1UEAwwcTlZJRElBIEFnZW50IENhcGFiaWxpdGllcyBDQTAgFw0yNjA0MDEwMDAwMDBaGA85OTk5MTIzMTIzNTk1OVowVTELMAkGA1UEBhMCVVMxGzAZBgNVBAoMEk5WSURJQSBDb3Jwb3JhdGlvbjEpMCcGA1UEAwwgTlZJRElBIEFnZW50IENhcGFiaWxpdGllcyBJQ0EgMDEwdjAQBgcqhkjOPQIBBgUrgQQAIgNiAASI72cR3ctKGg4VWnB3bNja6g1Z2PnOmFEopkPof+QeIcPk9rT+g9MjJnq51EQXL93a7C2GJ9J985G4o2V85VD7wJ1RaXhluHW2rf3y8bQGeAYaKMr5s/hUgn+M3/9WlWejgaAwgZ0wHQYDVR0OBBYEFE8akgvEwEGV4lKwEaOswqxvLUKCMB8GA1UdIwQYMBaAFItnoAjjfuCEUvzyvWyI2vOGvwPjMBIGA1UdEwEB/wQIMAYBAf8CAQAwDgYDVR0PAQH/BAQDAgEGMDcGCCsGAQUFBwEBBCswKTAnBggrBgEFBQcwAYYbaHR0cDovL29jc3AubmRpcy5udmlkaWEuY29tMAoGCCqGSM49BAMDA2gAMGUCMQCeIMMfAbyzPDacw2MxG+Yt1cikrJX/DVxiGfXuHmkkXn6VgSzE79+lkqDErpVO2gYCMCNEColOyvUvkzZGUEI1hQ3PfMgi3FIo9tHoBKMw4/wGBLFpu/0ubtmbBXM6/UMOEw=="},{"rawBytes":"MIICRTCCAcygAwIBAgIUeJdY3rV86EdvFmG7L8LJBsyQFYkwCgYIKoZIzj0EAwMwUTELMAkGA1UEBhMCVVMxGzAZBgNVBAoMEk5WSURJQSBDb3Jwb3JhdGlvbjElMCMGA1UEAwwcTlZJRElBIEFnZW50IENhcGFiaWxpdGllcyBDQTAgFw0yNjA0MDEwMDAwMDBaGA85OTk5MTIzMTIzNTk1OVowUTELMAkGA1UEBhMCVVMxGzAZBgNVBAoMEk5WSURJQSBDb3Jwb3JhdGlvbjElMCMGA1UEAwwcTlZJRElBIEFnZW50IENhcGFiaWxpdGllcyBDQTB2MBAGByqGSM49AgEGBSuBBAAiA2IABAYpiXCDjJ9NT2eSDhyHJVSw1Tbze18cGG2F/578oWvHxg23eQAhNRYdq88i1iOshZSO6C29doKui5Xpmo/7Ctw9Sx4PP2RzOmIuOLCuTdNtKcTRwi4GEsd5BAFvWj42M6NjMGEwHQYDVR0OBBYEFItnoAjjfuCEUvzyvWyI2vOGvwPjMB8GA1UdIwQYMBaAFItnoAjjfuCEUvzyvWyI2vOGvwPjMA8GA1UdEwEB/wQFMAMBAf8wDgYDVR0PAQH/BAQDAgEGMAoGCCqGSM49BAMDA2cAMGQCMCwtAjWLaNwgGWNCgdyNoTyvNhqWRECRJV2r3+7w8g0PL6NHLOsbkgE09BH95h8XlgIwTaQmbbUh2ChAJ5TA1wRiVDnCcvbzHlZl2jM2FcwQQZlk19LOAbyGMRixbu2Ww/rj"}]},"tlogEntries":[]},"dsseEnvelope":{"payload":"ewogICJfdHlwZSI6ICJodHRwczovL2luLXRvdG8uaW8vU3RhdGVtZW50L3YxIiwKICAic3ViamVjdCI6IFsKICAgIHsKICAgICAgIm5hbWUiOiAibmVtb2NsYXctdXNlci1hZ2VudC1za2lsbHMiLAogICAgICAiZGlnZXN0IjogewogICAgICAgICJzaGEyNTYiOiAiODY3YmEyNTlhZDRhNjA3MjVhZDkzMzljOTYyZDJlYTJiYmYxMmQ4MWVkOTBlZDYzYzVkZmQzOGNlZGEyZmI1NCIKICAgICAgfQogICAgfQogIF0sCiAgInByZWRpY2F0ZVR5cGUiOiAiaHR0cHM6Ly9tb2RlbF9zaWduaW5nL3NpZ25hdHVyZS92MS4wIiwKICAicHJlZGljYXRlIjogewogICAgInJlc291cmNlcyI6IFsKICAgICAgewogICAgICAgICJhbGdvcml0aG0iOiAic2hhMjU2IiwKICAgICAgICAibmFtZSI6ICJCRU5DSE1BUksubWQiLAogICAgICAgICJkaWdlc3QiOiAiNTBmZDliNjc5NWVjNzcyOWRlMDkwY2EyZjQyY2M2NjQxYzY5YzIxZDZkOTlmOGI2NTA3MzMxNTU0Mjc4M2ZlYyIKICAgICAgfSwKICAgICAgewogICAgICAgICJhbGdvcml0aG0iOiAic2hhMjU2IiwKICAgICAgICAibmFtZSI6ICJTS0lMTC5tZCIsCiAgICAgICAgImRpZ2VzdCI6ICIwODExMWJiMjRhYzU5Y2YyNWUzMzMxN2MxZDIwYzE1MWI4ZmQyMzRlOGE3MTFmZWExYWEzMTkwNWYwMzk4YThjIgogICAgICB9LAogICAgICB7CiAgICAgICAgImFsZ29yaXRobSI6ICJzaGEyNTYiLAogICAgICAgICJuYW1lIjogImV2YWxzL2V2YWxzLmpzb24iLAogICAgICAgICJkaWdlc3QiOiAiMjVjYzJhY2FjZDA0ODk1MjRjZDhlZjQxYTViM2IzYTUzN2JmOTlkOWFiNGQ3M2Y3MTg5M2UzYzI1NjM1NGE1MiIKICAgICAgfSwKICAgICAgewogICAgICAgICJhbGdvcml0aG0iOiAic2hhMjU2IiwKICAgICAgICAibmFtZSI6ICJyZWZlcmVuY2VzL2FnZW50LXNraWxscy5tZCIsCiAgICAgICAgImRpZ2VzdCI6ICIyOTQ3ZmRhYmU2YjM0MGI3NWVjZGM2Y2ZiMTEyMTg0NjQwYTdlM2I0NDc2ZDRjNGUyY2NjYzNkNmFjY2Q3ODk5IgogICAgICB9LAogICAgICB7CiAgICAgICAgImFsZ29yaXRobSI6ICJzaGEyNTYiLAogICAgICAgICJuYW1lIjogInNraWxsLWNhcmQubWQiLAogICAgICAgICJkaWdlc3QiOiAiNmM4M2Q5ZjVkYjcxZmUzZTdhMjI3ZjI5ZGQ0YjE4MjZlOGE1ZDU0NTMwOTk3NTFiMmQyMjgxYjc5NjJhOTAyZCIKICAgICAgfQogICAgXSwKICAgICJzZXJpYWxpemF0aW9uIjogewogICAgICAiaGFzaF90eXBlIjogInNoYTI1NiIsCiAgICAgICJpZ25vcmVfcGF0aHMiOiBbCiAgICAgICAgIi5naXQiLAogICAgICAgICIuZ2l0aHViIiwKICAgICAgICAiLmdpdGF0dHJpYnV0ZXMiLAogICAgICAgICIuZ2l0aWdub3JlIgogICAgICBdLAogICAgICAiYWxsb3dfc3ltbGlua3MiOiBmYWxzZSwKICAgICAgIm1ldGhvZCI6ICJmaWxlcyIKICAgIH0KICB9Cn0=","payloadType":"application/vnd.in-toto+json","signatures":[{"sig":"MGQCMACJwjyhEUdAfq8ybKu471FJDvOYVOz1pTnj91deSewhudL+6huCeUaazxnH8RayPQIwapx9W7+WDXoOUEUaEDq2oFQfQBsxwhdwHGkwcNJdfSo8X/VHweiISGnrsh+UHEAD","keyid":""}]}}

75
skills/nemoclaw-user-configure-inference/BENCHMARK.md
View file

@ -1,75 +0,0 @@
# Evaluation Report
Evaluation of the `nemoclaw-user-configure-inference` skill before publication through NVSkills-Eval.
This benchmark summarizes 3-Tier Evaluation from NVSkills-Eval results for the skill. The goal is to document whether the skill is safe, discoverable, effective, and useful for agents before it is published for broader workflow use.
## Evaluation Summary
- Skill: `nemoclaw-user-configure-inference`
- Evaluation date: 2026-05-28
- NVSkills-Eval profile: `external`
- Overall verdict: FAIL
- Tier 3 live agent evaluation: not available in this report
## Agents Used
- Tier 3 agent details were not available in this report.
## Metrics Used
Reported benchmark dimensions:
- Security: checks whether skill-assisted execution avoids unsafe behavior such as secret leakage, destructive commands, or unauthorized access.
- Correctness: checks whether the agent follows the expected workflow and produces the correct final output.
- Discoverability: checks whether the agent loads the skill when relevant and avoids using it when irrelevant.
- Effectiveness: checks whether the agent performs measurably better with the skill than without it.
- Efficiency: checks whether the agent uses fewer tokens and avoids redundant work.
Underlying evaluation signals used in this run:
- No Tier 3 evaluation signal details were available in this report.
## Test Tasks
Tier 3 evaluation task details were not available in this report.
## Results
Tier 3 dimension rollup was not available in this report.
## Tier 1: Static Validation Summary
Tier 1 validation passed with observations. NVSkills-Eval ran 9 checks and found 13 total findings.
Top findings:
- MEDIUM PII/gps_coordinates: GPS coordinates (location information) (`references/inference-options.md:89`)
- MEDIUM QUALITY/quality_correctness: SKILL_SPEC recommended field missing: 'metadata.author' (`skills/nemoclaw-user-configure-inference/SKILL.md`)
- MEDIUM QUALITY/quality_correctness: SKILL_SPEC recommended field missing: 'metadata.tags' (`skills/nemoclaw-user-configure-inference/SKILL.md`)
- MEDIUM QUALITY/quality_efficiency: Deeply nested references in set-up-sub-agent.md (`skills/nemoclaw-user-configure-inference/SKILL.md`)
- MEDIUM SCHEMA/body_recommended_section: Missing recommended section: '## Instructions' (`skills/nemoclaw-user-configure-inference/SKILL.md`)
## Tier 2: Deduplication Summary
Tier 2 validation reported findings. NVSkills-Eval ran 2 checks and found 3 total findings.
Top findings:
- HIGH DUPLICATE/duplicate: Duplicate content found across SKILL.md and references/inference-options.md and references/set-up-sub-agent.md and references/switch-inference-providers.md and references/tool-calling-reliability.md and references/use-local-inference-details.md:
"(preamble)" in SKILL.md (lines 1-3)
vs "(preamble)" in references/inference-options.md (lines 1-2)
vs "(preamble)" in references/set-up-sub-agent.md (lines 1-2)
vs "(preamble)" in references/switch-inference-providers.md (lines 1-2)
vs "(preamble)" in references/tool-calling-reliability.md (lines 1-2)
vs "(preamble)" in references/use-local-inference-details.md (lines 1-2) (`SKILL.md:1`)
- HIGH DUPLICATE/duplicate: Duplicate content found across references/inference-options.md and references/tool-calling-reliability.md:
"## Next Steps" in references/inference-options.md (lines 138-142)
vs "## Next Steps" in references/tool-calling-reliability.md (lines 160-164) (`references/inference-options.md:138`)
- HIGH DUPLICATE/duplicate: Duplicate content found across references/inference-options.md and references/switch-inference-providers.md:
"## How Inference Routing Works" in references/inference-options.md (lines 9-19)
vs "## Notes" in references/switch-inference-providers.md (lines 197-204) (`references/inference-options.md:9`)
## Publication Recommendation
The skill should be reviewed before NVSkills-Eval publication. Skill owners should address the findings above and rerun NVSkills-Eval to refresh this benchmark.

265
skills/nemoclaw-user-configure-inference/SKILL.md
View file

@ -1,265 +0,0 @@
---
name: "nemoclaw-user-configure-inference"
description: "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. Trigger keywords - nemoclaw local inference, ollama nemoclaw, vllm nemoclaw, local model server, openai compatible endpoint, switch nemoclaw inference model, change inference runtime, nemoclaw additional model, nemoclaw sub-agent model, openclaw sub-agent, agents.list, sessions_spawn, vlm-demo, nemoclaw inference options, nemoclaw onboarding providers, nemoclaw inference routing, nemoclaw tool calling, ollama tool calls, vllm tool-call-parser, raw json in tui."
license: "Apache-2.0"
---
# Use a Local Inference Server
import { AgentOnly } from "../_components/AgentGuide";
## Gotchas
- Ollama is convenient for local chat, but some model/template combinations can return tool calls as plain text under realistic agent load.
## Prerequisites
<AgentOnly variant="openclaw">
- NemoClaw installed. Refer to the Quickstart (use the `nemoclaw-user-get-started` skill) if you have not installed yet.
</AgentOnly>
<AgentOnly variant="hermes">
- NemoClaw installed. Refer to Quickstart with Hermes (use the `nemoclaw-user-get-started` skill) if you have not installed yet.
</AgentOnly>
- A local model server running, or a supported Ollama, vLLM, or NIM setup that the NemoClaw onboard wizard can use, start, or install.
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 experimental managed 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.
## Ollama
Ollama is the default local inference option.
The onboard wizard detects Ollama automatically when you have installed it or started it on the host.
If you installed Ollama but have not started it, NemoClaw starts it for you.
On macOS and Linux, the wizard can also offer to install Ollama when it is not present.
When the host Ollama is below the minimum version NemoClaw expects for its starter models (currently `0.7.0`), the wizard surfaces an explicit **Upgrade Ollama** entry in the provider menu instead of silently reusing the older daemon, and the express setup path resolves to that entry.
The wizard inspects both the CLI binary (`ollama --version`) and the locally running daemon (`/api/version` on `:11434`) so the upgrade entry still appears when only one side is stale, for example a fresh user-local binary paired with the original system daemon.
The gate skips Windows-host Ollama reached from WSL through `host.docker.internal`.
The separate **Use / Start / Install Ollama on Windows host** entries handle that case and run their own actions on the Windows side.
On macOS, the wizard runs the platform install or upgrade path with `brew upgrade ollama`.
On Linux, the wizard runs the official `https://ollama.com/install.sh` path.
Upgrades on Linux always take the sudo-driven system path because the sudo-free user-local fallback would leave the existing system daemon on `:11434` serving the stale binary.
If sudo is not available in a non-interactive run, NemoClaw refuses to silently downgrade the path and asks you to rerun interactively or upgrade Ollama manually.
After an upgrade finishes, NemoClaw re-probes the running daemon's `/api/version` and fails the run if the daemon still reports below the minimum.
Fresh installs skip this re-probe because the bundled installers ship a daemon at or above the minimum.
On WSL, the wizard can use, start, restart, or install Ollama on the Windows host through PowerShell interop.
### Linux Install Modes
On native Linux, the install path picks between a system install (under `/usr/local`, using the official `https://ollama.com/install.sh`) and a sudo-free user-local install (under `${HOME}/.local`).
NemoClaw selects the mode automatically:
- Running as root or with passwordless sudo (`sudo -n true` returns 0) selects the system install.
- A non-interactive run (`NEMOCLAW_NON_INTERACTIVE=1` or no TTY on stdin) without passwordless sudo selects the user-local install.
This is the path that lets headless hosts complete onboarding without prompting for a sudo password.
- An interactive shell without passwordless sudo selects the system install and lets the official installer prompt for the password as usual.
Override the detection with `NEMOCLAW_OLLAMA_INSTALL_MODE=system` or `NEMOCLAW_OLLAMA_INSTALL_MODE=user`.
The user-local install replicates only the binary extraction step of the official installer.
It downloads the release tarball, extracts it to `${HOME}/.local`, and launches `${HOME}/.local/bin/ollama serve` one time.
It does not configure a systemd service, does not create the `ollama` system user, and does not install CUDA drivers, so you must relaunch the daemon manually after a reboot.
NemoClaw also prints a one-line `PATH` hint if `${HOME}/.local/bin` is not already on your `PATH`; you can add `export PATH="${HOME}/.local/bin:$PATH"` to your shell profile to invoke `ollama` directly.
Both modes rely on `zstd` for archive extraction. On Debian and Ubuntu, the system path uses `sudo apt-get` to install `zstd` automatically and explains the prompt before continuing.
The user-local path cannot bootstrap system packages without elevation.
If `zstd` is missing, it prints per-distro install hints and exits.
Install `zstd` manually, then rerun onboarding.
Run the onboard wizard.
```bash
nemoclaw onboard
```
Select **Local Ollama** from the provider list.
NemoClaw lists installed models or offers starter models if you have not installed any.
On hosts where the larger starter models fit the currently available GPU memory, the starter list includes `qwen3.6:35b` and selects it by default.
When another GPU workload is using most of the memory at onboard time, NemoClaw downgrades the menu to the largest model that still fits.
It pulls the selected model, loads it into memory, and validates it before continuing.
When Ollama reports a loaded-model context length, NemoClaw uses that value for the `contextWindow` baked into `openclaw.json` unless you set `NEMOCLAW_CONTEXT_WINDOW` yourself.
If the selected model declares that it does not support tool calling, onboarding stops with guidance to choose a model whose `ollama show <model>` capabilities include `tools`.
The validation also requires structured chat-completions tool calls.
If the model leaks tool-call JSON as plain message text, onboarding stops so you can choose a model that returns tool calls in the expected response field.
If a host-side validation probe times out, NemoClaw retries the Ollama tool-call validation with a larger timeout before failing the setup.
On WSL, if you choose the Windows-host Ollama path, NemoClaw uses `host.docker.internal:11434` and pulls missing models through the Ollama HTTP API instead of requiring the `ollama` CLI inside WSL.
### WSL with Windows-Host Ollama
When NemoClaw runs inside WSL, the provider menu can include Windows-host Ollama actions:
- Use Ollama on Windows host when the Windows daemon is already reachable.
- Restart Ollama on Windows host when you installed the daemon but bound it only to Windows loopback.
- Start Ollama on Windows host when you installed Ollama but have not started it.
- Install Ollama on Windows host when Windows does not have Ollama installed.
The install and restart paths set `OLLAMA_HOST=0.0.0.0:11434` on the Windows side so Docker and WSL can reach the daemon through `host.docker.internal`.
After an install or restart action, NemoClaw relaunches Ollama from the detected Windows tray app or verified `ollama.exe` path and waits until `host.docker.internal:11434` responds.
If the HTTP endpoint is not reachable yet, NemoClaw also checks for the Windows `ollama.exe` process through PowerShell interop so it can offer a start or restart action instead of hiding the Windows-host path.
If the daemon does not become reachable, onboarding prints PowerShell commands you can run to inspect the Windows-side process and port state. Use one Ollama instance on port `11434` at a time.
If both WSL and Windows-host Ollama are running, pick the intended menu entry during onboarding so NemoClaw validates and pulls models against the right daemon.
Windows-host Ollama requires Docker Desktop WSL integration because the sandbox reaches the Windows daemon through Docker Desktop's WSL routing path.
If NemoClaw detects native Docker Engine inside WSL, the provider menu labels Windows-host Ollama actions as requiring Docker Desktop integration.
Selecting one of those actions in the unsupported native Docker topology exits early with a remediation message instead of trying to start or install Ollama on Windows.
<AgentOnly variant="openclaw">
**Warning:**
Ollama is convenient for local chat, but some model/template combinations can
return tool calls as plain text under realistic agent load. If the TUI shows raw
JSON such as `{"name":"memory_search","arguments":{...}}` instead of running a
tool, switch to vLLM with `--enable-auto-tool-choice` and the correct
`--tool-call-parser`. See [Tool-Calling Reliability](references/tool-calling-reliability.md).
</AgentOnly>
### 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.
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`.
For non-WSL Ollama setups, the onboard wizard manages the proxy automatically:
- Generates a random 24-byte token on first run and stores it in
`~/.nemoclaw/ollama-proxy-token` with `0600` permissions.
- Starts the proxy after Ollama and verifies it before continuing.
- Cleans up stale proxy processes from previous runs.
- Probes the sandbox Docker network path to the proxy before committing the inference route.
- Stops matching proxy processes during uninstall before deleting NemoClaw state.
- Reuses the persisted token after a host reboot so you do not need to re-run
onboard.
On native Linux hosts, a firewall can allow the host proxy health check while still blocking sandbox containers on the OpenShell Docker bridge.
When the sandbox-side proxy probe fails with a TCP error, onboarding exits before it saves the inference route and prints a command like:
```bash
sudo ufw allow from <openshell-docker-subnet> to any port 11435 proto tcp
nemoclaw onboard
```
If the probe cannot run, for example because Docker Desktop or WSL uses a different host routing model, onboarding continues and relies on the regular proxy health check.
NemoClaw configures the sandbox provider to use proxy port `11435` with the generated token as its `OPENAI_API_KEY` credential.
OpenShell's L7 proxy injects the token at egress, so the agent inside the sandbox never sees the token directly.
All proxy endpoints require the Bearer token, including `GET /api/tags`.
Internal health and reachability checks run through the proxy treat any HTTP response, including `401`, as proof the proxy is alive.
They fail only when nothing answers at all.
If Ollama is already running on a non-loopback address when you start onboard,
the wizard restarts it on `127.0.0.1:11434` so the proxy is the only network
path to the model server.
### GPU Memory Cleanup
When you switch away from Ollama, stop host services, or destroy an Ollama-backed sandbox, NemoClaw asks Ollama to unload currently loaded models from GPU memory.
The cleanup sends `keep_alive: 0` for each model reported by Ollama and runs on a best-effort basis, so shutdown continues if Ollama is already stopped.
This does not delete downloaded model files.
### Non-Interactive Setup
```bash
NEMOCLAW_PROVIDER=ollama \
NEMOCLAW_MODEL=qwen3.5:9b \
nemoclaw onboard --non-interactive --yes
```
If `NEMOCLAW_MODEL` is not set, NemoClaw selects a default model based on available memory.
If `NEMOCLAW_MODEL` names a known bootstrap model (for example `qwen3.6:35b`) that does not fit the host's currently available GPU memory, NemoClaw warns and falls back to the largest known model that does fit.
Unknown or custom tags (any value the bootstrap registry has not seen) are still passed through; the Ollama runner validates the choice itself.
In interactive onboarding, registry-known installed tags that do not fit current GPU memory are filtered out of the installed-model menu.
If none of the installed registry-known tags fit, NemoClaw shows the starter-model choices and warns when even the smallest bootstrap tag may not fit.
After a selected model fails validation, NemoClaw excludes that tag from the next installed-model menu so pressing Enter cannot select the same failing model repeatedly.
When Ollama reports a loaded-model context length below `16384` and `NEMOCLAW_CONTEXT_WINDOW` is unset, NemoClaw raises the baked `contextWindow` to `16384` so the agent prompt and tool definitions fit better than the stock daemon default.
If the initial Ollama validation probe times out during a cold load, NemoClaw retries once with a 300-second probe budget.
This applies beyond DGX Spark, including tight-VRAM dGPU hosts where warm-up can spill from GPU to CPU.
`--yes` (or `NEMOCLAW_YES=1`) authorizes the Ollama model download without an interactive confirmation prompt.
Under `--non-interactive`, include `--yes` (or `NEMOCLAW_YES=1`) to authorize the download.
Onboard exits otherwise because it cannot prompt.
Run onboard without `--non-interactive` to get the interactive `[y/N]` prompt that shows the model size before downloading.
| Variable | Purpose |
|---|---|
| `NEMOCLAW_PROVIDER` | Set to `ollama`. |
| `NEMOCLAW_MODEL` | Ollama model tag to use. Optional. |
| `NEMOCLAW_YES` | Set to `1` to auto-accept the model-download confirmation prompt. Optional. |
## Compatible Local Servers
Use **Other OpenAI-compatible endpoint** for vLLM, TensorRT-LLM, llama.cpp, LocalAI, NIM, SGLang, or another server that implements `/v1/chat/completions`.
For compatible endpoints, NemoClaw uses `/v1/chat/completions` by default because some local backends accept `/v1/responses` but drop system prompts or tool definitions.
Set `NEMOCLAW_PREFERRED_API=openai-responses` only after you have verified that the backend streams the events OpenClaw requires.
For the full compatible-endpoint prompt flow, non-interactive variables, API-path controls, managed vLLM profiles, NIM setup, and timeout settings, refer to [Inference Options](references/inference-options.md#setup-details-for-local-and-compatible-providers).
## Managed vLLM and NIM
NemoClaw can use an already-running vLLM server on `localhost:8000`, start managed vLLM on supported NVIDIA GPU hosts, or manage a local NIM container when `NEMOCLAW_EXPERIMENTAL=1` is set.
Managed vLLM records the model returned by `/v1/models` and uses runtime metadata such as `max_model_len` when available.
In interactive managed vLLM setup, the wizard lists validated model choices for your host profile before it pulls weights.
Press **Enter** to accept the profile default, or choose a numbered model from the list.
For scripted runs, set `NEMOCLAW_VLLM_MODEL=<slug>` to choose a registry model without prompting.
If the host reboots and the `nemoclaw-vllm` container is stopped, NemoClaw restarts the managed vLLM container during recovery instead of requiring a fresh onboarding run.
NIM uses the same chat-completions API path restriction as vLLM.
On Linux Docker-driver GPU sandboxes, NemoClaw keeps local inference on the OpenShell bridge route and verifies `https://inference.local/v1/models` from inside the sandbox runtime after the sandbox reaches ready.
It treats only a 2xx response as success because that path includes the proxy authentication rewrite the agent uses.
If the runtime route fails, onboarding reports the endpoint and recovery steps before the first agent prompt.
For registry slugs, Hugging Face token requirements, NGC login behavior, and non-interactive examples, refer to [Inference Options](references/inference-options.md#setup-details-for-local-and-compatible-providers).
## Verify the Configuration
After onboarding completes, confirm the active provider and model.
```bash
nemoclaw <name> status
```
The output shows the provider label (for example, "Local vLLM" or "Other OpenAI-compatible endpoint") and the active model.
For Local Ollama, status also checks the authenticated proxy when a proxy token is available.
If `Inference` is healthy but `Inference (auth proxy)` is not, rerun onboarding to repair the proxy path that sandbox requests use.
## Switch Models at Runtime
You can change the model without re-running onboard.
Refer to [Switch Inference Models](references/switch-inference-providers.md) for the full procedure.
For compatible endpoints, the command is:
```bash
nemoclaw inference set --provider compatible-endpoint --model <model-name>
```
If the provider itself needs to change (for example, switching from vLLM to a cloud API), pass the new provider to `nemoclaw inference set`.
## References
- **Load [references/switch-inference-providers.md](references/switch-inference-providers.md)** when switching inference providers, changing the model runtime, or reconfiguring inference routing. Changes the active inference model without restarting the sandbox.
- **Load [references/set-up-sub-agent.md](references/set-up-sub-agent.md)** when users ask how to add a second model, configure a sub-agent model, use Omni for vision tasks, configure agents.list, or use sessions_spawn in NemoClaw. Shows the NemoClaw-specific file paths and update flow for adding an auxiliary OpenClaw sub-agent model.
- **Load [references/inference-options.md](references/inference-options.md)** when explaining which providers are available, what the onboard wizard presents, or how inference routing works. Lists all inference providers offered during NemoClaw onboarding.
- **[references/tool-calling-reliability.md](references/tool-calling-reliability.md)** — Explains Ollama tool-call leak symptoms, when to use vLLM with a tool-call parser, and how to repoint NemoClaw to a parser-aware local endpoint.
## Related Skills
- [Inference Options](references/inference-options.md) for the full list of providers available during onboarding.
- [Tool-Calling Reliability](references/tool-calling-reliability.md) for diagnosing raw JSON tool-call output with local models.
- [Switch Inference Models](references/switch-inference-providers.md) for runtime model switching.
- `nemoclaw-user-get-started` — Quickstart (use the `nemoclaw-user-get-started` skill) for first-time installation

11
skills/nemoclaw-user-configure-inference/evals/evals.json
View file

@ -1,11 +0,0 @@
[
{
"id": "docs-inference-inference-options-001",
"question": "I'm choosing an inference option during onboarding. Help me compare hosted providers, local servers, and compatible endpoints so I can select a model path that fits my privacy, cost, and reliability needs.",
"expected_skill": "nemoclaw-user-configure-inference",
"ground_truth": "A NemoClaw-specific answer that helps the user compare hosted providers, local servers, and compatible endpoints and gives enough concrete guidance, decision criteria, verification steps, or risk framing to select a model path that fits my privacy, cost, and reliability needs.",
"expected_behavior": [
"Uses the expected_skill and does not make up answers if it cannot find the answer from the skill."
]
}
]

437
skills/nemoclaw-user-configure-inference/references/inference-options.md
View file

@ -1,437 +0,0 @@
# NemoClaw Inference Options
import { AgentOnly } from "../_components/AgentGuide";
NemoClaw supports multiple inference providers.
During onboarding, the NemoClaw onboarding wizard presents a numbered list of providers to choose from.
Your selection determines where NemoClaw routes the agent's inference traffic.
<AgentOnly variant="openclaw">
For OpenClaw onboarding, use `nemoclaw onboard`.
The provider flow is the same, with the NVIDIA Endpoints route available for OpenClaw Agent.
</AgentOnly>
<AgentOnly variant="hermes">
For Hermes onboarding, use `nemoclaw onboard`.
The provider flow is the same, with the Hermes Provider route available for Hermes Agent.
</AgentOnly>
## 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.
Local Ollama and local vLLM do not require your host `OPENAI_API_KEY`.
NemoClaw uses provider-specific local tokens for those routes, and rebuilds of legacy local-inference sandboxes migrate away from stale OpenAI credential requirements.
## Provider Status
| Provider | Status | Endpoint type | Notes |
|----------|--------|---------------|-------|
| NVIDIA Endpoints | Tested | OpenAI-compatible | Hosted models on integrate.api.nvidia.com |
| OpenAI | Tested | Native OpenAI-compatible | Uses OpenAI model IDs |
| Other OpenAI-compatible endpoint | Tested | Custom OpenAI-compatible | For compatible proxies and gateways |
| Anthropic | Tested | Native Anthropic | Uses anthropic-messages |
| Other Anthropic-compatible endpoint | Tested | Custom Anthropic-compatible | For Claude proxies and compatible gateways |
| Google Gemini | Tested | OpenAI-compatible | Uses Google's OpenAI-compatible endpoint |
| Hermes Provider | Hermes only | OpenAI-compatible route | Available when onboarding Hermes Agent through `nemohermes` |
| Local Ollama | Caveated | Local Ollama API | Available when Ollama is installed or running on the host |
| Local NVIDIA NIM | Experimental | Local OpenAI-compatible | Requires `NEMOCLAW_EXPERIMENTAL=1` and a NIM-capable GPU |
| Local vLLM (already running) | Caveated | Local OpenAI-compatible | Appears in the onboarding menu when NemoClaw detects a server already on `localhost:8000`. No flag required. |
| Local vLLM (managed install/start) | Caveated | Local OpenAI-compatible | Appears by default on DGX Spark and DGX Station. Generic Linux NVIDIA GPU hosts require `NEMOCLAW_EXPERIMENTAL=1` or `NEMOCLAW_PROVIDER=install-vllm`. NemoClaw pulls/starts a vLLM container on a supported NVIDIA GPU host. |
## Provider Options
The onboard wizard presents the following provider options by default.
The first six are always available.
Ollama appears when you have installed or started it on the host.
Local vLLM appears when NemoClaw detects a running vLLM server.
The managed install/start vLLM entry appears by default on DGX Spark and DGX Station, and appears on generic Linux NVIDIA GPU hosts after opt-in.
| 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, Nemotron 3 Ultra 550B, GLM-5.1, MiniMax M2.7, GPT-OSS 120B, DeepSeek V4 Pro |
| 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`. NemoClaw uses `/v1/chat/completions` at runtime by default; set `NEMOCLAW_PREFERRED_API=openai-responses` to allow `/v1/responses` for proxies that implement it, such as some llama.cpp builds. The wizard prompts for a base URL and model name. Works with OpenRouter, LocalAI, llama.cpp, or any compatible proxy. When you enable Telegram messaging, onboarding also runs a bounded sandbox-side smoke check through `https://inference.local/v1/chat/completions`. 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 chat-completions endpoint. NemoClaw skips the Responses-API probe because Gemini does not support `/v1/responses`. Set `GEMINI_API_KEY`. | `gemini-3.1-pro-preview`, `gemini-3.1-flash-lite-preview`, `gemini-3-flash-preview`, `gemini-2.5-pro`, `gemini-2.5-flash`, `gemini-2.5-flash-lite` |
| Hermes Provider | Routes Hermes Agent through the host OpenShell provider registered by NemoClaw when onboarding Hermes Agent. | Curated Hermes Provider models such as `moonshotai/kimi-k2.6`, `openai/gpt-5.4-mini`, and `z-ai/glm-5.1`. |
| Local Ollama | Routes to a local Ollama instance on `localhost:11434`. NemoClaw detects installed models, offers starter models if none are present, pulls and warms the selected model, and validates it. | Selected during onboarding. For more information, refer to [Use a Local Inference Server](../SKILL.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
NVIDIA Nemotron models expose OpenAI-compatible APIs across every supported deployment surface, so two onboarding options can route to Nemotron.
| Nemotron Host | Onboard Wizard Option | Why |
|---|---|---|
| `build.nvidia.com` (NVIDIA-hosted) | **Option 1: NVIDIA Endpoints** | NemoClaw sets the base URL to `https://integrate.api.nvidia.com/v1` for you and validates the model against the build catalog. |
| Self-hosted NIM container | **Option 3: Other OpenAI-compatible endpoint** | NIM exposes an OpenAI-compatible `/v1/chat/completions` route. Point the base URL at your NIM service and enter the Nemotron model ID. |
| Enterprise NVIDIA AI Enterprise gateway | **Option 3: Other OpenAI-compatible endpoint** | Enterprise gateways front Nemotron with the same OpenAI-compatible contract. Use the gateway's base URL and your enterprise token. |
| vLLM, SGLang, or TRT-LLM serving Nemotron weights | **Option 3: Other OpenAI-compatible endpoint** | Each runtime exposes Nemotron through `/v1/chat/completions`. Use the runtime's base URL and the model ID it reports. |
| Local NIM started by the wizard | **Local NVIDIA NIM** (experimental) | Requires `NEMOCLAW_EXPERIMENTAL=1` and a NIM-capable GPU. NemoClaw pulls and manages the container for you. |
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`.
Edit that file to define which models the router can choose from.
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.
```yaml
routing:
method: prefill
checkpoint: llm-router/checkpoints/prefill_router_qwen08b.pt
tolerance: 0.20
encoder: Qwen/Qwen3.5-0.8B
models:
- name: nano
litellm_model: "openai/nvidia/nvidia/Nemotron-3-Nano-30B-A3B"
cost_per_m_input_tokens: 0.05
api_base: "https://inference-api.nvidia.com"
- name: super
litellm_model: "openai/nvidia/nvidia/nemotron-3-super-v3"
cost_per_m_input_tokens: 0.10
api_base: "https://inference-api.nvidia.com"
```
The `tolerance` parameter controls the accuracy-cost tradeoff.
| Value | Behavior |
|-------|----------|
| `0.0` | Always pick the most accurate model. |
| `0.20` | Allow up to 20 percentage points below the best for a cheaper model (default). |
| `1.0` | Always pick the cheapest model. |
The router runs on the host, not inside the sandbox.
```text
Sandbox (agent) ──> OpenShell Gateway (L7 proxy) ──> Model Router (:4000) ──> NVIDIA API
└── PrefillRouter selects model
```
Credentials flow through the OpenShell provider system.
The sandbox never sees raw API keys.
To use the router in scripted setup, set:
```bash
NEMOCLAW_PROVIDER=routed NVIDIA_API_KEY=<your-key> nemoclaw onboard --non-interactive
```
### Host Python Requirement
The Model Router runs in a host-side virtual environment that NemoClaw creates during onboarding.
NemoClaw probes `python3.13`, `python3.12`, `python3.11`, `python3.10`, and bare `python3`, and adopts the first interpreter that satisfies both of:
- Version inside `[3.10, 3.14)`.
- `ensurepip`, `pyexpat`, `ssl`, and `venv` all import without error.
If no candidate qualifies, onboarding aborts and prints the real failure for each candidate.
This surfaces issues like Homebrew `python@3.14` whose `pyexpat` extension fails to dlopen against the older system `libexpat` on macOS.
To pin a specific interpreter, set `NEMOCLAW_MODEL_ROUTER_PYTHON` to its absolute path before running `nemoclaw onboard`:
```bash
NEMOCLAW_MODEL_ROUTER_PYTHON=/opt/homebrew/bin/python3.12 nemoclaw onboard
```
The pin is strict.
NemoClaw probes only that interpreter and aborts with the failure reason if it does not qualify, rather than silently falling back to a different python on `PATH`.
NemoClaw rejects relative command names such as `python3.12`.
Use `command -v python3.12` to find the absolute path.
If `python -m venv` itself fails for a probe-clean interpreter (for example, a corrupt ensurepip seed), NemoClaw retries with the next healthy candidate when no pin is set; with a pin set, the failure stops onboarding so you can fix or repoint the pinned python.
## Caveated Local Options
The following local inference options have caveats.
Local NIM and generic Linux managed vLLM install/start require `NEMOCLAW_EXPERIMENTAL=1`; DGX Spark and DGX Station managed vLLM entries appear by default.
An already-running vLLM server appears directly 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`, or a supported DGX Spark, DGX Station, or Linux NVIDIA GPU profile | Auto-detects the loaded model when vLLM is already running. Can install or start a managed vLLM container by default on DGX Spark/Station and after opt-in on generic Linux NVIDIA GPU hosts. |
For setup instructions, refer to [Use a Local Inference Server](../SKILL.md).
## Validation
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.
The wizard retries transient upstream validation failures before it 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.
| Provider type | Validation method |
|---|---|
| OpenAI | Tries `/responses` first, then `/chat/completions`. |
| NVIDIA Endpoints | Validates through `/v1/chat/completions` only; NemoClaw skips the `/v1/responses` probe because NVIDIA Build does not expose `/v1/responses` (returns 404 for every model). |
| Google Gemini | Validates through Gemini's OpenAI-compatible chat-completions path only; NemoClaw skips the `/v1/responses` probe because Gemini does not support the Responses API. |
| Other OpenAI-compatible endpoint | Tries `/v1/responses` first with a tool-calling probe; falls back to `/v1/chat/completions`. Selected runtime API defaults to `/v1/chat/completions`; set `NEMOCLAW_PREFERRED_API=openai-responses` to allow `/v1/responses` at runtime when validation succeeds. |
| 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 tries `/v1/responses` first then falls back to `/v1/chat/completions`; the selected runtime API defaults to `/v1/chat/completions`. Set `NEMOCLAW_PREFERRED_API=openai-responses` to allow `/v1/responses` at runtime when validation succeeds. |
| Local NVIDIA NIM | Validates through `/v1/chat/completions` only; NemoClaw skips the `/v1/responses` probe (same as NVIDIA Endpoints). |
## Setup Details for Local and Compatible Providers
The sections below collect the detailed setup prompts and environment variables for local and compatible inference providers.
Use them when the quickstart or local inference guide points you here for exact command shapes.
## OpenAI-Compatible Server
This option works with any server that implements `/v1/chat/completions`, including vLLM, TensorRT-LLM, llama.cpp, LocalAI, and others.
For compatible endpoints, NemoClaw uses `/v1/chat/completions` by default.
This avoids a class of failures where local backends accept `/v1/responses` requests but silently drop the system prompt and tool definitions.
To opt in to `/v1/responses`, set `NEMOCLAW_PREFERRED_API=openai-responses` before running onboard.
Start your model server.
The examples below use vLLM, but any OpenAI-compatible server works.
```bash
vllm serve meta-llama/Llama-3.1-8B-Instruct --port 8000
```
Run the onboard wizard.
```bash
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.
The wizard probes `/v1/chat/completions` by default for the compatible-endpoint provider.
If you set `NEMOCLAW_PREFERRED_API=openai-responses`, NemoClaw probes `/v1/responses` instead and only selects it when the response includes the streaming events OpenClaw requires.
If a reasoning model returns only reasoning content before producing a final answer, NemoClaw retries the smoke request with a larger response budget.
Route, configuration, and authentication failures still fail immediately.
### Non-Interactive Setup
Set the following environment variables for scripted or CI/CD deployments.
```bash
NEMOCLAW_PROVIDER=custom \
NEMOCLAW_ENDPOINT_URL=http://localhost:8000/v1 \
NEMOCLAW_MODEL=meta-llama/Llama-3.1-8B-Instruct \
COMPATIBLE_API_KEY=dummy \
nemoclaw onboard --non-interactive
```
| 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. |
### Selecting the API Path
For the compatible-endpoint provider, `/v1/chat/completions` is the default.
NemoClaw tests streaming events during onboarding and uses chat completions
without probing the Responses API.
To opt in to `/v1/responses`, set `NEMOCLAW_PREFERRED_API` before running onboard:
```bash
NEMOCLAW_PREFERRED_API=openai-responses nemoclaw onboard
```
The wizard then probes `/v1/responses` and only selects it when streaming
support is complete.
If the probe fails, the wizard falls back to `/v1/chat/completions`
automatically.
You can use this variable in both interactive and non-interactive mode.
| Variable | Values | Default |
|---|---|---|
| `NEMOCLAW_PREFERRED_API` | `openai-completions`, `openai-responses` | `openai-completions` for compatible endpoints |
If you already onboarded and the sandbox is failing at runtime, re-run `nemoclaw onboard` to re-probe the endpoint and bake the correct API path
into the image.
Refer to [Switch Inference Models](switch-inference-providers.md) for more information.
## Anthropic-Compatible Server
If your local server implements the Anthropic Messages API (`/v1/messages`), choose **Other Anthropic-compatible endpoint** during onboarding instead.
```bash
nemoclaw onboard
```
For non-interactive setup, use `NEMOCLAW_PROVIDER=anthropicCompatible` and set `COMPATIBLE_ANTHROPIC_API_KEY`.
```bash
NEMOCLAW_PROVIDER=anthropicCompatible \
NEMOCLAW_ENDPOINT_URL=http://localhost:8080 \
NEMOCLAW_MODEL=my-model \
COMPATIBLE_ANTHROPIC_API_KEY=dummy \
nemoclaw onboard --non-interactive
```
## vLLM
When vLLM is already running on `localhost:8000`, NemoClaw can detect it automatically and query the `/v1/models` endpoint to determine the loaded model.
On supported Linux hosts with NVIDIA GPUs, the onboard wizard can also install or start a managed vLLM container for you.
For an already-running vLLM server, run `nemoclaw onboard` and select **Local vLLM [experimental]** from the provider list.
If vLLM is already running, NemoClaw detects the running model and validates the endpoint.
When vLLM exposes runtime metadata such as `max_model_len`, NemoClaw uses that value for the `contextWindow` baked into `openclaw.json` unless you set `NEMOCLAW_CONTEXT_WINDOW` yourself.
If vLLM is not running and your host matches a DGX Spark or DGX Station managed profile, NemoClaw shows the **Install vLLM** or **Start vLLM** entry by default.
Generic Linux NVIDIA GPU hosts still require `NEMOCLAW_EXPERIMENTAL=1` or `NEMOCLAW_PROVIDER=install-vllm` before the managed entry appears.
NemoClaw pulls the vLLM image, downloads model weights into `~/.cache/huggingface`, starts the `nemoclaw-vllm` container on `localhost:8000`, streams Hugging Face download progress, and polls `/v1/models` until the model is ready.
Managed DGX Spark and DGX Station profiles use the stable NGC `nvcr.io/nvidia/vllm:26.05.post1-py3` container image.
If Docker pull output stops making progress, a watchdog stops the stalled pull instead of failing slow but active downloads on a fixed wall-clock timeout.
If vLLM never becomes ready, NemoClaw prints a short tail of the vLLM container logs before exiting.
The first run can take 10 to 30 minutes.
Later runs reuse the cached image and model weights.
Managed vLLM uses these profiles:
| Host profile | Default model |
|---|---|
| DGX Spark | `nvidia/Qwen3.6-35B-A3B-NVFP4` |
| DGX Station | `Qwen/Qwen3.6-27B-FP8` |
| Linux with an NVIDIA GPU | `nvidia/NVIDIA-Nemotron-3-Nano-4B-FP8` |
**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
Use an already-running vLLM server:
```bash
NEMOCLAW_PROVIDER=vllm \
nemoclaw onboard --non-interactive
```
Install or start managed vLLM when NemoClaw detects a supported profile.
On DGX Spark and DGX Station, `NEMOCLAW_PROVIDER=install-vllm` is enough for non-interactive runs; add `NEMOCLAW_EXPERIMENTAL=1` on generic Linux NVIDIA GPU hosts.
```bash
NEMOCLAW_PROVIDER=install-vllm \
nemoclaw onboard --non-interactive
```
NemoClaw records the model returned by vLLM's `/v1/models` endpoint.
Start vLLM with the model you want before onboarding if you manage the server yourself.
### Override the Managed-vLLM Model
Managed vLLM serves the profile default unless you select a different registry entry.
Export `NEMOCLAW_VLLM_MODEL=<slug>` before invoking the installer to choose a different model from the registry.
NemoClaw uses the matching `vllm serve` flags, including the reasoning parser, tool-call parser, and `--max-model-len`.
Recognized slugs are:
| Slug | Hugging Face model | Notes |
|---|---|---|
| `qwen3.6-27b` | `Qwen/Qwen3.6-27B-FP8` | Default on the DGX Station profile |
| `qwen3.6-35b-a3b-nvfp4` | `nvidia/Qwen3.6-35B-A3B-NVFP4` | Default on the DGX Spark profile |
| `nemotron-3-nano-4b` | `nvidia/NVIDIA-Nemotron-3-Nano-4B-FP8` | Default on the generic Linux + NVIDIA GPU profile |
| `deepseek-v4-flash` | `deepseek-ai/DeepSeek-V4-Flash` | Supported override |
| `deepseek-r1-distill-70b` | `deepseek-ai/DeepSeek-R1-Distill-Llama-70B` | Gated. Requires Hugging Face license acceptance |
The slug is case-insensitive; the full Hugging Face id is also accepted.
An unrecognized value fails fast with a list of valid slugs.
Gated models require a Hugging Face token; export it before onboarding so NemoClaw can forward it into the managed vLLM container:
```bash
export HF_TOKEN=<your-hf-token>
NEMOCLAW_PROVIDER=install-vllm \
NEMOCLAW_VLLM_MODEL=deepseek-r1-distill-70b \
nemoclaw onboard --non-interactive
```
NemoClaw accepts `HUGGING_FACE_HUB_TOKEN` as an alternative.
The token check runs on the host before any docker pull, so a missing or empty token aborts onboarding before bandwidth is spent on a 401.
## 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.
```bash
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.
On hosts with mixed NVIDIA GPU models, the preflight summary shows each detected GPU model and the total VRAM so you can confirm which device class the model selection used.
On Docker 29.x or containerd image-store hosts, NemoClaw resolves the host-platform manifest digest before pulling multi-architecture NIM images when the registry exposes an index.
It pulls `repo@digest` and retags the local image so NGC attestation metadata on other architectures does not block the selected platform.
If the registry does not expose a matching index, NemoClaw falls back to the tag pull.
NVIDIA hosts NIM container images on `nvcr.io`, and `docker pull` requires NGC registry authentication.
If Docker is not already logged in to `nvcr.io`, onboard prompts for an [NGC API key](https://org.ngc.nvidia.com/setup/api-key) and runs `docker login nvcr.io` over `--password-stdin` so the key is never written to disk or shell history.
The prompt masks the key during input and retries one time on a bad key before failing.
In non-interactive mode, onboard exits with login instructions if Docker is not already authenticated; run `docker login nvcr.io` yourself, then re-run `nemoclaw onboard --non-interactive`.
If `NGC_API_KEY` or `NVIDIA_API_KEY` is already exported, NemoClaw passes it into the managed NIM container through the process environment instead of command-line arguments.
If the NIM container exits before the health endpoint becomes ready, onboarding stops early and prints the last container log lines.
After NIM becomes healthy, NemoClaw reads `/v1/models` and uses the served model id for validation when it differs from the catalog name.
Unsafe served ids are rejected instead of being written into the sandbox config.
**Note:**
NIM uses vLLM internally.
The same `chat/completions` API path restriction applies.
## Timeout Configuration
Local inference requests use a default timeout of 180 seconds.
Large prompts on hardware such as DGX Spark can exceed shorter timeouts, so NemoClaw sets a higher default for Ollama, vLLM, NIM, and compatible-endpoint setup.
To override the timeout, set the `NEMOCLAW_LOCAL_INFERENCE_TIMEOUT` environment variable before onboarding:
```bash
export NEMOCLAW_LOCAL_INFERENCE_TIMEOUT=300
nemoclaw onboard
```
The value is in seconds.
NemoClaw bakes this setting into the sandbox at build time.
Changing it after onboarding requires re-running `nemoclaw onboard`.
`NEMOCLAW_LOCAL_INFERENCE_TIMEOUT` only governs the inference-server validation probe.
During local Ollama setup, NemoClaw treats host-side curl process timeouts as retryable probe failures and retries with a larger timeout before it reports a validation failure.
NemoClaw also retries Docker runtime detection with a longer `docker info` timeout before it chooses the local inference route.
The post-create readiness wait (image build, gateway upload, in-sandbox boot) has its own budget, `NEMOCLAW_SANDBOX_READY_TIMEOUT`, also defaulting to 180 seconds.
On hosts where the sandbox image takes minutes to build or upload, raise both settings together.
Examples include large quantized models, DGX Station first runs, and remote VMs over a slow link.
```bash
export NEMOCLAW_LOCAL_INFERENCE_TIMEOUT=300
export NEMOCLAW_SANDBOX_READY_TIMEOUT=600
nemoclaw onboard
```
If onboard ends with `Sandbox '<name>' was created but did not become ready within 180s`, refer to Troubleshooting (use the `nemoclaw-user-reference` skill).
## Next Steps
- [Use a Local Inference Server](../SKILL.md) for Ollama, vLLM, NIM, and compatible-endpoint setup details.
<AgentOnly variant="openclaw">
- [Tool-Calling Reliability](tool-calling-reliability.md) for deciding when Ollama is enough and when vLLM with a parser is safer.
</AgentOnly>
- [Switch Inference Models](switch-inference-providers.md) for changing the model at runtime without re-onboarding.

118
skills/nemoclaw-user-configure-inference/references/set-up-sub-agent.md
View file

@ -1,118 +0,0 @@
# Set Up Task-Specific Sub-Agents
OpenClaw documents the sub-agent behavior, `sessions_spawn` tool, `agents.list` configuration, tool policy, nesting, and auth model in [Sub-Agents](https://docs.openclaw.ai/tools/subagents).
Use that page as the source of truth for how OpenClaw sub-agents work.
This NemoClaw page covers the sandbox-specific pieces: where the OpenClaw config lives, where to put per-agent credentials, which writable workspace path agents should use, and how the Omni VLM demo maps onto those paths.
## NemoClaw Sandbox Paths
NemoClaw runs OpenClaw inside an OpenShell sandbox.
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 the file is root-owned and read-only. |
| `/sandbox/.openclaw/agents/<agent-id>/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. |
For file-based tasks, instruct agents to use `/sandbox/.openclaw/workspace/`.
Avoid relying on legacy `.openclaw-data` paths or read-only OpenClaw paths in delegation instructions.
## Omni Vision Sub-Agent Example
The [`vlm-demo`](https://github.com/brevdev/nemoclaw-demos/tree/main/vlm-demo) applies the OpenClaw sub-agent pattern to a vision task.
It keeps the primary `main` agent on the normal NemoClaw inference route and adds a `vision-operator` sub-agent backed by an Omni vision model.
| OpenClaw field | Omni example value |
|---|---|
| Primary agent | `main` |
| Primary model | `inference/nvidia/nemotron-3-super-120b-a12b` |
| Auxiliary provider | `nvidia-omni` |
| Sub-agent | `vision-operator` |
| Sub-agent model | `nvidia-omni/private/nvidia/nemotron-3-nano-omni-reasoning-30b-a3b` |
| Delegation tool | `sessions_spawn` |
The sub-agent uses Omni as the specialist model for image tasks.
The primary orchestration model remains responsible for conversation, planning, and deciding when to delegate.
## Update the Sandbox Config
Fetch the current OpenClaw config from the sandbox, patch it with your auxiliary provider and `agents.list` changes, then upload it back.
```bash
export SANDBOX=my-assistant
export DOCKER_CTR=openshell-cluster-nemoclaw
docker exec "$DOCKER_CTR" kubectl exec -n openshell "$SANDBOX" -c agent -- cat /sandbox/.openclaw/openclaw.json > /tmp/openclaw.json
```
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; lock the config root-owned and read-only afterward if the sandbox should enforce config integrity at startup.
```bash
docker exec "$DOCKER_CTR" kubectl exec -n openshell "$SANDBOX" -c agent -- chmod 644 /sandbox/.openclaw/openclaw.json
docker exec "$DOCKER_CTR" kubectl exec -n openshell "$SANDBOX" -c agent -- chmod 644 /sandbox/.openclaw/.config-hash
cat /tmp/openclaw.updated.json | docker exec -i "$DOCKER_CTR" kubectl exec -i -n openshell "$SANDBOX" -c agent -- sh -c 'cat > /sandbox/.openclaw/openclaw.json'
docker exec "$DOCKER_CTR" kubectl exec -n openshell "$SANDBOX" -c agent -- /bin/bash -c "cd /sandbox/.openclaw && sha256sum openclaw.json > .config-hash"
docker exec "$DOCKER_CTR" kubectl exec -n openshell "$SANDBOX" -c agent -- chmod 444 /sandbox/.openclaw/openclaw.json
docker exec "$DOCKER_CTR" kubectl exec -n openshell "$SANDBOX" -c agent -- chmod 444 /sandbox/.openclaw/.config-hash
```
Check `/tmp/gateway.log` after upload and confirm the gateway hot-reloaded the provider or `agents.list` change.
## Add Sub-Agent Credentials
If the auxiliary model uses a provider key outside the normal NemoClaw inference route, put that key in the sub-agent auth profile.
For the Omni example:
```text
/sandbox/.openclaw/agents/vision-operator/agent/auth-profiles.json
```
Use the same provider ID that appears in `models.providers`, such as `nvidia-omni`.
After uploading the auth profile, make sure the sandbox user owns the sub-agent directory:
```bash
docker exec "$DOCKER_CTR" kubectl exec -n openshell "$SANDBOX" -c agent -- chown -R sandbox:sandbox /sandbox/.openclaw/agents/vision-operator
```
## Allow Auxiliary Provider Egress
If the sub-agent calls a provider directly, update the OpenShell network policy for the binary that makes the request.
In the Omni demo, the OpenClaw gateway runs as `/usr/local/bin/node`, so the NVIDIA endpoint policy must allow that binary.
Refer to Customize the Network Policy (use the `nemoclaw-user-manage-policy` skill) for policy update workflows.
## Add Delegation Instructions
OpenClaw handles `sessions_spawn`, but the primary agent still needs task instructions.
Place those instructions in the writable workspace, for example:
```text
/sandbox/.openclaw/workspace/TOOLS.md
```
The Omni demo includes `vlm-demo/vlm-subagent/TOOLS.md`, which tells `main` to delegate image tasks to `vision-operator` and tells the sub-agent to read the image path it receives.
Adapt that file for other task-specific models.
## Demo Assets
Use the [`vlm-demo`](https://github.com/brevdev/nemoclaw-demos/tree/main/vlm-demo) repository for runnable Omni example assets:
- `vlm-subagent-guide.md` for a command-by-command walkthrough.
- `vlm-subagent/openclaw-patch.py` for patching `openclaw.json`.
- `vlm-subagent/auth-profiles.template.json` for the sub-agent auth profile.
- `vlm-subagent/TOOLS.md` for delegation instructions.
## Next Steps
Use the following resources for more information:
- Refer to [OpenClaw Sub-Agents](https://docs.openclaw.ai/tools/subagents) for `sessions_spawn`, `agents.list`, nesting, tool policy, and auth behavior.
- Refer to [Switch Inference Providers](switch-inference-providers.md) to change the primary orchestration model instead of adding a sub-agent model.
- Refer to Workspace Files (use the `nemoclaw-user-manage-sandboxes` skill) to understand per-agent workspace directories.

284
skills/nemoclaw-user-configure-inference/references/switch-inference-providers.md
View file

@ -1,284 +0,0 @@
# Switch Inference Models at Runtime
import { AgentOnly } from "../_components/AgentGuide";
Change the active inference model while the sandbox is running.
You do not need to restart the sandbox.
## Prerequisites
- A running NemoClaw sandbox.
- The OpenShell CLI on your `PATH`, which NemoClaw uses under the hood.
## Switch to a Different Model
<AgentOnly variant="openclaw">
Use `nemoclaw inference set` with the provider and model that match the upstream you want to use.
The command updates the OpenShell inference route and synchronizes the running agent config.
For OpenClaw, it updates `agents.defaults.model.primary` and the matching provider namespace.
</AgentOnly>
<AgentOnly variant="hermes">
Use `nemoclaw inference set` with the provider and model that match the upstream you want to use.
The command updates the OpenShell inference route and synchronizes the running agent config.
For Hermes, it updates `/sandbox/.hermes/config.yaml` (`model.default`, `model.base_url`, `model.provider: custom`, API-family mode when needed, and the OpenShell proxy API-key placeholder) without rebuilding or restarting Hermes.
Pass `--sandbox <name>` when you do not want to use the default registered sandbox.
Under `nemoclaw`, pass `--sandbox <name>` when you have registered more than one Hermes sandbox.
</AgentOnly>
<AgentOnly variant="openclaw">
Pass `--sandbox <name>` when you do not want to use the default registered sandbox.
</AgentOnly>
### NVIDIA Endpoints
```bash
nemoclaw inference set --provider nvidia-prod --model nvidia/nemotron-3-super-120b-a12b
```
### OpenAI
```bash
nemoclaw inference set --provider openai-api --model gpt-5.4
```
### Anthropic
```bash
nemoclaw inference set --provider anthropic-prod --model claude-sonnet-4-6
```
### Google Gemini
```bash
nemoclaw inference set --provider gemini-api --model gemini-2.5-flash
```
### Compatible Endpoints
If you onboarded a custom compatible endpoint, switch models with the provider created for that endpoint:
```bash
nemoclaw inference set --provider compatible-endpoint --model <model-name>
```
```bash
nemoclaw inference set --provider compatible-anthropic-endpoint --model <model-name>
```
<AgentOnly variant="hermes">
### Hermes Provider
For a NemoClaw-managed Hermes sandbox, use the Hermes alias with the registered Hermes Provider route:
```bash
nemoclaw inference set --provider hermes-provider --model openai/gpt-5.4-mini
```
</AgentOnly>
### API Family Sync
Before patching the in-sandbox config, NemoClaw resolves the target route's API family: OpenAI chat completions, Anthropic Messages, or OpenAI Responses.
For OpenClaw, `inference set` syncs the provider API family and primary model reference into the running config.
For Hermes, `inference set` writes `model.api_mode: anthropic_messages` for Anthropic Messages routes, `model.api_mode: codex_responses` for OpenAI Responses routes, and removes `api_mode` for OpenAI-style chat-completions routes.
Hermes also keeps `model.api_key` on the OpenShell proxy placeholder so dashboard and API sessions continue to authenticate through the gateway after a route change.
Amazon Bedrock Runtime routes created through `compatible-anthropic-endpoint` are the exception.
When you switch within the same Bedrock Runtime compatible provider, NemoClaw keeps the route OpenAI-compatible and does not set Hermes to Anthropic Messages mode.
#### Switching from Responses API to Chat Completions
If onboarding selected `/v1/responses` but the agent fails at runtime, re-run onboarding so the wizard re-probes the endpoint and bakes the correct API path into the image.
This can happen when the backend does not emit the streaming events OpenClaw requires.
```bash
nemoclaw onboard
```
Select the same provider and endpoint again.
The updated streaming probe detects incomplete `/v1/responses` support and selects `/v1/chat/completions` automatically.
For the compatible-endpoint provider, NemoClaw uses `/v1/chat/completions` by default, so you do not need an environment variable to keep the safe path.
To opt in to `/v1/responses` for a backend you have verified end to end, set `NEMOCLAW_PREFERRED_API` before onboarding:
```bash
NEMOCLAW_PREFERRED_API=openai-responses nemoclaw onboard
```
**Note:**
`NEMOCLAW_INFERENCE_API_OVERRIDE` patches the config at container startup but does not update the Dockerfile ARG baked into the image.
If you recreate the sandbox without the override environment variable, the image reverts to the original API path.
A fresh `nemoclaw onboard` is the reliable fix because it updates both the
session and the baked image.
## Cross-Provider Switching
<AgentOnly variant="openclaw">
Switching to a different provider family (for example, from NVIDIA Endpoints to Anthropic) also uses `nemoclaw inference set`.
The command updates both the gateway route and the OpenClaw provider namespace in the running sandbox config.
If the in-sandbox config sync fails after the gateway route is updated, NemoClaw keeps the host registry aligned with the gateway and prints a rebuild hint.
Run the rebuild before relying on the running agent if the warning says the image config could not be patched.
```bash
nemoclaw inference set --provider anthropic-prod --model claude-sonnet-4-6 --no-verify
```
</AgentOnly>
<AgentOnly variant="hermes">
Switching to a different provider family (for example, from NVIDIA Endpoints to Anthropic) also uses `nemoclaw inference set`.
The command updates both the gateway route and `/sandbox/.hermes/config.yaml`.
If the Hermes config sync fails after the gateway route is updated, NemoClaw keeps the host registry aligned with the gateway and prints a rebuild hint.
Run the rebuild before relying on the running agent if the warning says the image config could not be patched.
```bash
nemoclaw inference set --provider anthropic-prod --model claude-sonnet-4-6 --no-verify
```
</AgentOnly>
Use `--no-verify` only when OpenShell cannot verify the provider at switch time but you have already confirmed the provider and credential.
## Tune Model Metadata
The sandbox image bakes model metadata (context window, max output tokens, reasoning mode, and accepted input modalities) into `openclaw.json` at build time.
To change these values, set the corresponding environment variables before running `nemoclaw onboard` so they patch into the Dockerfile before the image builds.
| Variable | Values | Default |
|---|---|---|
| `NEMOCLAW_CONTEXT_WINDOW` | Positive integer (tokens) | `131072` |
| `NEMOCLAW_MAX_TOKENS` | Positive integer (tokens) | `4096` |
| `NEMOCLAW_REASONING` | `true` or `false` | `false` |
| `NEMOCLAW_INFERENCE_INPUTS` | `text` or `text,image` | `text` |
| `NEMOCLAW_AGENT_TIMEOUT` | Positive integer (seconds) | `600` |
| `NEMOCLAW_AGENT_HEARTBEAT_EVERY` | Go-style duration (`30m`, `1h`, `0m` to disable) | `unset` (OpenClaw default) |
NemoClaw ignores invalid values and bakes the default into the image.
For Local Ollama, onboarding loads the selected model first and uses Ollama's reported runtime context length when `NEMOCLAW_CONTEXT_WINDOW` is unset.
For local vLLM, onboarding uses the runtime `max_model_len` value when the server reports one and `NEMOCLAW_CONTEXT_WINDOW` is unset.
Use `NEMOCLAW_INFERENCE_INPUTS=text,image` only for a model that accepts image input through the selected provider.
During interactive onboarding, NemoClaw prompts for **Text only** or **Text + Image** when the discovered model name looks multimodal and `NEMOCLAW_INFERENCE_INPUTS` is not already valid.
Non-interactive onboarding uses the environment value or the default `text` setting.
```bash
export NEMOCLAW_CONTEXT_WINDOW=65536
export NEMOCLAW_MAX_TOKENS=8192
export NEMOCLAW_REASONING=true
export NEMOCLAW_INFERENCE_INPUTS=text,image
export NEMOCLAW_AGENT_TIMEOUT=1800
export NEMOCLAW_AGENT_HEARTBEAT_EVERY=0m
nemoclaw onboard
```
<AgentOnly variant="openclaw">
`NEMOCLAW_AGENT_TIMEOUT` controls the per-request inference timeout baked into `agents.defaults.timeoutSeconds`.
Increase it for slow local inference, such as CPU-only Ollama or vLLM on modest hardware.
NemoClaw writes this value into `openclaw.json` during onboarding.
The default sandbox can keep that file writable for agent state, but direct in-sandbox edits are not the supported or durable way to change NemoClaw-managed defaults.
Rebuild the sandbox with `nemoclaw onboard` to apply a new value.
</AgentOnly>
<AgentOnly variant="hermes">
`NEMOCLAW_AGENT_TIMEOUT` controls the per-request inference timeout baked into the Hermes sandbox image.
Increase it for slow local inference, such as CPU-only Ollama or vLLM on modest hardware.
Direct in-sandbox edits are not the supported or durable way to change NemoClaw-managed defaults.
Rebuild the sandbox with `nemoclaw onboard` to apply a new value.
</AgentOnly>
<AgentOnly variant="openclaw">
`NEMOCLAW_AGENT_HEARTBEAT_EVERY` sets `agents.defaults.heartbeat.every`.
This controls OpenClaw's periodic main-session agent turn.
Each interval, the agent wakes up to review follow-ups and read `HEARTBEAT.md` if present in the workspace.
The OpenClaw default is 30 minutes (1 hour for Anthropic OAuth / Claude CLI reuse).
Tune the cadence with a duration string like `5m` or `2h`, or set `0m` to disable the periodic turns entirely.
Disabling also drops `HEARTBEAT.md` from normal-run bootstrap context per upstream behavior, so the model no longer sees heartbeat-only instructions.
NemoClaw writes this value into `openclaw.json` during onboarding.
The in-sandbox `openclaw config set` command is not the supported path for NemoClaw-managed build-time defaults, and a rebuild overwrites direct file edits.
Rebuild the sandbox with `nemoclaw onboard --resume` to apply a new value.
</AgentOnly>
<AgentOnly variant="hermes">
Hermes does not use OpenClaw's `HEARTBEAT.md` wake-up mechanism.
Rebuild the sandbox with `nemoclaw onboard --resume` to apply build-time inference metadata changes.
</AgentOnly>
These variables are build-time settings.
If you change them on an existing sandbox, recreate the sandbox so the new values bake into the image:
```bash
nemoclaw onboard --resume --recreate-sandbox
```
## Verify the Active Model
Use `nemoclaw inference get` to print the provider and model the gateway is currently routing to.
Run it before `nemoclaw inference set` to confirm the starting state, or after a switch to verify the new route.
```bash
nemoclaw inference get
```
Expected output:
```text
Provider: nvidia-prod
Model: nvidia/nemotron-3-super-120b-a12b
```
Pass `--json` for machine-readable output.
```bash
nemoclaw inference get --json
```
Expected output:
```json
{
"provider": "nvidia-prod",
"model": "nvidia/nemotron-3-super-120b-a12b"
}
```
The command exits non-zero with `OpenShell inference route is not configured.` when the gateway has no registered inference route.
Run `nemoclaw onboard` to configure one.
Run the status command when you also need sandbox, service, and messaging health:
```bash
nemoclaw <name> status
```
The status output includes the active provider, model, and endpoint with the rest of the sandbox state.
## Notes
<AgentOnly variant="openclaw">
- The host keeps provider credentials.
- The sandbox continues to use `inference.local`.
- `nemoclaw inference set` patches the selected running OpenClaw or Hermes sandbox config and recomputes its config hash.
- Use `nemoclaw onboard --resume --recreate-sandbox` for build-time settings such as context window, max tokens, reasoning mode, heartbeat cadence, or image contents.
- Local Ollama and local vLLM routes use local provider tokens rather than `OPENAI_API_KEY`. Rebuilds of older local-inference sandboxes clear the stale OpenAI credential requirement automatically.
</AgentOnly>
<AgentOnly variant="hermes">
- The host keeps provider credentials.
- The sandbox continues to use `inference.local`.
- `nemoclaw inference set` patches the selected running Hermes sandbox config and recomputes its config hash.
- Use `nemoclaw onboard --resume --recreate-sandbox` for build-time settings such as context window, max tokens, reasoning mode, heartbeat cadence, or image contents.
- Local Ollama and local vLLM routes use local provider tokens rather than `OPENAI_API_KEY`. Rebuilds of older local-inference sandboxes clear the stale OpenAI credential requirement automatically.
</AgentOnly>
## Related Topics
- [Inference Options](inference-options.md) for the full list of providers available during onboarding.

154
skills/nemoclaw-user-configure-inference/references/tool-calling-reliability.md
View file

@ -1,154 +0,0 @@
# Tool-Calling Reliability for Local Inference
Local inference is useful for privacy, cost control, and offline development, but tool-calling agents place stricter demands on the model server than simple chat.
The model server must return structured `tool_calls`, not a JSON-looking string inside normal assistant text.
Use this page when the TUI shows raw JSON such as:
```json
{"arguments":{"query":"robotics"},"name":"memory_search"}
```
If that appears as text in the assistant reply, OpenClaw cannot dispatch the tool because the inference response did not include a structured tool call.
## Quick Choice Guide
| Workload | Ollama is usually sufficient | Prefer vLLM with a parser |
|---|---|---|
| Plain chat | Yes | Optional |
| Embeddings-only or retrieval setup | Yes | Optional |
| One simple tool with short prompts | Often | Optional |
| Agent loops with several tools | Risky | Yes |
| Long system prompts or sender metadata | Risky | Yes |
| Multi-turn tool dispatch | Risky | Yes |
Ollama can work well for lightweight local chat and some simple tool surfaces.
For OpenClaw-style agent loops with multiple tools, long instructions, or multi-turn dispatch, use a server that exposes OpenAI-compatible `/v1/chat/completions` with a tool-call parser.
vLLM is the common local choice.
## Symptom
The common failure mode is:
- The model emits text that looks like a tool call.
- The response does not include a structured `tool_calls` field.
- The gateway treats the response as normal text.
- No tool runs, and the user sees raw JSON in the TUI.
This is different from a network or policy block.
`nemoclaw <name> status`, `nemoclaw <name> logs`, and `nemoclaw debug --quick` can all look healthy while tool dispatch still fails inside the conversation.
### Nemotron Managed Inference
For the `nvidia/nemotron-3-super-120b-a12b` managed inference route on `inference.local`, NemoClaw disables OpenClaw's native code-based tool search surface.
That route otherwise tends to generate invalid JavaScript for the `tool_search_code` helper, which creates `[tools] tool_search_code failed` noise even when normal turns succeed.
The agent still uses the structured tool-calling surface that the model handles correctly.
## Recommended Fix
For persistent NemoClaw use, start vLLM with auto tool choice and the parser that matches your model family, then rerun onboarding and select **Local vLLM [experimental]** or **Other OpenAI-compatible endpoint**.
For Hermes 3 style models, a known-good vLLM command shape is:
```bash
vllm serve /models/Hermes-3-Llama-3.1-8B \
--served-model-name hermes-3-llama-3.1-8b \
--enable-auto-tool-choice \
--tool-call-parser hermes \
--port 8000
```
For a Docker Compose setup:
```yaml
services:
vllm-nemoclaw:
image: vllm/vllm-openai:latest
container_name: vllm-nemoclaw
restart: unless-stopped
ports:
- "8002:8000"
volumes:
- /path/to/models:/models:ro
- /path/to/hf-cache:/root/.cache/huggingface
ipc: host
deploy:
resources:
reservations:
devices:
- capabilities: [gpu]
count: all
command: >
--model /models/Hermes-3-Llama-3.1-8B
--served-model-name hermes-3-llama-3.1-8b
--enable-auto-tool-choice
--tool-call-parser hermes
--gpu-memory-utilization 0.20
--max-model-len 32768
--api-key ${VLLM_API_KEY}
```
Then onboard against that endpoint:
```bash
NEMOCLAW_PROVIDER=custom \
NEMOCLAW_ENDPOINT_URL=http://localhost:8002/v1 \
NEMOCLAW_MODEL=hermes-3-llama-3.1-8b \
COMPATIBLE_API_KEY=$VLLM_API_KEY \
nemoclaw onboard --non-interactive
```
If the endpoint does not require authentication, set `COMPATIBLE_API_KEY` to any non-empty placeholder, such as `dummy`.
## Advanced Temporary Repointing
NemoClaw-managed sandboxes normally block direct `openclaw config set` writes inside the sandbox because those edits do not survive rebuilds.
Prefer rerunning `nemoclaw onboard` for a persistent provider change.
If you are intentionally testing a mutable OpenClaw config, prepare a batch file
like this:
```json
{
"models": {
"providers": {
"vllm-local": {
"baseUrl": "http://host.openshell.internal:8002/v1",
"api": "openai",
"apiKey": "${VLLM_API_KEY}"
}
}
},
"agents": {
"defaults": {
"model": {
"primary": "vllm-local/hermes-3-llama-3.1-8b"
}
}
}
}
```
Apply it only in environments where OpenClaw allows config writes:
```bash
openclaw config set --batch-file /sandbox/.openclaw/vllm-tool-calls.json
```
After testing, persist the working provider through `nemoclaw onboard` so the sandbox image, OpenShell inference route, and host-managed credentials stay in sync.
## Verify the Fix
After switching to vLLM, ask for an action that should use a tool. Good signs:
- The TUI does not show JSON blobs as assistant text.
- The gateway log shows tool dispatch and a follow-up answer.
- `nemoclaw <name> status` reports the local vLLM or compatible endpoint as the active provider.
If JSON still appears as text, confirm that you started vLLM with both `--enable-auto-tool-choice` and the correct `--tool-call-parser` value for your model.
## Next Steps
- [Use a Local Inference Server](../SKILL.md)
- [Inference Options](inference-options.md)
- [Switch Inference Models](switch-inference-providers.md)

51
skills/nemoclaw-user-configure-inference/skill-card.md
View file

@ -1,51 +0,0 @@
## Description: <br>
Connects NemoClaw to a local inference server such as Ollama, vLLM, TensorRT-LLM, NIM, or any OpenAI-compatible endpoint. <br>
This skill is ready for commercial/non-commercial use. <br>
## Owner
NVIDIA <br>
### License/Terms of Use: <br>
Apache 2.0 <br>
## Use Case: <br>
Developers and engineers configuring NemoClaw to route inference to a local model server for running AI agents inside OpenShell sandboxes. <br>
### Deployment Geography for Use: <br>
Global <br>
## Known Risks and Mitigations: <br>
Risk: Review before execution as proposals could introduce incorrect or misleading guidance into skills. <br>
Mitigation: Review and scan skill before deployment. <br>
## Reference(s): <br>
- [Inference Options](references/inference-options.md) <br>
- [Set Up Sub-Agent](references/set-up-sub-agent.md) <br>
- [Switch Inference Providers](references/switch-inference-providers.md) <br>
- [Tool-Calling Reliability](references/tool-calling-reliability.md) <br>
## Skill Output: <br>
**Output Type(s):** [Configuration instructions, Shell commands] <br>
**Output Format:** [Markdown with inline bash code blocks] <br>
**Output Parameters:** [1D] <br>
**Other Properties Related to Output:** [None] <br>
## Evaluation Metrics Used: <br>
Reported benchmark dimensions: <br>
- Security: Checks whether skill-assisted execution avoids unsafe behavior such as secret leakage, destructive commands, or unauthorized access. <br>
- Correctness: Checks whether the agent follows the expected workflow and produces the correct final output. <br>
- Discoverability: Checks whether the agent loads the skill when relevant and avoids using it when irrelevant. <br>
- Effectiveness: Checks whether the agent performs measurably better with the skill than without it. <br>
- Efficiency: Checks whether the agent uses fewer tokens and avoids redundant work. <br>
## Skill Version(s): <br>
0.1.0 (source: package.json) <br>
## Ethical Considerations: <br>
NVIDIA believes Trustworthy AI is a shared responsibility and we have established policies and practices to enable development for a wide array of AI applications. When downloaded or used in accordance with our terms of service, developers should work with their internal team to ensure this skill meets requirements for the relevant industry and use case and addresses unforeseen product misuse. <br>
(For Release on NVIDIA Platforms Only) <br>
Please report quality, risk, security vulnerabilities or NVIDIA AI Concerns [here](https://app.intigriti.com/programs/nvidia/nvidiavdp/detail). <br>

1
skills/nemoclaw-user-configure-inference/skill.oms.sig
View file

File diff suppressed because one or more lines are too long

67
skills/nemoclaw-user-configure-security/BENCHMARK.md
View file

@ -1,67 +0,0 @@
# Evaluation Report
Evaluation of the `nemoclaw-user-configure-security` skill before publication through NVSkills-Eval.
This benchmark summarizes 3-Tier Evaluation from NVSkills-Eval results for the skill. The goal is to document whether the skill is safe, discoverable, effective, and useful for agents before it is published for broader workflow use.
## Evaluation Summary
- Skill: `nemoclaw-user-configure-security`
- Evaluation date: 2026-05-28
- NVSkills-Eval profile: `external`
- Overall verdict: FAIL
- Tier 3 live agent evaluation: not available in this report
## Agents Used
- Tier 3 agent details were not available in this report.
## Metrics Used
Reported benchmark dimensions:
- Security: checks whether skill-assisted execution avoids unsafe behavior such as secret leakage, destructive commands, or unauthorized access.
- Correctness: checks whether the agent follows the expected workflow and produces the correct final output.
- Discoverability: checks whether the agent loads the skill when relevant and avoids using it when irrelevant.
- Effectiveness: checks whether the agent performs measurably better with the skill than without it.
- Efficiency: checks whether the agent uses fewer tokens and avoids redundant work.
Underlying evaluation signals used in this run:
- No Tier 3 evaluation signal details were available in this report.
## Test Tasks
Tier 3 evaluation task details were not available in this report.
## Results
Tier 3 dimension rollup was not available in this report.
## Tier 1: Static Validation Summary
Tier 1 validation passed with observations. NVSkills-Eval ran 9 checks and found 15 total findings.
Top findings:
- MEDIUM QUALITY/quality_correctness: Guide-only skill has very little content (12 lines) (`skills/nemoclaw-user-configure-security/SKILL.md`)
- MEDIUM QUALITY/quality_correctness: SKILL_SPEC recommended field missing: 'metadata.author' (`skills/nemoclaw-user-configure-security/SKILL.md`)
- MEDIUM QUALITY/quality_correctness: SKILL_SPEC recommended field missing: 'metadata.tags' (`skills/nemoclaw-user-configure-security/SKILL.md`)
- MEDIUM QUALITY/quality_efficiency: Deeply nested references in credential-storage.md (`skills/nemoclaw-user-configure-security/SKILL.md`)
- MEDIUM SCHEMA/body_recommended_section: Missing recommended section: '## Instructions' (`skills/nemoclaw-user-configure-security/SKILL.md`)
## Tier 2: Deduplication Summary
Tier 2 validation reported findings. NVSkills-Eval ran 2 checks and found 1 total findings.
Top findings:
- HIGH DUPLICATE/duplicate: Duplicate content found across SKILL.md and references/best-practices.md and references/credential-storage.md and references/openclaw-controls.md:
"(preamble)" in SKILL.md (lines 1-3)
vs "(preamble)" in references/best-practices.md (lines 1-2)
vs "(preamble)" in references/credential-storage.md (lines 1-2)
vs "(preamble)" in references/openclaw-controls.md (lines 1-2) (`SKILL.md:1`)
## Publication Recommendation
The skill should be reviewed before NVSkills-Eval publication. Skill owners should address the findings above and rerun NVSkills-Eval to refresh this benchmark.

16
skills/nemoclaw-user-configure-security/SKILL.md
View file

@ -1,16 +0,0 @@
---
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. Trigger keywords - nemoclaw security best practices, sandbox security controls risk framework, nemoclaw credential storage, openshell provider, api key security, openclaw security controls, nemoclaw security boundary, prompt injection, tool access control."
license: "Apache-2.0"
---
<!-- SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. -->
<!-- SPDX-License-Identifier: Apache-2.0 -->
# NemoClaw Security Best Practices: Controls, Risks, and Posture Profiles
## References
- **Load [references/best-practices.md](references/best-practices.md)** when evaluating security posture, reviewing sandbox security defaults, or assessing control trade-offs. Presents a risk framework for every configurable security control in NemoClaw.
- **Load [references/openclaw-controls.md](references/openclaw-controls.md)** when reviewing the security boundary between NemoClaw and OpenClaw or assessing what NemoClaw does not cover. Lists OpenClaw security controls that operate independently of NemoClaw, including prompt injection detection, tool access control, rate limiting, environment variable policy, audit framework, supply chain scanning, messaging access policy, context visibility, and safe regex.
- **Load [references/credential-storage.md](references/credential-storage.md)** when reviewing how credentials are handled, locating a stored credential, or assessing the storage threat model. Covers where NemoClaw stores provider credentials, why nothing is persisted to host disk, and how the OpenShell gateway acts as the single system of record.

56
skills/nemoclaw-user-configure-security/evals/evals.json
View file

@ -1,56 +0,0 @@
[
{
"id": "docs-security-best-practices-001",
"question": "I'm evaluating NemoClaw security best practices. Help me understand the risk posture of each configurable control so I can justify the setup to my team or security reviewers.",
"expected_skill": "nemoclaw-user-configure-security",
"ground_truth": "A NemoClaw-specific answer that helps the user understand the risk posture of each configurable control and gives enough concrete guidance, decision criteria, verification steps, or risk framing to justify the setup to my team or security reviewers."
},
{
"id": "docs-security-best-practices-002",
"question": "I'm balancing developer convenience with lockdown. Help me compare the trade-offs of changing security controls so I can choose a posture that fits the environment.",
"expected_skill": "nemoclaw-user-configure-security",
"ground_truth": "A NemoClaw-specific answer that helps the user compare the trade-offs of changing security controls and gives enough concrete guidance, decision criteria, verification steps, or risk framing to choose a posture that fits the environment."
},
{
"id": "docs-security-best-practices-003",
"question": "I'm preparing for production-like use. Help me see which defaults are acceptable and which require changes so I can avoid shipping with accidental weak spots.",
"expected_skill": "nemoclaw-user-configure-security",
"ground_truth": "A NemoClaw-specific answer that helps the user see which defaults are acceptable and which require changes and gives enough concrete guidance, decision criteria, verification steps, or risk framing to avoid shipping with accidental weak spots."
},
{
"id": "docs-security-credential-storage-001",
"question": "I'm inspecting NemoClaw credential storage. Help me verify how secrets are stored and protected so I can decide whether the setup meets my secret-handling expectations.",
"expected_skill": "nemoclaw-user-configure-security",
"ground_truth": "A NemoClaw-specific answer that helps the user verify how secrets are stored and protected and gives enough concrete guidance, decision criteria, verification steps, or risk framing to decide whether the setup meets my secret-handling expectations."
},
{
"id": "docs-security-credential-storage-002",
"question": "I'm tracing where credentials live. Help me distinguish host, gateway, and sandbox storage boundaries so I can avoid assuming secrets are available in the wrong place.",
"expected_skill": "nemoclaw-user-configure-security",
"ground_truth": "A NemoClaw-specific answer that helps the user distinguish host, gateway, and sandbox storage boundaries and gives enough concrete guidance, decision criteria, verification steps, or risk framing to avoid assuming secrets are available in the wrong place."
},
{
"id": "docs-security-credential-storage-003",
"question": "I'm rotating or inspecting credentials. Help me follow a workflow that does not print secrets in logs or docs so I can recover or update access safely.",
"expected_skill": "nemoclaw-user-configure-security",
"ground_truth": "A NemoClaw-specific answer that helps the user follow a workflow that does not print secrets in logs or docs and gives enough concrete guidance, decision criteria, verification steps, or risk framing to recover or update access safely."
},
{
"id": "docs-security-openclaw-controls-001",
"question": "I'm reading about controls outside NemoClaw's scope. Help me understand which security responsibilities remain with OpenClaw so I can avoid treating sandbox isolation as a complete application security model.",
"expected_skill": "nemoclaw-user-configure-security",
"ground_truth": "A NemoClaw-specific answer that helps the user understand which security responsibilities remain with OpenClaw and gives enough concrete guidance, decision criteria, verification steps, or risk framing to avoid treating sandbox isolation as a complete application security model."
},
{
"id": "docs-security-openclaw-controls-002",
"question": "I'm assessing application-layer agent risk. Help me identify the controls NemoClaw does not add so I can plan separate mitigations for authentication, prompt handling, and agent behavior.",
"expected_skill": "nemoclaw-user-configure-security",
"ground_truth": "A NemoClaw-specific answer that helps the user identify the controls NemoClaw does not add and gives enough concrete guidance, decision criteria, verification steps, or risk framing to plan separate mitigations for authentication, prompt handling, and agent behavior."
},
{
"id": "docs-security-openclaw-controls-003",
"question": "I'm documenting the security boundary. Help me explain where NemoClaw protection ends so I can set accurate expectations for reviewers and operators.",
"expected_skill": "nemoclaw-user-configure-security",
"ground_truth": "A NemoClaw-specific answer that helps the user explain where NemoClaw protection ends and gives enough concrete guidance, decision criteria, verification steps, or risk framing to set accurate expectations for reviewers and operators."
}
]

511
skills/nemoclaw-user-configure-security/references/best-practices.md
View file

@ -1,511 +0,0 @@
<!-- SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. -->
<!-- SPDX-License-Identifier: Apache-2.0 -->
# NemoClaw Security Best Practices: Controls, Risks, and Posture Profiles
NemoClaw ships with deny-by-default security controls across four layers: network, filesystem, process, and inference.
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 (use the `nemoclaw-user-overview` skill).
## Protection Layers at a Glance
NemoClaw enforces security at four layers.
NemoClaw locks some when it creates the sandbox and requires a restart to change them.
You can hot-reload others while the sandbox runs.
The following diagram shows the default posture immediately after `nemoclaw onboard`, before you approve any endpoints or apply any presets.
```mermaid
flowchart TB
subgraph HOST["Your Machine: default posture after nemoclaw onboard"]
direction TB
YOU["👤 Operator"]
subgraph NC["NemoClaw + OpenShell"]
direction TB
subgraph SB["Sandbox: the agent's isolated world"]
direction LR
PROC["⚙️ Process Layer<br/>Controls what the agent can execute"]
FS["📁 Filesystem Layer<br/>Controls what the agent can read and write"]
AGENT["🤖 Agent"]
end
subgraph GW["Gateway: the gatekeeper"]
direction LR
NET["🌐 Network Layer<br/>Controls where the agent can connect"]
INF["🧠 Inference Layer<br/>Controls which AI models the agent can use"]
end
end
end
OUTSIDE["🌍 Outside World<br/>Internet · AI Providers · APIs"]
AGENT -- "all requests" --> GW
GW -- "approved only" --> OUTSIDE
YOU -. "approve / deny" .-> GW
classDef agent fill:#76b900,stroke:#5a8f00,color:#fff,stroke-width:2px,font-weight:bold
classDef locked fill:#1a1a1a,stroke:#76b900,color:#fff,stroke-width:2px
classDef hot fill:#333,stroke:#76b900,color:#e6f2cc,stroke-width:2px
classDef external fill:#f5f5f5,stroke:#ccc,color:#1a1a1a,stroke-width:1px
classDef operator fill:#fff,stroke:#76b900,color:#1a1a1a,stroke-width:2px,font-weight:bold
class AGENT agent
class PROC,FS locked
class NET,INF hot
class OUTSIDE external
class YOU operator
style HOST fill:none,stroke:#76b900,stroke-width:2px,color:#1a1a1a
style NC fill:none,stroke:#76b900,stroke-width:1px,stroke-dasharray:5 5,color:#1a1a1a
style SB fill:#f5faed,stroke:#76b900,stroke-width:2px,color:#1a1a1a
style GW fill:#2a2a2a,stroke:#76b900,stroke-width:2px,color:#fff
```
| Layer | What it protects | Enforcement point | Changeable at runtime |
| --- | --- | --- | --- |
| Network | Unauthorized outbound connections and data exfiltration. | OpenShell gateway | Yes. Use `openshell policy set` or operator approval. |
| Filesystem | System binary tampering, credential theft, config manipulation. | Landlock LSM + container mounts | Landlock layout: no. Requires sandbox re-creation. Use host-side NemoClaw commands for durable config changes. |
| Process | Privilege escalation, fork bombs, syscall abuse. | Container runtime (Docker/K8s `securityContext`) | No. Requires sandbox re-creation. |
| Inference | Credential exposure, unauthorized model access, cost overruns. | OpenShell gateway | Yes. Use `nemoclaw inference set`. |
## Network Controls
NemoClaw controls which hosts, ports, and HTTP methods the sandbox can reach, and lets operators approve or deny requests in real time.
### Deny-by-Default Egress
The sandbox blocks all outbound connections unless you explicitly list the endpoint in the policy file `nemoclaw-blueprint/policies/openclaw-sandbox.yaml`.
| Aspect | Detail |
|---|---|
| Default | All egress denied. Only endpoints in the baseline policy can receive traffic. |
| What you can change | Add endpoints to the policy file (static) or with `openshell policy set` (dynamic). |
| Risk if relaxed | Each allowed endpoint is a potential data exfiltration path. The agent can send workspace content, credentials, or conversation history to any reachable host. |
| Recommendation | Add only endpoints the agent needs for its task. Prefer operator approval for one-off requests over permanently widening the baseline. |
### Binary-Scoped Endpoint Rules
Each network policy entry restricts which executables can reach the endpoint using the `binaries` field.
OpenShell identifies the calling binary by reading `/proc/<pid>/exe` (the kernel-trusted executable path, not `argv[0]`), walking the process tree for ancestor binaries, and computing a SHA256 hash of each binary on first use.
If someone replaces a binary while the sandbox runs, the hash mismatch triggers an immediate deny.
| Aspect | Detail |
|---|---|
| Default | Each endpoint restricts access to specific binaries. For example, the `github` preset restricts access so only `/usr/bin/git` can reach `github.com`. Binary paths support glob patterns (`*` matches one path component, `**` matches recursively). |
| What you can change | Add binaries to an endpoint entry, or omit the `binaries` field to allow any executable. |
| Risk if relaxed | Removing binary restrictions lets any process in the sandbox reach the endpoint. An agent could use `curl`, `wget`, or a Python script to exfiltrate data to an allowed host, bypassing the intended usage pattern. |
| Recommendation | Always scope endpoints to the binaries that need them. If the agent needs a host from a new binary, add that binary explicitly rather than removing the restriction. |
### Path-Scoped HTTP Rules
Endpoint rules restrict allowed HTTP methods and URL paths.
| Aspect | Detail |
|---|---|
| Default | Some endpoints allow GET and POST on `/**` (for example, `clawhub.ai`). Others restrict methods and paths to specific API routes (for example, `integrate.api.nvidia.com` allows POST only to inference and embedding paths and GET to model listings). Read-only endpoints such as `docs.openclaw.ai`, the `npm_registry` baseline entry, and the `pypi` preset allow GET only (PyPI also allows HEAD). The `npm` preset is an intentional exception: npm/Yarn registry traffic uses L4 pass-through for Node 22 undici CONNECT compatibility. |
| What you can change | Add methods (PUT, DELETE, PATCH) or restrict paths to specific prefixes. |
| Risk if relaxed | Allowing all methods on an API endpoint gives the agent write and delete access. For example, allowing DELETE on `api.github.com` lets the agent delete repositories. |
| Recommendation | Use GET-only rules for endpoints that the agent only reads. Add write methods only for endpoints where the agent must create or modify resources. Restrict paths to specific API routes when possible. |
### L4-Only vs L7 Inspection (`protocol` Field)
All sandbox egress goes through OpenShell's CONNECT proxy.
The `protocol` field on an endpoint controls whether the proxy also inspects individual HTTP requests inside the tunnel.
| Aspect | Detail |
|---|---|
| Default | Endpoints without a `protocol` field use L4-only enforcement: the proxy checks host, port, and binary identity, then relays the TCP stream without inspecting payloads. Setting `protocol: rest` enables L7 inspection: the proxy auto-detects and terminates TLS, then evaluates each HTTP request's method and path against the endpoint's `rules` or `access` preset. |
| What you can change | Add `protocol: rest` to an endpoint to enable per-request HTTP inspection. Use the `access` preset (`full`, `read-only`, `read-write`) or explicit `rules` to control allowed methods and paths. |
| Risk if relaxed | L4-only endpoints (no `protocol` field) allow the agent to send any data through the tunnel after the initial connection is permitted. The proxy cannot see or filter the HTTP method, path, or body. The `access: full` preset with `protocol: rest` enables inspection but allows all methods and paths, so it does not restrict what the agent can do at the HTTP level. |
| Recommendation | Use `protocol: rest` with specific `rules` for REST APIs where you want method and path control. Use `protocol: rest` with `access: read-only` for read-only endpoints. Omit `protocol` only for non-HTTP protocols (WebSocket, gRPC streaming), endpoints that do not need HTTP inspection, or documented compatibility exceptions that require a client-managed CONNECT tunnel. |
### Operator Approval Flow
When the agent reaches an unlisted endpoint, OpenShell blocks the request and prompts the operator in the TUI.
| Aspect | Detail |
|---|---|
| Default | Enabled. The gateway blocks all unlisted endpoints and requires approval. |
| What you can change | The system merges approved endpoints into the sandbox's policy as a new durable revision. They persist across sandbox restarts within the same sandbox instance. However, when you destroy and recreate the sandbox (for example, by running `nemoclaw onboard`), the policy resets to the baseline defined in the blueprint. |
| Risk if relaxed | Approving an endpoint permanently widens the running sandbox's policy. If you approve a broad domain (such as a CDN that hosts arbitrary content), the agent can fetch anything from that domain until you destroy and recreate the sandbox. |
| Recommendation | Review each blocked request before approving. If you find yourself approving the same endpoint repeatedly, add it to the baseline policy with appropriate binary and path restrictions. To reset approved endpoints, destroy and recreate the sandbox. |
### Policy Presets
NemoClaw ships preset policy files in `nemoclaw-blueprint/policies/presets/` for common integrations.
| Preset | What it enables | Key risk |
|---|---|---|
| `brave` | Brave Search API. | Agent can issue search queries. |
| `brew` | Homebrew (Linuxbrew) package manager. The sandbox base image includes the `brew` binary; this preset opens network egress to GitHub and the Homebrew formulae index so `brew install` can fetch bottles. | Allows installing arbitrary Homebrew packages, which may contain malicious code. |
| `discord` | Discord REST API, WebSocket gateway, CDN. | CDN endpoint (`cdn.discordapp.com`) allows GET to any path. WebSocket uses `access: full` (no inspection). |
| `github` | GitHub and GitHub REST API. | Gives agent read/write access to repositories and issues via `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. |
| `slack` | Slack API, Socket Mode, webhooks. | WebSocket uses `access: full`. Agent can post to any channel the bot token has access to. |
| `telegram` | Telegram Bot API. | Agent can send messages to any chat the bot token has access to. |
**Recommendation:** Apply presets only when the agent's task requires the integration. Review the preset's YAML file before applying to understand the endpoints, methods, and binary restrictions it adds.
## Filesystem Controls
NemoClaw restricts which paths the agent can read and write, protecting system binaries, configuration files, and gateway credentials.
### Read-Only System Paths
The container mounts system directories read-only to prevent the agent from modifying binaries, libraries, or configuration files.
| Aspect | Detail |
|---|---|
| Default | `/usr`, `/lib`, `/proc`, `/dev/urandom`, `/app`, `/etc`, `/var/log` are read-only. |
| What you can change | Add or remove paths in the `filesystem_policy.read_only` section of the policy file. |
| Risk if relaxed | Making `/usr` or `/lib` writable lets the agent replace system binaries (such as `curl` or `node`) with trojanized versions. Making `/etc` writable lets the agent modify DNS resolution, TLS trust stores, or user accounts. |
| Recommendation | Never make system paths writable. If the agent needs a writable location for generated files, use a subdirectory of `/sandbox`. |
### Agent Config Directory
The `/sandbox/.openclaw` directory contains the OpenClaw gateway configuration (model routing, CORS settings, channel config).
The current entrypoint reads the gateway auth token from OpenClaw config when present, exports it as `OPENCLAW_GATEWAY_TOKEN`, and writes it to `/tmp/nemoclaw-proxy-env.sh` so interactive sandbox sessions can reach the gateway through system-wide shell hooks.
In root mode, the gateway process still runs as the separate `gateway` user, but the token is intentionally available to sandbox shells for local gateway access.
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.
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 `2770` (setgid `sandbox:sandbox`) and `openclaw.json` with mode `660`, so the agent and its group can read and write config directly. A reviewed host-side immutability workflow should compare the intended ownership and mode with the live sandbox filesystem before treating the config tree as locked.
- **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 (`2770 sandbox:sandbox`), sets `openclaw.json` to `660 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 | 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, lock config after initial setup. For development workflows, the writable default is appropriate. |
### Writable Paths
The agent has read-write access to `/sandbox`, `/tmp`, and `/dev/null`.
| Aspect | Detail |
|---|---|
| Default | `/sandbox` (agent workspace), `/tmp` (temporary files), `/dev/null`. |
| What you can change | Add additional writable paths in `filesystem_policy.read_write`. |
| Risk if relaxed | Each additional writable path expands the agent's ability to persist data and potentially modify system behavior. Adding `/var` lets the agent write to log directories. Adding `/home` gives access to other user directories. |
| Recommendation | Keep writable paths to `/sandbox` and `/tmp`. If the agent needs a persistent working directory, create a subdirectory under `/sandbox`. |
### Landlock LSM Enforcement
Landlock is a Linux Security Module that enforces filesystem access rules at the kernel level.
| Aspect | Detail |
|---|---|
| Default | `compatibility: best_effort`. The entrypoint applies Landlock rules when the kernel supports them and silently skips them on older kernels. |
| What you can change | This is a NemoClaw default, not a user-facing knob. |
| Risk if relaxed | On kernels without Landlock support (pre-5.13), filesystem restrictions rely solely on container mount configuration, which is less granular. |
| Recommendation | Run on a kernel that supports Landlock (5.13+). Ubuntu 22.04 LTS and later include Landlock support. |
## Process Controls
NemoClaw limits the capabilities, user privileges, and resource quotas available to processes inside the sandbox.
### Capability Drops
The entrypoint drops dangerous Linux capabilities from the bounding set at startup using `capsh`.
This limits what capabilities any child process (gateway, sandbox, agent) can ever acquire.
When the entrypoint switches from root to the `sandbox` and `gateway` users, it uses `setpriv` when available to remove the remaining privilege-separation capabilities from the child process at the same time as the user change.
The initial entrypoint drop removes `cap_sys_admin`, `cap_sys_ptrace`, `cap_net_raw`, `cap_dac_override`, `cap_sys_chroot`, `cap_fsetid`, `cap_setfcap`, `cap_mknod`, `cap_audit_write`, and `cap_net_bind_service`.
During `setpriv` step-down, the child process also loses `cap_setuid`, `cap_setgid`, `cap_fowner`, `cap_chown`, and `cap_kill`.
This is best-effort: if `capsh` is not available or `CAP_SETPCAP` is not in the bounding set, the entrypoint logs a warning and continues with the default capability set.
If `setpriv` is unavailable, the entrypoint falls back to `gosu` and logs a warning that the remaining bounding-set capabilities were retained for the child process.
For additional protection, pass `--cap-drop=ALL` with `docker run` or Compose (see Sandbox Hardening (use the `nemoclaw-user-deploy-remote` skill)).
| Aspect | Detail |
|---|---|
| Default | The entrypoint drops dangerous capabilities at startup using `capsh`, then uses `setpriv` during user step-down when possible. Best-effort. |
| What you can change | When launching with `docker run` directly, pass `--cap-drop=ALL --cap-add=NET_BIND_SERVICE` for stricter enforcement. In the standard NemoClaw flow (with `nemoclaw onboard`), the entrypoint handles capability dropping automatically. |
| Risk if relaxed | `CAP_SYS_ADMIN` and `CAP_SYS_PTRACE` expand kernel and process attack surface. `CAP_NET_RAW` allows raw socket access for network sniffing. `CAP_DAC_OVERRIDE` bypasses filesystem permission checks. If `capsh` or `setpriv` cannot run, the container retains more of the runtime-provided capability set. |
| Recommendation | Run on an image that includes `capsh` and `setpriv` (the NemoClaw image includes them). For defense-in-depth, also pass `--cap-drop=ALL` at the container runtime level. |
### Gateway Process Isolation
The OpenClaw gateway runs as a separate `gateway` user, not as the `sandbox` user that runs the agent.
| Aspect | Detail |
|---|---|
| Default | The entrypoint starts the gateway process using `gosu gateway`, isolating it from the agent's `sandbox` user. |
| What you can change | This is not a user-facing knob. The entrypoint enforces it when running as root. In non-root mode (when OpenShell sets `no-new-privileges`), gateway process isolation does not work because `gosu` cannot change users. |
| Risk if relaxed | If the gateway and agent run as the same user, the agent can kill the gateway process and restart it with a tampered configuration (the "fake-HOME" attack). |
| Recommendation | No action needed. The entrypoint handles this automatically. Be aware that non-root mode disables this isolation. |
### No New Privileges
The `no-new-privileges` flag prevents processes from gaining additional privileges through setuid binaries or capability inheritance.
| Aspect | Detail |
|---|---|
| Default | OpenShell sets `PR_SET_NO_NEW_PRIVS` using `prctl()` inside the sandbox process as part of the seccomp filter setup. The NemoClaw Compose example also shows the equivalent `security_opt: no-new-privileges:true` setting. |
| What you can change | OpenShell's seccomp path enforces this inside the sandbox. It is not a user-facing knob. |
| Risk if relaxed | Without this flag, a compromised process could execute a setuid binary to escalate to root inside the container, then attempt container escape techniques. |
| Recommendation | No action needed. OpenShell enforces this automatically when the sandbox network policy is active. This flag prevents `gosu` from switching users, so non-root mode disables gateway process isolation in the NemoClaw entrypoint. |
### Process Limit
A process limit caps the number of processes the sandbox user can spawn.
The entrypoint sets both soft and hard limits using `ulimit -u 512`.
This is best-effort: if the container runtime restricts `ulimit` modification, the entrypoint logs a security warning and continues without the limit.
| Aspect | Detail |
|---|---|
| Default | 512 processes (`ulimit -u 512`), best-effort. |
| What you can change | Increase or decrease the limit with `--ulimit nproc=N:N` in `docker run` or the `ulimits` section in Compose. The runtime-level ulimit takes precedence over the entrypoint's setting. |
| Risk if relaxed | Removing or raising the limit makes the sandbox vulnerable to fork-bomb attacks, where a runaway process spawns children until the host runs out of resources. If the entrypoint cannot set the limit (logs `[SECURITY] Could not set soft/hard nproc limit`), the container runs without process limits. |
| Recommendation | Keep the default at 512. If the agent runs workloads that spawn many child processes (such as parallel test runners), increase to 1024 and monitor host resource usage. If the entrypoint logs a warning about ulimit restrictions, set the limit through the container runtime instead. |
### Non-Root User
The sandbox runs agent processes as a dedicated `sandbox` user and group.
The entrypoint starts as root for privilege separation, then drops to the `sandbox` user for all agent commands.
| Aspect | Detail |
|---|---|
| Default | `run_as_user: sandbox`, `run_as_group: sandbox`. A separate `gateway` user runs the gateway process. |
| What you can change | Change the `process` section in the policy file to run as a different user. |
| Risk if relaxed | Running as `root` inside the container gives the agent access to modify any file in the container filesystem and increases the impact of container escape vulnerabilities. |
| Recommendation | Never run as root. Keep the `sandbox` user. |
### PATH Hardening
The entrypoint locks the `PATH` environment variable to system directories, preventing the agent from injecting malicious binaries into command resolution.
| Aspect | Detail |
|---|---|
| Default | The entrypoint sets `PATH` to `/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin` at startup. |
| What you can change | This is not a user-facing knob. The entrypoint enforces it. |
| Risk if relaxed | Without PATH hardening, the agent could create an executable named `curl` or `git` in a writable directory earlier in the PATH, intercepting commands run by the entrypoint or other processes. |
| Recommendation | No action needed. The entrypoint handles this automatically. |
### Build Toolchain Removal
The Dockerfile removes compilers and network probes from the runtime image.
| Aspect | Detail |
|---|---|
| Default | The Dockerfile purges `gcc`, `gcc-12`, `g++`, `g++-12`, `cpp`, `cpp-12`, `make`, `netcat-openbsd`, `netcat-traditional`, and `ncat` from the sandbox image. |
| What you can change | Modify the Dockerfile to keep these tools, or install them at runtime if package manager access is allowed. |
| Risk if relaxed | A compiler lets the agent build arbitrary native code, including kernel exploits or custom network tools. `netcat` enables arbitrary TCP connections that bypass HTTP-level policy enforcement. |
| Recommendation | Keep build tools removed. If the agent needs to compile code, run the build in a separate, purpose-built container and copy artifacts into the sandbox. |
### Image Digest Pinning
The blueprint references the sandbox image by an immutable `@sha256:` digest instead of a mutable tag such as `:latest`.
A registry compromise or accidental force-push cannot silently swap the sandbox image.
| Aspect | Detail |
|---|---|
| Default | `nemoclaw-blueprint/blueprint.yaml` pins the sandbox image by digest. A CI regression test blocks any mutable-tag reference from merging. |
| What you can change | Contributors bumping the sandbox image must update the digest in `blueprint.yaml`. Release tooling should rewrite the digest automatically. |
| Risk if relaxed | Reverting to a mutable tag (`:latest`) allows a registry-side change to replace the sandbox image without any blueprint update, which is a supply-chain risk. |
| Recommendation | Always reference the sandbox image by digest. If you build a custom image with `nemoclaw onboard --from`, the digest constraint does not apply to your local build. |
### Auth Profile Permissions
The entrypoint and migration flows enforce `chmod 600` on all `auth-profiles.json` files under `~/.openclaw`.
This prevents other users on the host from reading stored credentials.
| Aspect | Detail |
|---|---|
| Default | `600` permissions applied recursively at startup and after migration restores. |
| What you can change | This is not a user-facing knob. The entrypoint enforces it. |
| Risk if relaxed | Looser permissions let other users or processes on the host read provider API keys and tokens stored in auth profiles. |
| Recommendation | No action needed. If you see a `permission denied` error when reading auth profiles, verify that you are running as the same user who created them. |
## Gateway Authentication Controls
The OpenClaw gateway authenticates devices that connect to the Control UI dashboard.
NemoClaw hardens these defaults at image build time.
### Device Authentication
Device authentication requires each connecting device to go through a pairing flow before it can interact with the gateway.
| Aspect | Detail |
|---|---|
| Default | Enabled. The gateway requires device pairing for all connections. |
| What you can change | Set `NEMOCLAW_DISABLE_DEVICE_AUTH=1` as a Docker build argument to disable device authentication. This is a build-time setting baked into `openclaw.json` and verified by hash at startup. |
| Risk if relaxed | Disabling device auth allows any device on the network to connect to the gateway without proving identity. This is dangerous when combined with LAN-bind changes or cloudflared tunnels in remote deployments, resulting in an unauthenticated, publicly reachable dashboard. |
| Recommendation | Keep device auth enabled (the default). Only disable it for headless or development environments where no untrusted devices can reach the gateway. |
### Gateway Bind Address
NemoClaw binds the OpenShell gateway to loopback by default.
| Aspect | Detail |
|---|---|
| Default | `NEMOCLAW_GATEWAY_BIND_ADDRESS=127.0.0.1`. |
| What you can change | Set `NEMOCLAW_GATEWAY_BIND_ADDRESS=0.0.0.0` before onboarding to listen on all IPv4 interfaces. |
| Risk if relaxed | Other hosts on the network may be able to reach the OpenShell gateway. |
| Recommendation | Keep the loopback default unless the gateway must be reachable from another host. |
### Insecure Auth Derivation
The `allowInsecureAuth` setting controls whether the gateway permits non-HTTPS authentication.
| Aspect | Detail |
|---|---|
| Default | Derived from the `CHAT_UI_URL` scheme at build time. When the URL uses `http://` (local development), insecure auth is allowed. When it uses `https://` (remote or production), insecure auth is blocked. |
| What you can change | This is derived automatically from `CHAT_UI_URL`. Set `CHAT_UI_URL` to an `https://` URL to enforce secure auth. |
| Risk if relaxed | Allowing insecure auth over HTTPS defeats the purpose of TLS, because authentication tokens transit in cleartext. |
| Recommendation | Use `https://` for any deployment accessible beyond `localhost`. The default local URL (`http://127.0.0.1:18789`) correctly allows insecure auth for local development. |
### Auto-Pair Client Allowlist
The auto-pair watcher automatically approves device pairing requests from recognized clients, so you do not need to manually approve the Control UI.
| Aspect | Detail |
|---|---|
| Default | The watcher approves devices with `clientId` set to `openclaw-control-ui` or `clientMode` set to `webchat`. All other clients are rejected and logged. |
| What you can change | This is not a user-facing knob. The allowlist is defined in the entrypoint script. |
| Risk if relaxed | Approving all device types without validation lets rogue or unexpected clients pair with the gateway unchallenged. |
| Recommendation | No action needed. The entrypoint handles this automatically. If you see `[auto-pair] rejected unknown client=...` in the logs, investigate the source of the unexpected connection. |
### CLI Secret Redaction
The CLI automatically redacts secret patterns (API keys, bearer tokens, provider credentials) from command output and error messages before logging them.
| Aspect | Detail |
|---|---|
| Default | Enabled. The runner redacts secrets from stdout, stderr, and thrown error messages. |
| What you can change | This is not a user-facing knob. The CLI enforces it on all command output paths. |
| Risk if relaxed | Without redaction, secrets could appear in terminal scrollback, log files, or debug output shared in bug reports. |
| Recommendation | No action needed. If you share `nemoclaw debug` output, verify that no secrets appear in the collected diagnostics. |
### Memory Secret Scanner
The NemoClaw plugin blocks the agent from writing likely secrets (API keys, tokens, private keys) into persistent memory files.
The scanner intercepts Write, Edit, and similar tool calls targeting memory and workspace paths before they reach disk.
| Aspect | Detail |
|---|---|
| Default | Enabled. The plugin registers a `before_tool_call` hook that scans for 14 high-confidence secret patterns. |
| What it covers | Examples include `.openclaw/memory/`, `.openclaw/workspace/`, `.openclaw/agents/`, `.openclaw/skills/`, `.openclaw/hooks/`, `.openclaw/credentials/`, `.openclaw/openclaw.json`, `.nemoclaw/`, and `MEMORY.md`; the exact coverage is defined by `MEMORY_PATH_SEGMENTS` and enforced through `isMemoryPath()`. |
| What you can change | This is not a user-facing knob. The plugin enforces it automatically. |
| Risk if relaxed | Without scanning, the agent could persist API keys or tokens in memory files that survive across sessions and backups. |
| Recommendation | No action needed. If a write is blocked, the agent receives an actionable error listing the detected patterns. |
## Inference Controls
OpenShell routes all inference traffic through the gateway to isolate provider credentials from the sandbox.
### Routed Inference through `inference.local`
The OpenShell gateway intercepts all inference requests from the agent and routes them to the configured provider.
The agent never receives the provider API key.
| Aspect | Detail |
|---|---|
| Default | The agent talks to `inference.local`. The host owns the credential and upstream endpoint. |
| What you can change | You cannot configure this architecture. The system always enforces it. |
| Risk if bypassed | If the agent could reach an inference endpoint directly (by adding it to the network policy), it would need an API key. Since the sandbox does not contain credentials, this acts as defense-in-depth. However, adding an inference provider's host to the network policy without going through OpenShell routing could let the agent use a stolen or hardcoded key. |
| Recommendation | Do not add inference provider hosts (such as `api.openai.com` or `api.anthropic.com`) to the network policy. Use OpenShell inference routing instead. |
### Provider Trust Tiers
Different inference providers have different trust and cost profiles.
| Provider | Trust level | Cost risk | Data handling |
|---|---|---|---|
| NVIDIA Endpoints | High. Hosted on `build.nvidia.com`. | Pay-per-token with an API key. Unattended agents can accumulate cost. | NVIDIA infrastructure processes requests. |
| OpenAI | High. Commercial API. | Pay-per-token. Same cost risk as NVIDIA Endpoints. | Subject to OpenAI data policies. |
| Anthropic | High. Commercial API. | Pay-per-token. Same cost risk as NVIDIA Endpoints. | Subject to Anthropic data policies. |
| Google Gemini | High. Commercial API. | Pay-per-token. Same cost risk as NVIDIA Endpoints. | Subject to Google data policies. |
| Local Ollama | Self-hosted. No data leaves the machine. | No per-token cost. GPU/CPU resource cost. | Data stays local. |
| Custom compatible endpoint | Varies. Depends on the proxy or gateway. | Varies. | Depends on the endpoint operator. |
**Recommendation:** For sensitive workloads, use local Ollama to keep data on-premise. For general use, NVIDIA Endpoints provide a good balance of capability and trust. Review the data policies of any cloud provider you use.
### Experimental Providers
The `NEMOCLAW_EXPERIMENTAL=1` environment variable gates local NVIDIA NIM and generic Linux managed vLLM install/start. DGX Spark and DGX Station managed vLLM entries are offered by default, and an already-running vLLM server on `localhost:8000` is offered in the menu without a flag, because selecting either is an explicit user action.
| Aspect | Detail |
|---|---|
| Default | Local NVIDIA NIM and generic Linux managed vLLM install/start are hidden. DGX Spark and DGX Station managed vLLM entries, plus already-running vLLM on `localhost:8000`, are offered when detected. |
| What you can change | Set `NEMOCLAW_EXPERIMENTAL=1` before running `nemoclaw onboard` to surface Local NIM and generic Linux managed vLLM. To request only the managed vLLM path non-interactively, set `NEMOCLAW_PROVIDER=install-vllm`. |
| Risk if selected | NemoClaw has not fully validated these providers. NIM requires a NIM-capable GPU. The managed vLLM path pulls a container image and starts it on a supported NVIDIA GPU host. Misconfiguration can cause failed inference or unexpected behavior. |
| Recommendation | Use experimental providers only for evaluation. Do not rely on them for always-on assistants. |
## Posture Profiles
The following profiles describe how to configure NemoClaw for different use cases.
These are not separate policy files.
They provide guidance on which controls to keep tight or relax.
### Locked-Down (Default)
Use for always-on assistants with minimal external access.
- Keep all defaults. Do not add presets.
- Use operator approval for any endpoint the agent requests.
- Use NVIDIA Endpoints or local Ollama for inference.
- Monitor the TUI for unexpected network requests.
### Development
Use when the agent needs package registries, Docker Hub, or broader GitHub access during development tasks.
- Apply the `pypi` and `npm` presets for package installation.
- Keep binary restrictions on all presets.
- Review the agent's network activity periodically with `openshell term`.
- Use operator approval for any endpoint not covered by a preset.
### Integration Testing
Use when the agent talks to internal APIs or third-party services during testing.
- Add custom endpoint entries with tight path and method restrictions.
- Use `protocol: rest` for all HTTP APIs to maintain inspection.
- Use operator approval for unknown endpoints during test runs.
- Review and clean up the baseline policy after testing. Remove endpoints that are no longer needed.
## Common Mistakes
The following patterns weaken security without providing meaningful benefit.
| Mistake | Why it matters | What to do instead |
|---------|---------------|-------------------|
| 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. | 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. |
## Known Limitations
| Limitation | Impact | Mitigation |
|-----------|--------|------------|
| `openclaw agent --local` bypasses gateway | Secret scanning, network policy, and inference auth are not enforced when the agent runs in local mode. | A runtime warning is emitted when `--local` is detected. Avoid `--local` for production workflows. A future OpenClaw-level hook will close this gap. |
| Direct filesystem writes bypass secret scanner | The scanner intercepts OpenClaw tool calls, not raw filesystem writes (e.g., `echo secret > file`). | Landlock restricts writable paths. The scanner is application-layer defense-in-depth, not a filesystem-level control. |
| Base64/hex-encoded secrets are not detected | Content-based regex scanning cannot detect encoded or obfuscated secrets. | Use environment variables or credential stores instead of writing secrets to files. |
## Related Topics
- Network Policies (use the `nemoclaw-user-reference` skill) for the full baseline policy reference.
- Customize the Network Policy (use the `nemoclaw-user-manage-policy` skill) for static and dynamic policy changes.
- Approve or Deny Network Requests (use the `nemoclaw-user-manage-policy` skill) for the operator approval flow.
- Sandbox Hardening (use the `nemoclaw-user-deploy-remote` skill) for container-level security measures.
- Inference Options (use the `nemoclaw-user-configure-inference` skill) for provider configuration details.
- How It Works (use the `nemoclaw-user-overview` skill) for the protection layer architecture.

110
skills/nemoclaw-user-configure-security/references/credential-storage.md
View file

@ -1,110 +0,0 @@
<!-- SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. -->
<!-- SPDX-License-Identifier: Apache-2.0 -->
# Credential Storage
NemoClaw does not persist provider credentials to host disk.
The OpenShell gateway is the only system of record for stored credentials.
When you provide a provider credential — interactively during `nemoclaw onboard` or via an environment variable — NemoClaw holds the value in memory only long enough to register it with the OpenShell gateway through `openshell provider create` or `openshell provider update`.
The gateway stores the credential and the OpenShell L7 proxy substitutes it into outbound requests at egress, so sandboxed agents see placeholders instead of the raw secret.
The sandbox-side OpenClaw gateway token is generated at container startup and is not rotated through provider credential commands.
## Where Credentials Live
Provider credentials live in the OpenShell gateway store.
List what is registered with:
```console
$ openshell provider list
```
Or, equivalently, through NemoClaw:
```console
$ nemoclaw credentials list
```
Both surface the provider names that the gateway holds credentials for. The values themselves cannot be read back from the CLI; this is a deliberate property of OpenShell.
NemoClaw still keeps non-secret operational state under `~/.nemoclaw/` (such as the sandbox registry).
That directory is created with mode `0700` and contains no credential material.
## Environment Variables Take Precedence
When a NemoClaw command needs a credential value during a single run (for example to forward it to an `openshell provider` registration), it reads from `process.env` first.
This means you can:
- Prefix any command with the credential to override the gateway-stored value: `NVIDIA_API_KEY=nvapi-... nemoclaw onboard`
- Use short-lived or rotated credentials in CI by exporting them once per pipeline run
- Avoid registering credentials in the gateway entirely if your environment supplies them
## Deploy Reads from Environment Only
`nemoclaw deploy` (which provisions a remote Brev box) cannot read secrets back from the gateway, so it requires every credential to be present in the host environment at invocation time.
A typical deploy invocation looks like:
```console
$ NVIDIA_API_KEY=nvapi-... \
HF_TOKEN=hf_... \
TELEGRAM_BOT_TOKEN=... \
nemoclaw deploy my-instance
```
For remote vLLM or Hugging Face workflows that need gated model access, `nemoclaw deploy` also forwards `HF_TOKEN` and `HUGGING_FACE_HUB_TOKEN` to the VM when either variable is present.
If a required credential is missing the deploy aborts before any remote work begins.
## GitHub Tokens
NemoClaw never persists `GITHUB_TOKEN` itself.
When a private repo requires authentication NemoClaw runs `gh auth token`, which returns whatever the GitHub CLI has stored — without caring about the storage backend.
The GitHub CLI prefers an OS keychain when one is reachable: macOS Keychain on macOS, Windows Credential Manager on Windows, and Linux Secret Service (libsecret + a running D-Bus session) on Linux.
On hosts where no keychain is reachable (CI runners, headless launches, WSL without a session bus, macOS contexts where Keychain access is blocked, etc.) `gh auth login` falls back to a `gh`-managed file under `~/.config/gh/` with mode `0600`.
NemoClaw treats both backends identically: `gh auth token` returns the value, and NemoClaw stages it in `process.env` for the current run only.
If `gh` is not installed or not logged in, NemoClaw prompts for a personal access token for that single run; the prompted value is held in process memory and is not written to host disk.
Run `gh auth login` if you want a persistent backing store (whichever one applies on your host) so future runs do not prompt.
## Migration From Earlier Releases
Earlier NemoClaw releases stored credentials as plaintext JSON in `~/.nemoclaw/credentials.json` with mode `0600`.
On first `nemoclaw onboard` after upgrading, NemoClaw automatically:
1. Reads the legacy file.
2. Stages allowlisted credential values into `process.env` for the rest of the run.
3. Re-registers each value with the OpenShell gateway through the normal onboarding path.
4. Securely overwrites and deletes `~/.nemoclaw/credentials.json` only after every staged value has been verified as migrated to the gateway.
You will see a one-line stderr notice the first time this happens.
Credential lookup paths such as rebuild also stage allowlisted legacy values so interrupted upgrades can keep working, but those staging-only paths do not delete the plaintext file because they cannot prove every legacy value was registered with the gateway.
If `~/.nemoclaw/credentials.json` remains after a rebuild or other credential lookup, run `nemoclaw onboard` to complete the verified gateway migration and cleanup.
## Rotate or Remove a Stored Credential
The simplest way to replace a stored value is to rerun onboarding with the new value in your environment:
```console
$ NVIDIA_API_KEY=nvapi-new-value nemoclaw onboard
```
To remove a credential from the gateway entirely:
```console
$ nemoclaw credentials reset <PROVIDER_NAME>
```
`<PROVIDER_NAME>` is the OpenShell provider name (run `nemoclaw credentials list` first if you are not sure).
On the next run NemoClaw prompts again unless the credential is supplied through the environment.
## Security Recommendations
1. Prefer short-lived or low-scope provider credentials where the upstream service supports them.
2. Rotate keys after suspected exposure, machine transfer, or account changes.
3. Prefer environment variables for ephemeral automation rather than registering long-lived secrets in the gateway.
4. Do not copy any host-side NemoClaw state into container images, Git repositories, bug reports, or support bundles. Even though credentials no longer live on disk, the surrounding configuration may reveal which providers you have registered.
5. Keep your home directory private and owned by your user account.
## Related Files
For the broader sandbox security model and operational trade-offs, see [Security Best Practices](best-practices.md) and Architecture (use the `nemoclaw-user-reference` skill).

121
skills/nemoclaw-user-configure-security/references/openclaw-controls.md
View file

@ -1,121 +0,0 @@
<!-- SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. -->
<!-- SPDX-License-Identifier: Apache-2.0 -->
# OpenClaw Security Controls Beyond NemoClaw's Scope
NemoClaw provides infrastructure-layer security through sandbox isolation, network policy, filesystem restrictions, SSRF validation, and credential handling.
It delegates all application-layer security to OpenClaw.
This page documents areas where NemoClaw adds no independent protection beyond what OpenClaw already provides.
The details below reflect the OpenClaw documentation at the time of writing.
Consult the [OpenClaw Security docs](https://docs.openclaw.ai/gateway/security/index) for the current state.
## Prompt Injection Detection and Prevention
OpenClaw detects and neutralizes prompt injection attempts before they reach the agent.
| Control | Detail |
|---|---|
| Regex detection | Pattern matching detects common injection vectors such as "ignore all previous instructions" and `<system>` tag spoofing |
| Boundary wrapping | Untrusted input is wrapped in randomized XML boundary markers |
| Unicode folding | Homoglyph folding normalizes bracket variants to prevent visual spoofing |
| Invisible character stripping | Zero-width invisible characters are removed from input |
| Boundary sanitization | Fake boundary markers are sanitized to prevent marker injection |
| Auto-wrapping | Web fetch and search results are automatically wrapped as untrusted external content |
## Tool Access Control and Policy Pipeline
OpenClaw enforces a multi-layer tool policy pipeline that gates every tool call.
| Control | Detail |
|---|---|
| Deny list | High-risk tools (`exec`, `spawn`, `shell`, `fs_write`, `fs_delete`, and others) are blocked from Gateway HTTP by default |
| Policy pipeline | Multi-layer pipeline evaluates tool calls through profile, provider, agent, sandbox, and per-provider policies |
| Fail-closed semantics | Tool call hooks block execution on any error |
| Loop detection | Optional guard detects and blocks repeated identical tool call patterns (disabled by default, opt-in via `tools.loopDetection.enabled`) |
| Plugin approval | Approval workflow defaults to deny on timeout |
## Authentication Rate Limiting and Flood Protection
OpenClaw rate-limits authentication attempts and guards against connection floods.
| Control | Detail |
|---|---|
| Auth rate limiter | Sliding-window rate limiter tracks failed authentication attempts per IP and per scope |
| Control plane limiter | Per-device write rate limiting for control plane operations |
| WebSocket flood guard | Closes connections after repeated unauthorized attempts |
| Pre-auth budget | Limits connections before authentication completes |
## Environment Variable Security Policy
OpenClaw blocks environment variables that could enable code injection, privilege escalation, or credential theft.
| Category | Detail |
|---|---|
| Always-blocked keys | Keys such as `NODE_OPTIONS`, `LD_PRELOAD`, shell injection vectors, crypto mining variables, and `GIT_*` hijacking paths |
| Override-blocked keys | Additional keys blocked unless explicitly overridden |
| Blocked prefixes | Prefixes such as `GIT_CONFIG_`, `NPM_CONFIG_`, `CARGO_REGISTRIES_`, `TF_VAR_` |
| Universal blocked prefixes | `DYLD_`, `LD_`, `BASH_FUNC_` |
## Security Audit Framework
OpenClaw runs automated security checks (50+ distinct check types) that cover configuration, credential handling, and sandbox posture.
Run `openclaw security audit` to see all findings for your deployment.
These checks include:
- Synced-folder leak detection.
- Plaintext secrets in configuration files.
- Hooks hardening verification.
- Gateway no-auth detection.
- Sandbox misconfiguration scanning.
- Weak-model susceptibility assessment.
- Multi-user exposure matrix.
- Node command policy validation.
- Dangerous config flag scanning (`allowInsecureAuth`, `dangerouslyDisableDeviceAuth`, and similar flags).
## Skill and Extension Supply Chain Scanning
OpenClaw scans skills and extensions with a built-in static analysis scanner before installation.
Critical findings block installation by default.
The scanner checks for patterns including:
- Direct process execution calls.
- Dynamic code execution (`eval`, `new Function`, and similar constructs).
- Cryptocurrency mining patterns.
- Unexpected network activity.
- Potential data exfiltration (file read combined with network calls).
- Obfuscated code.
- Environment variable harvesting combined with network calls.
## DM and Group Messaging Access Policy
OpenClaw controls who can interact with the agent through direct messages and group channels.
| Control | Detail |
|---|---|
| DM policy modes | 4 modes: open, disabled, pairing, allowlist |
| Group policies | Per-group access rules |
| Per-sender authorization | Individual sender gating |
| Command authorization | Command-level access control |
| Multi-user detection | Heuristic that detects multi-user scenarios |
## Context Visibility and Output Controls
OpenClaw restricts what supplemental context the agent can see and how it can modify outputs.
| Control | Detail |
|---|---|
| Mode-based restrictions | Limits visibility of history, threads, quotes, and forwarded messages based on the active mode |
| Sender-based restrictions | Limits visibility based on who sent the message |
| Plugin output hooks | Plugin hooks intercept and modify tool results before they reach the user |
## Safe Regex (ReDoS Prevention)
OpenClaw includes safe regex compilation to prevent Regular Expression Denial of Service (ReDoS) attacks.
The implementation detects unsafe nested quantifiers, bounds input length, and caches results.
## Next Steps
- [Security Best Practices](best-practices.md) for NemoClaw's own security controls and risk framework.
- [Credential Storage](credential-storage.md) for how NemoClaw stores and protects provider credentials.

51
skills/nemoclaw-user-configure-security/skill-card.md
View file

@ -1,51 +0,0 @@
## Description: <br>
Presents a risk framework for every configurable security control in NemoClaw. <br>
This skill is ready for commercial/non-commercial use. <br>
## Owner
NVIDIA <br>
### License/Terms of Use: <br>
Apache 2.0 <br>
## Use Case: <br>
Developers and security engineers evaluating NemoClaw security posture, reviewing sandbox security defaults, or assessing control trade-offs for their deployment. <br>
### Deployment Geography for Use: <br>
Global <br>
## Known Risks and Mitigations: <br>
Risk: Review before execution as proposals could introduce incorrect or misleading guidance into skills. <br>
Mitigation: Review and scan skill before deployment. <br>
## Reference(s): <br>
- [NemoClaw Security Best Practices](references/best-practices.md) <br>
- [Credential Storage](references/credential-storage.md) <br>
- [OpenClaw Security Controls Beyond NemoClaw's Scope](references/openclaw-controls.md) <br>
- [OpenClaw Security Documentation](https://docs.openclaw.ai/gateway/security/index) <br>
## Skill Output: <br>
**Output Type(s):** [Analysis, Configuration instructions] <br>
**Output Format:** [Markdown with inline bash code blocks] <br>
**Output Parameters:** [1D] <br>
**Other Properties Related to Output:** [None] <br>
## Evaluation Metrics Used: <br>
Reported benchmark dimensions: <br>
- Security: Checks whether skill-assisted execution avoids unsafe behavior such as secret leakage, destructive commands, or unauthorized access. <br>
- Correctness: Checks whether the agent follows the expected workflow and produces the correct final output. <br>
- Discoverability: Checks whether the agent loads the skill when relevant and avoids using it when irrelevant. <br>
- Effectiveness: Checks whether the agent performs measurably better with the skill than without it. <br>
- Efficiency: Checks whether the agent uses fewer tokens and avoids redundant work. <br>
## Skill Version(s): <br>
0.1.0 (source: package.json) <br>
## Ethical Considerations: <br>
NVIDIA believes Trustworthy AI is a shared responsibility and we have established policies and practices to enable development for a wide array of AI applications. When downloaded or used in accordance with our terms of service, developers should work with their internal team to ensure this skill meets requirements for the relevant industry and use case and addresses unforeseen product misuse. <br>
(For Release on NVIDIA Platforms Only) <br>
Please report quality, risk, security vulnerabilities or NVIDIA AI Concerns [here](https://app.intigriti.com/programs/nvidia/nvidiavdp/detail). <br>

1
skills/nemoclaw-user-configure-security/skill.oms.sig
View file

File diff suppressed because one or more lines are too long

Some files were not shown because too many files have changed in this diff Show more