Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 2 additions & 10 deletions .agents/skills/nemoclaw-user-configure-inference/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,8 +6,6 @@ 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.
Expand All @@ -17,17 +15,11 @@ import { AgentOnly } from "../_components/AgentGuide";
<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.

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.

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ When adapting an OpenClaw sub-agent setup, use these paths inside the sandbox:
| Path | Purpose |
|---|---|
| `/sandbox/.openclaw/openclaw.json` | OpenClaw config, including `models.providers`, `agents.defaults`, and `agents.list`. |
| `/sandbox/.openclaw/.config-hash` | Hash for `openclaw.json`. Keep it in sync after manual config edits; it becomes a startup-enforced trust anchor only after the file is root-owned and read-only. |
| `/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. |
Expand Down Expand Up @@ -41,26 +41,30 @@ The primary orchestration model remains responsible for conversation, planning,
## 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 DOCKER_CTR=openshell-cluster-nemoclaw
docker exec "$DOCKER_CTR" kubectl exec -n openshell "$SANDBOX" -c agent -- cat /sandbox/.openclaw/openclaw.json > /tmp/openclaw.json
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; lock the config root-owned and read-only afterward if the sandbox should enforce config integrity at startup.
In the default mutable state, this keeps the local hash consistent but does not make it tamper-proof.
Use NemoClaw runtime controls when the sandbox needs a hardened config posture after the manual edit.

```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
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.
Expand All @@ -78,7 +82,7 @@ Use the same provider ID that appears in `models.providers`, such as `nvidia-omn
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
docker exec --user root "$SANDBOX_CTR" chown -R sandbox:sandbox /sandbox/.openclaw/agents/vision-operator
```

## Allow Auxiliary Provider Egress
Expand Down
69 changes: 55 additions & 14 deletions .agents/skills/nemoclaw-user-deploy-remote/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,22 +13,59 @@ license: "Apache-2.0"

## Prerequisites

- The [Brev CLI](https://brev.nvidia.com) installed and authenticated.
- 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`.

## Deploy the Instance
## 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.

Create a Brev instance and run the legacy compatibility flow:
Use the legacy compatibility wrapper only when you need the older Brev-specific bootstrap flow:

```bash
nemoclaw deploy <instance-name>
Expand All @@ -51,38 +88,40 @@ If you export `HF_TOKEN` or `HUGGING_FACE_HUB_TOKEN`, the wrapper forwards those

## Connect to the Remote Sandbox

After deployment finishes, the deploy command opens an interactive shell inside the remote sandbox.
To reconnect after closing the session, run the command again:
After onboarding finishes, run the host CLI on the remote VM:

```bash
nemoclaw deploy <instance-name>
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 to monitor activity and approve network requests:
SSH to the instance and run the OpenShell TUI on the remote VM to monitor activity and approve network requests:

```bash
ssh <instance-name> 'cd ~/nemoclaw && set -a && . .env && set +a && openshell term'
ssh <instance-name> 'openshell term'
```

## Verify Inference

Run a test agent prompt inside the remote sandbox:
Run a test agent prompt from the remote VM host:

```bash
openclaw agent --agent main -m "Hello from the remote sandbox" --session-id test
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 setup:
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 deploy <instance-name>
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.
Expand Down Expand Up @@ -134,9 +173,11 @@ Changing the proxy after onboarding requires re-running `nemoclaw onboard`.

## GPU Configuration

The deploy script uses the `NEMOCLAW_GPU` environment variable to select the GPU type.
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`.
Set this variable before running `nemoclaw deploy` to use a different GPU configuration:
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"
Expand Down
9 changes: 3 additions & 6 deletions .agents/skills/nemoclaw-user-manage-policy/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -159,12 +159,9 @@ openshell policy set --policy live-policy.yaml my-assistant

Dynamic changes apply only to the current session.
When the sandbox stops, the running policy resets to the baseline policy plus the presets recorded for the sandbox.
<AgentOnly variant="openclaw">
To make a custom policy survive a sandbox recreation, ship the preset file in the repository (Option 1 above; the file under `presets/` persists) or edit `openclaw-sandbox.yaml` and re-run `nemoclaw onboard`.
</AgentOnly>
<AgentOnly variant="hermes">
To make a custom policy survive a sandbox recreation, ship the preset file in the repository (Option 1 above; the file under `presets/` persists) or edit the Hermes policy additions and re-run `nemoclaw onboard`.
</AgentOnly>
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

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,7 @@ 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.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -31,6 +31,8 @@ Snapshots capture all workspace state directories defined in the agent manifest
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
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -91,3 +91,4 @@ Use the following table to decide when to use NemoHermes versus OpenShell alone.
- [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.
Original file line number Diff line number Diff line change
Expand Up @@ -90,3 +90,4 @@ Use the following table to decide when to use NemoClaw versus OpenShell.
- [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.
2 changes: 2 additions & 0 deletions .agents/skills/nemoclaw-user-overview/references/overview.md
Original file line number Diff line number Diff line change
Expand Up @@ -65,6 +65,7 @@ Navigate to the following topics to learn more about NemoClaw and how to install
- [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>
Expand All @@ -74,6 +75,7 @@ Navigate to the following topics to learn more about NemoClaw and how to install
- [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>
10 changes: 10 additions & 0 deletions .agents/skills/nemoclaw-user-overview/references/release-notes.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,16 @@ 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.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).
- Release validation expands live Vitest coverage for rebuild, sandbox operations, network policy, credential migration, inference routing, Hermes, WhatsApp QR, dashboard binding, VM driver, docs validation, token rotation, and launch smoke paths.

## v0.0.63

NemoClaw v0.0.63 improves sandbox recovery, OpenClaw configuration restore safety, local inference onboarding, messaging safeguards, and release validation:
Expand Down
Loading
Loading