diff --git a/.agents/skills/nemoclaw-user-configure-inference/SKILL.md b/.agents/skills/nemoclaw-user-configure-inference/SKILL.md index 749dbc79c63..c3fc152e5f0 100644 --- a/.agents/skills/nemoclaw-user-configure-inference/SKILL.md +++ b/.agents/skills/nemoclaw-user-configure-inference/SKILL.md @@ -73,16 +73,9 @@ Install `zstd` manually, then rerun onboarding. Run the onboard wizard. - ```bash nemoclaw onboard ``` - - -```bash -nemohermes onboard -``` - Select **Local Ollama** from the provider list. NemoClaw lists installed models or offers starter models if you have not installed any. @@ -116,6 +109,7 @@ Windows-host Ollama requires Docker Desktop WSL integration because the sandbox 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. + **Warning:** Ollama is convenient for local chat, but some model/template combinations can @@ -123,6 +117,7 @@ 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). + ### Authenticated Reverse Proxy @@ -148,18 +143,10 @@ For non-WSL Ollama setups, the onboard wizard manages the proxy automatically: 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 to any port 11435 proto tcp nemoclaw onboard ``` - - -```bash -sudo ufw allow from to any port 11435 proto tcp -nemohermes 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. @@ -182,20 +169,11 @@ This does not delete downloaded model files. ### Non-Interactive Setup - ```bash NEMOCLAW_PROVIDER=ollama \ NEMOCLAW_MODEL=qwen2.5:14b \ nemoclaw onboard --non-interactive --yes ``` - - -```bash -NEMOCLAW_PROVIDER=ollama \ - NEMOCLAW_MODEL=qwen2.5:14b \ - nemohermes 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. @@ -228,17 +206,9 @@ vllm serve meta-llama/Llama-3.1-8B-Instruct --port 8000 Run the onboard wizard. - ```bash nemoclaw onboard ``` - - - -```bash -nemohermes 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`. @@ -256,7 +226,6 @@ Route, configuration, and authentication failures still fail immediately. Set the following environment variables for scripted or CI/CD deployments. - ```bash NEMOCLAW_PROVIDER=custom \ NEMOCLAW_ENDPOINT_URL=http://localhost:8000/v1 \ @@ -264,17 +233,6 @@ NEMOCLAW_PROVIDER=custom \ COMPATIBLE_API_KEY=dummy \ nemoclaw onboard --non-interactive ``` - - - -```bash -NEMOCLAW_PROVIDER=custom \ - NEMOCLAW_ENDPOINT_URL=http://localhost:8000/v1 \ - NEMOCLAW_MODEL=meta-llama/Llama-3.1-8B-Instruct \ - COMPATIBLE_API_KEY=dummy \ - nemohermes onboard --non-interactive -``` - | Variable | Purpose | |---|---| @@ -291,16 +249,9 @@ 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 ``` - - -```bash -NEMOCLAW_PREFERRED_API=openai-responses nemohermes onboard -``` - The wizard then probes `/v1/responses` and only selects it when streaming support is complete. @@ -312,33 +263,20 @@ You can use this variable in both interactive and non-interactive mode. |---|---|---| | `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. - - -If you already onboarded and the sandbox is failing at runtime, re-run `nemohermes onboard` to re-probe the endpoint and bake the correct API path -into the image. - Refer to [Switch Inference Models](references/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 ``` - - -```bash -nemohermes 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 \ @@ -346,30 +284,16 @@ NEMOCLAW_PROVIDER=anthropicCompatible \ COMPATIBLE_ANTHROPIC_API_KEY=dummy \ nemoclaw onboard --non-interactive ``` - - -```bash -NEMOCLAW_PROVIDER=anthropicCompatible \ - NEMOCLAW_ENDPOINT_URL=http://localhost:8080 \ - NEMOCLAW_MODEL=my-model \ - COMPATIBLE_ANTHROPIC_API_KEY=dummy \ - nemohermes 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. - - -For an already-running vLLM server, run `nemohermes 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. @@ -395,34 +319,18 @@ The vLLM `/v1/responses` endpoint does not run the `--tool-call-parser`, so tool Use an already-running vLLM server: - ```bash NEMOCLAW_PROVIDER=vllm \ nemoclaw onboard --non-interactive ``` - - -```bash -NEMOCLAW_PROVIDER=vllm \ - nemohermes 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 ``` - - -```bash -NEMOCLAW_PROVIDER=install-vllm \ - nemohermes 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. @@ -446,22 +354,12 @@ 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= NEMOCLAW_PROVIDER=install-vllm \ NEMOCLAW_VLLM_MODEL=deepseek-r1-distill-70b \ nemoclaw onboard --non-interactive ``` - - -```bash -export HF_TOKEN= -NEMOCLAW_PROVIDER=install-vllm \ - NEMOCLAW_VLLM_MODEL=deepseek-r1-distill-70b \ - nemohermes 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. @@ -472,16 +370,9 @@ NemoClaw can pull, start, and manage a NIM container on hosts with a NIM-capable Set the experimental flag and run onboard. - ```bash NEMOCLAW_EXPERIMENTAL=1 nemoclaw onboard ``` - - -```bash -NEMOCLAW_EXPERIMENTAL=1 nemohermes 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. @@ -490,12 +381,7 @@ On hosts with mixed NVIDIA GPU models, the preflight summary shows each detected 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`. - - -In non-interactive mode, onboard exits with login instructions if Docker is not already authenticated; run `docker login nvcr.io` yourself, then re-run `nemohermes 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. @@ -506,20 +392,11 @@ The same `chat/completions` API path restriction applies. ### Non-Interactive Setup - ```bash NEMOCLAW_EXPERIMENTAL=1 \ NEMOCLAW_PROVIDER=nim \ nemoclaw onboard --non-interactive ``` - - -```bash -NEMOCLAW_EXPERIMENTAL=1 \ - NEMOCLAW_PROVIDER=nim \ - nemohermes onboard --non-interactive -``` - To select a specific model, set `NEMOCLAW_MODEL`. @@ -530,27 +407,14 @@ Large prompts on hardware such as DGX Spark can exceed shorter timeouts, so Nemo To override the timeout, set the `NEMOCLAW_LOCAL_INFERENCE_TIMEOUT` environment variable before onboarding: - ```bash export NEMOCLAW_LOCAL_INFERENCE_TIMEOUT=300 nemoclaw onboard ``` - - -```bash -export NEMOCLAW_LOCAL_INFERENCE_TIMEOUT=300 -nemohermes 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`. - - -Changing it after onboarding requires re-running `nemohermes 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. @@ -559,20 +423,11 @@ The post-create readiness wait (image build, gateway upload, in-sandbox boot) ha 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 ``` - - -```bash -export NEMOCLAW_LOCAL_INFERENCE_TIMEOUT=300 -export NEMOCLAW_SANDBOX_READY_TIMEOUT=600 -nemohermes onboard -``` - If onboard ends with `Sandbox '' was created but did not become ready within 180s`, refer to Troubleshooting (use the `nemoclaw-user-reference` skill). @@ -580,16 +435,9 @@ If onboard ends with `Sandbox '' was created but did not become ready with After onboarding completes, confirm the active provider and model. - ```bash nemoclaw status ``` - - -```bash -nemohermes 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. @@ -602,23 +450,11 @@ Refer to [Switch Inference Models](references/switch-inference-providers.md) for For compatible endpoints, the command is: - ```bash nemoclaw inference set --provider compatible-endpoint --model ``` - - -```bash -nemohermes inference set --provider compatible-endpoint --model -``` - - If the provider itself needs to change (for example, switching from vLLM to a cloud API), pass the new provider to `nemoclaw inference set`. - - -If the provider itself needs to change (for example, switching from vLLM to a cloud API), pass the new provider to `nemohermes inference set`. - ## References diff --git a/.agents/skills/nemoclaw-user-configure-inference/references/inference-options.md b/.agents/skills/nemoclaw-user-configure-inference/references/inference-options.md index 1ef2d127734..bc400365e66 100644 --- a/.agents/skills/nemoclaw-user-configure-inference/references/inference-options.md +++ b/.agents/skills/nemoclaw-user-configure-inference/references/inference-options.md @@ -14,7 +14,7 @@ The provider flow is the same, with the NVIDIA Endpoints route available for Ope -For Hermes onboarding, use `nemohermes onboard`. +For Hermes onboarding, use `nemoclaw onboard`. The provider flow is the same, with the Hermes Provider route available for Hermes Agent. @@ -128,17 +128,9 @@ The sandbox never sees raw API keys. To use the router in scripted setup, set: - ```bash NEMOCLAW_PROVIDER=routed NVIDIA_API_KEY= nemoclaw onboard --non-interactive ``` - - - -```bash -NEMOCLAW_PROVIDER=routed NVIDIA_API_KEY= nemohermes onboard --non-interactive -``` - ### Host Python Requirement @@ -151,24 +143,11 @@ NemoClaw probes `python3.13`, `python3.12`, `python3.11`, `python3.10`, and bare 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`: - - -To pin a specific interpreter, set `NEMOCLAW_MODEL_ROUTER_PYTHON` to its absolute path before running `nemohermes onboard`: - - ```bash NEMOCLAW_MODEL_ROUTER_PYTHON=/opt/homebrew/bin/python3.12 nemoclaw onboard ``` - - - -```bash -NEMOCLAW_MODEL_ROUTER_PYTHON=/opt/homebrew/bin/python3.12 nemohermes 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`. @@ -211,5 +190,7 @@ Other provider credentials, such as `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `GEMI ## Next Steps - [Use a Local Inference Server](../SKILL.md) for Ollama, vLLM, NIM, and compatible-endpoint setup details. + - [Tool-Calling Reliability](tool-calling-reliability.md) for deciding when Ollama is enough and when vLLM with a parser is safer. + - [Switch Inference Models](switch-inference-providers.md) for changing the model at runtime without re-onboarding. diff --git a/.agents/skills/nemoclaw-user-configure-inference/references/switch-inference-providers.md b/.agents/skills/nemoclaw-user-configure-inference/references/switch-inference-providers.md index 384aa069e51..c040e377870 100644 --- a/.agents/skills/nemoclaw-user-configure-inference/references/switch-inference-providers.md +++ b/.agents/skills/nemoclaw-user-configure-inference/references/switch-inference-providers.md @@ -20,11 +20,11 @@ The command updates the OpenShell inference route and synchronizes the running a For OpenClaw, it updates `agents.defaults.model.primary` and the matching provider namespace. -Use `nemohermes inference set` with the provider and model that match the upstream you want to use. +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`, and `model.provider: custom`) without rebuilding or restarting Hermes. Pass `--sandbox ` when you do not want to use the default registered sandbox. -Under `nemohermes`, pass `--sandbox ` when you have registered more than one Hermes sandbox. +Under `nemoclaw`, pass `--sandbox ` when you have registered more than one Hermes sandbox. @@ -33,62 +33,32 @@ Pass `--sandbox ` when you do not want to use the default registered sandb ### NVIDIA Endpoints - ```bash nemoclaw inference set --provider nvidia-prod --model nvidia/nemotron-3-super-120b-a12b ``` - - -```bash -nemohermes inference set --provider nvidia-prod --model nvidia/nemotron-3-super-120b-a12b -``` - ### OpenAI - ```bash nemoclaw inference set --provider openai-api --model gpt-5.4 ``` - - -```bash -nemohermes inference set --provider openai-api --model gpt-5.4 -``` - ### Anthropic - ```bash nemoclaw inference set --provider anthropic-prod --model claude-sonnet-4-6 ``` - - -```bash -nemohermes inference set --provider anthropic-prod --model claude-sonnet-4-6 -``` - ### Google Gemini - ```bash nemoclaw inference set --provider gemini-api --model gemini-2.5-flash ``` - - -```bash -nemohermes 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 ``` @@ -97,19 +67,6 @@ nemoclaw inference set --provider compatible-endpoint --model nemoclaw inference set --provider compatible-anthropic-endpoint --model ``` - - - -```bash -nemohermes inference set --provider compatible-endpoint --model -``` - -```bash -nemohermes inference set --provider compatible-anthropic-endpoint --model -``` - - - ### Hermes Provider @@ -117,7 +74,7 @@ nemohermes inference set --provider compatible-anthropic-endpoint --model @@ -127,45 +84,26 @@ nemohermes inference set --provider hermes-provider --model openai/gpt-5.4-mini 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 ``` - - -```bash -nemohermes 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 ``` - - -```bash -NEMOCLAW_PREFERRED_API=openai-responses nemohermes 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. - - -A fresh `nemohermes onboard` is the reliable fix because it updates both the -session and the baked image. - ## Cross-Provider Switching @@ -181,13 +119,13 @@ nemoclaw inference set --provider anthropic-prod --model claude-sonnet-4-6 --no- -Switching to a different provider family (for example, from NVIDIA Endpoints to Anthropic) also uses `nemohermes inference set`. +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 -nemohermes inference set --provider anthropic-prod --model claude-sonnet-4-6 --no-verify +nemoclaw inference set --provider anthropic-prod --model claude-sonnet-4-6 --no-verify ``` @@ -197,12 +135,7 @@ Use `--no-verify` only when OpenShell cannot verify the provider at switch time ## 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. - - -To change these values, set the corresponding environment variables before running `nemohermes onboard` so they patch into the Dockerfile before the image builds. - | Variable | Values | Default | |---|---|---| @@ -215,9 +148,9 @@ To change these values, set the corresponding environment variables before runni 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. - ```bash export NEMOCLAW_CONTEXT_WINDOW=65536 export NEMOCLAW_MAX_TOKENS=8192 @@ -227,18 +160,6 @@ export NEMOCLAW_AGENT_TIMEOUT=1800 export NEMOCLAW_AGENT_HEARTBEAT_EVERY=0m nemoclaw onboard ``` - - -```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 -nemohermes onboard -``` - @@ -254,7 +175,7 @@ Rebuild the sandbox with `nemoclaw onboard` to apply a new value. `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 `nemohermes onboard` to apply a new value. +Rebuild the sandbox with `nemoclaw onboard` to apply a new value. @@ -274,31 +195,19 @@ Rebuild the sandbox with `nemoclaw onboard --resume` to apply a new value. Hermes does not use OpenClaw's `HEARTBEAT.md` wake-up mechanism. -Rebuild the sandbox with `nemohermes onboard --resume` to apply build-time inference metadata changes. +Rebuild the sandbox with `nemoclaw onboard --resume` to apply build-time inference metadata changes. 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 ``` - - - -```bash -nemohermes 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. @@ -318,49 +227,14 @@ $ nemoclaw inference get --json } ``` - - -Use `nemohermes inference get` to print the provider and model the gateway is currently routing to. -Run it before `nemohermes inference set` to confirm the starting state, or after a switch to verify the new route. - -```console -$ nemohermes inference get -Provider: nvidia-prod -Model: nvidia/nemotron-3-super-120b-a12b -``` - -Pass `--json` for machine-readable output. - -```console -$ nemohermes inference get --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 `nemohermes onboard` to configure one. - Run the status command when you also need sandbox, service, and messaging health: - ```bash nemoclaw status ``` - - -```bash -nemohermes status -``` - The status output includes the active provider, model, and endpoint with the rest of the sandbox state. @@ -379,8 +253,8 @@ The status output includes the active provider, model, and endpoint with the res - The host keeps provider credentials. - The sandbox continues to use `inference.local`. -- `nemohermes inference set` patches the selected running Hermes sandbox config and recomputes its config hash. -- Use `nemohermes onboard --resume --recreate-sandbox` for build-time settings such as context window, max tokens, reasoning mode, heartbeat cadence, or image contents. +- `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. diff --git a/.agents/skills/nemoclaw-user-configure-security/references/best-practices.md b/.agents/skills/nemoclaw-user-configure-security/references/best-practices.md index 2302f351bb7..29318327c7d 100644 --- a/.agents/skills/nemoclaw-user-configure-security/references/best-practices.md +++ b/.agents/skills/nemoclaw-user-configure-security/references/best-practices.md @@ -77,6 +77,7 @@ flowchart TB ## 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 @@ -270,7 +271,15 @@ During `setpriv` step-down, the child process also loses `cap_setuid`, `cap_setg 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. -For additional protection, pass `--cap-drop=ALL` with `docker run` or Compose (see Sandbox Hardening). + +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)). + + +For additional protection, pass `--cap-drop=ALL` with `docker run` or Compose. Refer to Sandbox Hardening. + | Aspect | Detail | |---|---| @@ -569,6 +578,8 @@ The following patterns weaken security without providing meaningful benefit. - 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 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. diff --git a/.agents/skills/nemoclaw-user-configure-security/references/credential-storage.md b/.agents/skills/nemoclaw-user-configure-security/references/credential-storage.md index b80719272a3..af22c1fe761 100644 --- a/.agents/skills/nemoclaw-user-configure-security/references/credential-storage.md +++ b/.agents/skills/nemoclaw-user-configure-security/references/credential-storage.md @@ -7,12 +7,7 @@ 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`. - - -When you provide a provider credential, either interactively during `nemohermes 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. @@ -33,16 +28,9 @@ openshell provider list Or, equivalently, through NemoClaw: - ```bash nemoclaw credentials list ``` - - -```bash -nemohermes 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. @@ -55,21 +43,10 @@ That directory is created with mode `0700` and contains no credential material. 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 - - - -- Prefix any command with the credential to override the gateway-stored value: `NVIDIA_API_KEY=nvapi-... nemohermes 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. @@ -101,12 +78,7 @@ Run `gh auth login` if you want a persistent backing store (whichever one applie ## 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: - - -On first `nemohermes onboard` after upgrading, NemoClaw automatically: - 1. Reads the legacy file. 2. Stages allowlisted credential values into `process.env` for the rest of the run. @@ -115,47 +87,23 @@ On first `nemohermes onboard` after upgrading, NemoClaw automatically: 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. - - -If `~/.nemoclaw/credentials.json` remains after a rebuild or other credential lookup, run `nemohermes 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_API_KEY=nvapi-new-value nemoclaw onboard ``` - - -```bash -NVIDIA_API_KEY=nvapi-new-value nemohermes onboard -``` - To remove a credential from the gateway entirely: - ```bash nemoclaw credentials reset ``` - - -```bash -nemohermes credentials reset -``` - - `` is the OpenShell provider name (run `nemoclaw credentials list` first if you are not sure). - - -`` is the OpenShell provider name (run `nemohermes 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 diff --git a/.agents/skills/nemoclaw-user-deploy-remote/SKILL.md b/.agents/skills/nemoclaw-user-deploy-remote/SKILL.md index 73395a6e63b..a1a1b13fd65 100644 --- a/.agents/skills/nemoclaw-user-deploy-remote/SKILL.md +++ b/.agents/skills/nemoclaw-user-deploy-remote/SKILL.md @@ -156,4 +156,4 @@ nemoclaw deploy - `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` — Commands (use the `nemoclaw-user-reference` skill) for the full `deploy` command reference +- `nemoclaw-user-reference` — `nemoclaw deploy` (use the `nemoclaw-user-reference` skill) for the full `deploy` command reference diff --git a/.agents/skills/nemoclaw-user-deploy-remote/references/sandbox-hardening.md b/.agents/skills/nemoclaw-user-deploy-remote/references/sandbox-hardening.md index 9ac53930222..cd8e8db6687 100644 --- a/.agents/skills/nemoclaw-user-deploy-remote/references/sandbox-hardening.md +++ b/.agents/skills/nemoclaw-user-deploy-remote/references/sandbox-hardening.md @@ -32,6 +32,11 @@ It removes `CAP_SYS_ADMIN`, `CAP_SYS_PTRACE`, `CAP_NET_RAW`, `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: diff --git a/.agents/skills/nemoclaw-user-get-started/references/prerequisites.md b/.agents/skills/nemoclaw-user-get-started/references/prerequisites.md index 102e7f5764b..cda42859dbb 100644 --- a/.agents/skills/nemoclaw-user-get-started/references/prerequisites.md +++ b/.agents/skills/nemoclaw-user-get-started/references/prerequisites.md @@ -30,6 +30,7 @@ If you cannot add memory, configure at least 8 GB of swap to work around the iss 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:** @@ -39,6 +40,11 @@ Members of the `docker` group can control the daemon with root-level impact, so 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. @@ -70,5 +76,5 @@ The table comes from [`ci/platform-matrix.json`](https://github.com/NVIDIA/NemoC ## Next Steps - Prepare Windows for NemoClaw if you are using Windows. -- [Quickstart](../SKILL.md) to install NemoClaw and launch your first sandbox. +- [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. diff --git a/.agents/skills/nemoclaw-user-manage-policy/SKILL.md b/.agents/skills/nemoclaw-user-manage-policy/SKILL.md index 0e1f0f708fe..72985a30784 100644 --- a/.agents/skills/nemoclaw-user-manage-policy/SKILL.md +++ b/.agents/skills/nemoclaw-user-manage-policy/SKILL.md @@ -11,6 +11,7 @@ license: "Apache-2.0" ## 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 @@ -28,15 +29,16 @@ NemoClaw supports both static policy changes that persist across restarts and dy **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 policy-add --from-file`. - - -Apply a custom NemoClaw preset with `nemohermes 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. @@ -54,9 +56,9 @@ That updates the live policy and does not edit `openclaw-sandbox.yaml`. 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 `nemohermes onboard`. +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 `nemohermes policy-add` under [Dynamic Changes](#dynamic-changes). +If you only need to apply a preset to a running sandbox, use `nemoclaw policy-add` under [Dynamic Changes](#dynamic-changes). That updates the live policy and does not edit the baseline policy files. @@ -77,16 +79,9 @@ Each entry in the `network` section defines an endpoint group with the following Apply the updated policy by re-running the onboard wizard: - ```bash nemoclaw onboard ``` - - -```bash -nemohermes onboard -``` - The wizard reads the modified policy file and applies it to the sandbox. @@ -94,16 +89,9 @@ The wizard reads the modified policy file and applies it to the sandbox. Check that the sandbox is running with the updated policy: - ```bash nemoclaw status ``` - - -```bash -nemohermes status -``` - ### Add Blueprint Policy Additions @@ -147,21 +135,10 @@ This is the non-destructive path and the only flow NemoClaw supports out of the 2. Apply it to the running sandbox: - - ```bash nemoclaw my-assistant policy-add ``` - - - -```bash -nemohermes 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. @@ -189,7 +166,7 @@ When the sandbox stops, the running policy resets to the baseline policy plus th 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`. -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 `nemohermes onboard`. +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`. ### Approve Requests Interactively @@ -233,16 +210,9 @@ Available presets: To apply a preset to a running sandbox: - ```bash nemoclaw policy-add ``` - - -```bash -nemohermes policy-add -``` - **Note:** @@ -251,71 +221,39 @@ 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 ``` - - -```bash -nemohermes my-assistant policy-add -``` - To list which presets are applied to a sandbox: - ```bash nemoclaw policy-list ``` - - -```bash -nemohermes policy-list -``` - To include a preset in the baseline, merge its entries into `openclaw-sandbox.yaml` and re-run `nemoclaw onboard`. -To include a preset in the baseline, merge its entries into the Hermes policy additions and re-run `nemohermes onboard`. +To include a preset in the baseline, merge its entries into the Hermes policy additions and re-run `nemoclaw onboard`. **Note:** The `openshell policy set --policy ` command operates on raw policy files and does not accept the `preset:` metadata block used in preset YAML files. - Use `nemoclaw policy-add` for presets. - - -Use `nemohermes 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 ``` - - -```bash -nemohermes my-assistant policy-add pypi --yes -nemohermes 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 rebuild` reapplies every policy preset to the recreated sandbox, so presets survive an agent-version upgrade without manual reapplication. - - -`nemohermes rebuild` reapplies every policy preset to the recreated sandbox, so presets survive an agent-version upgrade without manual reapplication. - ## Custom Preset Files @@ -348,31 +286,17 @@ Rename `preset.name` if NemoClaw refuses to apply the file because of a collisio ### Apply a Single File - ```bash nemoclaw my-assistant policy-add --from-file ./presets/my-internal-api.yaml ``` - - -```bash -nemohermes 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 ``` - - -```bash -nemohermes 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. @@ -388,23 +312,11 @@ Review every host in a custom preset before applying it, especially when the fil 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 ``` - - -```bash -nemohermes my-assistant policy-remove my-internal-api --yes -``` - - `policy-remove` accepts both built-in and custom preset names. Run `nemoclaw policy-list` to see every preset currently applied to the sandbox. - - -`policy-remove` accepts both built-in and custom preset names. Run `nemohermes policy-list` to see every preset currently applied to the sandbox. - ## References diff --git a/.agents/skills/nemoclaw-user-manage-policy/references/integration-policy-examples.md b/.agents/skills/nemoclaw-user-manage-policy/references/integration-policy-examples.md index a51ce1c0dee..5b3798c68a9 100644 --- a/.agents/skills/nemoclaw-user-manage-policy/references/integration-policy-examples.md +++ b/.agents/skills/nemoclaw-user-manage-policy/references/integration-policy-examples.md @@ -20,16 +20,9 @@ Replace `my-assistant` with your sandbox name in the examples. Check the current policy state first: - ```bash nemoclaw my-assistant policy-list ``` - - -```bash -nemohermes my-assistant policy-list -``` - For a live view of blocked requests, open the OpenShell TUI in a separate host terminal: @@ -65,60 +58,31 @@ NemoClaw ships maintained policy presets for common services in `nemoclaw-bluepr Preview the endpoints before applying: - ```bash nemoclaw my-assistant policy-add outlook --dry-run ``` - - -```bash -nemohermes my-assistant policy-add outlook --dry-run -``` - Apply the preset: - ```bash nemoclaw my-assistant policy-add outlook --yes ``` - - -```bash -nemohermes 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 ``` - - -```bash -nemohermes 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 ``` - - -```bash -nemohermes my-assistant policy-add outlook --dry-run -nemohermes 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. @@ -131,35 +95,18 @@ If the blocked endpoint is not covered by the maintained `outlook` preset, treat 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 ``` - - -```bash -nemohermes 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= NEMOCLAW_NON_INTERACTIVE=1 nemoclaw my-assistant channels add telegram nemoclaw my-assistant rebuild nemoclaw my-assistant policy-add telegram --yes ``` - - -```bash -export TELEGRAM_BOT_TOKEN= -NEMOCLAW_NON_INTERACTIVE=1 nemohermes my-assistant channels add telegram -nemohermes my-assistant rebuild -nemohermes my-assistant policy-add telegram --yes -``` - If delivery fails, open the TUI and send a test message to the bot: @@ -176,7 +123,6 @@ Use the matching policy preset after you configure the channel credentials. For Slack: - ```bash export SLACK_BOT_TOKEN= export SLACK_APP_TOKEN= @@ -184,20 +130,9 @@ NEMOCLAW_NON_INTERACTIVE=1 nemoclaw my-assistant channels add slack nemoclaw my-assistant rebuild nemoclaw my-assistant policy-add slack --yes ``` - - -```bash -export SLACK_BOT_TOKEN= -export SLACK_APP_TOKEN= -NEMOCLAW_NON_INTERACTIVE=1 nemohermes my-assistant channels add slack -nemohermes my-assistant rebuild -nemohermes my-assistant policy-add slack --yes -``` - For Discord: - ```bash export DISCORD_BOT_TOKEN= export DISCORD_SERVER_ID= @@ -205,31 +140,13 @@ NEMOCLAW_NON_INTERACTIVE=1 nemoclaw my-assistant channels add discord nemoclaw my-assistant rebuild nemoclaw my-assistant policy-add discord --yes ``` - - -```bash -export DISCORD_BOT_TOKEN= -export DISCORD_SERVER_ID= -NEMOCLAW_NON_INTERACTIVE=1 nemohermes my-assistant channels add discord -nemohermes my-assistant rebuild -nemohermes 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 ``` - - -```bash -nemohermes my-assistant policy-add slack --yes -nemohermes my-assistant policy-add discord --yes -``` - ## WeChat or WhatsApp Messaging (Experimental) @@ -241,53 +158,27 @@ 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 ``` - - -```bash -nemohermes my-assistant channels add wechat -nemohermes my-assistant rebuild -nemohermes 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 ``` - - -```bash -NEMOCLAW_NON_INTERACTIVE=1 nemohermes my-assistant channels add whatsapp -nemohermes my-assistant rebuild -nemohermes 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 ``` - - -```bash -nemohermes my-assistant policy-add wechat --yes -nemohermes my-assistant policy-add whatsapp --yes -``` - ## GitHub and Jira @@ -296,33 +187,17 @@ 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 ``` - - -```bash -nemohermes my-assistant policy-add github --dry-run -nemohermes 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 ``` - - -```bash -nemohermes my-assistant policy-add github --yes -nemohermes 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`. @@ -341,36 +216,20 @@ This manual probe proves curl reached Atlassian, but no Jira credentials were su Remove access when the task is done: - ```bash nemoclaw my-assistant policy-remove github --yes nemoclaw my-assistant policy-remove jira --yes ``` - - -```bash -nemohermes my-assistant policy-remove github --yes -nemohermes 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 ``` - - -```bash -nemohermes my-assistant policy-add brave --dry-run -nemohermes my-assistant policy-add brave --yes -``` - The Brave Search API key is still configured separately during onboarding or through the web search setup flow. @@ -387,41 +246,21 @@ Use these presets when an agent workflow installs packages or downloads model as 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 ``` - - -```bash -nemohermes my-assistant policy-add npm --yes -nemohermes my-assistant policy-add pypi --yes -nemohermes my-assistant policy-add brew --yes -nemohermes 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 ``` - - -```bash -nemohermes my-assistant policy-remove npm --yes -nemohermes my-assistant policy-remove pypi --yes -nemohermes my-assistant policy-remove brew --yes -nemohermes 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. @@ -432,20 +271,11 @@ The sandbox base image includes Homebrew (Linuxbrew), so applying the `brew` pre 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 nemoclaw my-assistant exec -- bash -lc '' ``` - - -```bash -nemohermes my-assistant policy-add brew --yes -nemohermes my-assistant exec -- brew install -nemohermes my-assistant exec -- bash -lc '' -``` - You do not need to bootstrap Homebrew, install build dependencies, or source `brew shellenv` inside the sandbox. @@ -481,46 +311,24 @@ Use `local-inference` when the sandbox needs access to host-side local inference 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 ``` - - -```bash -nemohermes my-assistant policy-add local-inference --dry-run -nemohermes my-assistant policy-add local-inference --yes -``` - Then verify the sandbox status: - ```bash nemoclaw my-assistant status ``` - - -```bash -nemohermes my-assistant status -``` - ## Inspect or Replace the Live Policy Use `policy-list` for normal preset state: - ```bash nemoclaw my-assistant policy-list ``` - - -```bash -nemohermes my-assistant policy-list -``` - Use OpenShell when you need the full enforced YAML: @@ -536,12 +344,7 @@ 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. - - -Use `nemohermes my-assistant policy-add` for maintained NemoClaw presets. - ## Next Steps diff --git a/.agents/skills/nemoclaw-user-manage-sandboxes/SKILL.md b/.agents/skills/nemoclaw-user-manage-sandboxes/SKILL.md index ce9f7cf4f6c..86956e2b07e 100644 --- a/.agents/skills/nemoclaw-user-manage-sandboxes/SKILL.md +++ b/.agents/skills/nemoclaw-user-manage-sandboxes/SKILL.md @@ -22,93 +22,51 @@ It covers day-two sandbox operations such as listing sandboxes, checking health, 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`. -When a workflow uses the lower-level OpenShell CLI, see CLI Selection Guide (use the `nemoclaw-user-reference` skill) for the boundary between `nemohermes`, `nemoclaw`, and `openshell`. +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`. ## List Sandboxes List every sandbox registered on this host: - ```bash nemoclaw list ``` - - -```bash -nemohermes 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 ``` - - -```bash -nemohermes 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 ``` - - -```bash -nemohermes 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 ``` - - -```bash -nemohermes status -``` - ## Inspect Logs View recent sandbox logs: - ```bash nemoclaw my-assistant logs ``` - - -```bash -nemohermes my-assistant logs -``` - Stream logs while you reproduce a problem: - ```bash nemoclaw my-assistant logs --follow ``` - - -```bash -nemohermes my-assistant logs --follow -``` - The log command reads both OpenClaw gateway output and OpenShell audit events, so policy denials appear beside gateway logs. @@ -121,29 +79,15 @@ The log command reads both Hermes gateway output and OpenShell audit events, so Collect diagnostics for bug reports or support handoff: - ```bash nemoclaw debug --sandbox my-assistant --output nemoclaw-debug.tar.gz ``` - - -```bash -nemohermes debug --sandbox my-assistant --output nemoclaw-debug.tar.gz -``` - Use `--quick` for a smaller local summary: - ```bash nemoclaw debug --quick --sandbox my-assistant ``` - - -```bash -nemohermes debug --quick --sandbox my-assistant -``` - The debug command gathers system information, Docker state, gateway logs, and sandbox status. @@ -168,51 +112,28 @@ Each sandbox needs its own dashboard port, since `openshell forward` refuses to When the default port is already held by another sandbox, `nemoclaw onboard` scans ports `18789` through `18799` and uses the next free port. -When the default API port is already held by another sandbox, `nemohermes onboard` scans for the next free port and records it for the sandbox. +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. 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. - ```bash nemoclaw onboard # first sandbox uses 18789 nemoclaw onboard # second sandbox uses the next free port, such as 18790 ``` - - -```bash -nemohermes onboard # first sandbox uses 18789 -nemohermes 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 ``` - - -```bash -nemohermes 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 ``` - - -```bash -CHAT_UI_URL=http://127.0.0.1:19000 nemohermes onboard -NEMOCLAW_DASHBOARD_PORT=19000 nemohermes onboard -``` - For full details on port conflicts and overrides, refer to Port already in use (use the `nemoclaw-user-reference` skill). @@ -224,16 +145,9 @@ Recover from a misconfigured sandbox without re-running the full onboard wizard Change the active model or provider at runtime without rebuilding the sandbox: - ```bash nemoclaw inference set --model --provider ``` - - -```bash -nemohermes inference set --model --provider -``` - Refer to Switch Inference Providers (use the `nemoclaw-user-configure-inference` skill) for provider-specific model IDs and API compatibility notes. @@ -243,54 +157,28 @@ Refer to Switch Inference Providers (use the `nemoclaw-user-configure-inference` If `nemoclaw status` reports the sandbox is alive but the gateway is not running, run the recover command instead of opening a shell. -If `nemohermes status` reports the sandbox is alive but the Hermes gateway is not running, run the recover command instead of opening a shell. +If `nemoclaw status` reports the sandbox is alive but the Hermes gateway is not running, run the recover command instead of opening a shell. - ```bash nemoclaw recover ``` - - -```bash -nemohermes 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 recover` (use the `nemoclaw-user-reference` skill) for details. - - -Refer to the command reference for details on `nemohermes recover`. - ### 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 # clear a single provider, for example nvidia-prod nemoclaw onboard # re-run to re-enter the cleared provider ``` - - -```bash -nemohermes credentials list # see which providers are registered -nemohermes credentials reset # clear a single provider, for example nvidia-prod -nemohermes onboard # re-run to re-enter the cleared provider -``` - - The command reference documents `nemoclaw credentials reset ` (use the `nemoclaw-user-reference` skill) in full. - - -The Commands reference (use the `nemoclaw-user-reference` skill) documents the credentials command in full. - ### Rebuild a Sandbox While Preserving Workspace State @@ -301,40 +189,21 @@ If you changed the underlying Dockerfile, upgraded OpenClaw, or want to pick up 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: - ```bash nemoclaw rebuild ``` - - -```bash -nemohermes 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 rebuild` (use the `nemoclaw-user-reference` skill) for flag details. - - -Refer to the Commands reference (use the `nemoclaw-user-reference` skill) for `nemohermes rebuild` 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 policy-add ``` - - -```bash -nemohermes policy-add -``` - Refer to `nemoclaw policy-add` (use the `nemoclaw-user-reference` skill) for usage details and flags. @@ -344,12 +213,8 @@ See `NEMOCLAW_POLICY_MODE` (use the `nemoclaw-user-reference` skill) for the ful ## Update to the Maintained Version - When a maintained NemoClaw release becomes available, update the `nemoclaw` CLI on your host and check existing sandboxes for stale agent/runtime versions. - - -When a maintained NemoClaw release becomes available, update the `nemohermes` CLI on your host and check existing sandboxes for stale agent/runtime versions. - + The standard installer follows the admin-promoted `lkg` release tag by default, so it can trail the newest semver or `latest` tag while validation completes. To pin a specific release in a `curl | bash` install, set `NEMOCLAW_INSTALL_TAG` on the `bash` side of the pipe, or export it before the pipeline: @@ -366,12 +231,8 @@ If the requested ref cannot be fetched, the installer exits with a clear error i ## Update the NemoClaw CLI Re-run the installer. - Before it onboards anything, the installer calls `nemoclaw backup-all` (use the `nemoclaw-user-reference` skill) automatically, storing a snapshot of each running sandbox in `~/.nemoclaw/rebuild-backups/` as a safety net. - - -Before it onboards anything, the installer calls `nemohermes backup-all` automatically, storing a snapshot of each running sandbox in `~/.nemoclaw/rebuild-backups/` as a safety net. - + If your existing gateway is from OpenShell earlier than `0.0.37`, the installer prompts before it runs the new automatic gateway upgrade path. The installer offers the automatic path only when the existing `nemoclaw` CLI supports `backup-all`. @@ -379,9 +240,9 @@ Older installs must preserve sandbox state manually before retiring the gateway. For unattended installs, set `NEMOCLAW_ACCEPT_EXPERIMENTAL_OPENSHELL_UPGRADE=1`, or manually run `nemoclaw backup-all`, `openshell gateway remove nemoclaw || openshell gateway destroy -g nemoclaw || openshell gateway destroy` (the command tries both verbs so the right one runs on either OpenShell release), and `sudo pkill -f openshell-gateway` if a privileged host gateway remains before rerunning the installer as `curl -fsSL https://www.nvidia.com/nemoclaw.sh | NEMOCLAW_OPENSHELL_UPGRADE_PREPARED=1 bash`. -The installer offers the automatic path only when the existing `nemohermes` CLI supports `backup-all`. +The installer offers the automatic path only when the existing `nemoclaw` CLI supports `backup-all`. Older installs must preserve sandbox state manually before retiring the gateway. -For unattended installs, set `NEMOCLAW_ACCEPT_EXPERIMENTAL_OPENSHELL_UPGRADE=1`, or manually run `nemohermes backup-all`, `openshell gateway remove nemoclaw || openshell gateway destroy -g nemoclaw || openshell gateway destroy` (the command tries both verbs so the right one runs on either OpenShell release), and `sudo pkill -f openshell-gateway` if a privileged host gateway remains before rerunning the installer as `curl -fsSL https://www.nvidia.com/nemoclaw.sh | NEMOCLAW_AGENT=hermes NEMOCLAW_OPENSHELL_UPGRADE_PREPARED=1 bash`. +For unattended installs, set `NEMOCLAW_ACCEPT_EXPERIMENTAL_OPENSHELL_UPGRADE=1`, or manually run `nemoclaw backup-all`, `openshell gateway remove nemoclaw || openshell gateway destroy -g nemoclaw || openshell gateway destroy` (the command tries both verbs so the right one runs on either OpenShell release), and `sudo pkill -f openshell-gateway` if a privileged host gateway remains before rerunning the installer as `curl -fsSL https://www.nvidia.com/nemoclaw.sh | NEMOCLAW_AGENT=hermes NEMOCLAW_OPENSHELL_UPGRADE_PREPARED=1 bash`. ```bash @@ -390,61 +251,34 @@ curl -fsSL https://www.nvidia.com/nemoclaw.sh | bash ### Upgrade Sandboxes with Stale Agent and Runtime Versions - The installer checks registered sandboxes after onboarding succeeds and runs `nemoclaw upgrade-sandboxes --auto` for stale running sandboxes. - - -The installer checks registered sandboxes after onboarding succeeds and runs `nemohermes upgrade-sandboxes --auto` for stale running sandboxes. - Use `upgrade-sandboxes` directly to verify the result, rebuild when you skipped the installer or onboarding step, or handle sandboxes that were stopped or could not be version checked. The upgrade flow is non-destructive by default because NemoClaw preserves manifest-defined workspace state, but a manual snapshot before any major upgrade gives you a state restore point. - ```bash nemoclaw snapshot create --name pre-upgrade # optional, recommended nemoclaw update --yes # updates CLI through the maintained installer flow nemoclaw upgrade-sandboxes --check # verify or list remaining stale/unknown sandboxes nemoclaw upgrade-sandboxes # manually rebuild remaining stale running sandboxes ``` - - -```bash -nemohermes snapshot create --name pre-upgrade # optional, recommended -nemohermes update --yes # updates CLI through the maintained installer flow -nemohermes upgrade-sandboxes --check # verify or list remaining stale/unknown sandboxes -nemohermes upgrade-sandboxes # manually rebuild remaining stale running sandboxes -``` - `nemoclaw update` is the CLI wrapper around the same installer path as `curl -fsSL https://www.nvidia.com/nemoclaw.sh | bash`. Use `nemoclaw update --check` when you only want to inspect version state and see the maintained update command. -`nemohermes update` is the CLI wrapper around the same installer path with Hermes selected. -Use `nemohermes update --check` when you only want to inspect version state and see the maintained update command. +`nemoclaw update` is the CLI wrapper around the same installer path with Hermes selected. +Use `nemoclaw update --check` when you only want to inspect version state and see the maintained update command. - For scripted manual rebuilds, use `nemoclaw upgrade-sandboxes --auto` to skip the confirmation prompt. - - -For scripted manual rebuilds, use `nemohermes upgrade-sandboxes --auto` to skip the confirmation prompt. - If the upgraded sandbox needs its workspace state reverted, restore the pre-upgrade snapshot into the running sandbox. This restores saved state directories only; it does not downgrade the sandbox image or agent/runtime: - ```bash nemoclaw snapshot restore pre-upgrade ``` - - -```bash -nemohermes snapshot restore pre-upgrade -``` - ### What Changes During a Rebuild @@ -457,10 +291,10 @@ NemoClaw protects your data through the same backup-and-restore flow as `nemocla -NemoClaw protects your data through the same backup-and-restore flow as `nemohermes rebuild`: +NemoClaw protects your data through the same backup-and-restore flow as `nemoclaw rebuild` (use the `nemoclaw-user-reference` skill): - NemoClaw preserves manifest-defined Hermes state. Before deleting the old container, NemoClaw snapshots the state directories and durable state files defined in the Hermes manifest, including `SOUL.md` and the SQLite database behind `.hermes/state.db`. Stored credentials (`~/.nemoclaw/credentials.json`) and registered policy presets live on the host and are re-applied to the new sandbox automatically. -- NemoClaw does not preserve runtime changes outside the manifest-defined state directories. This includes packages installed inside the running container with `apt` or `pip`, files in non-state paths, and in-memory or process state. If you have customized the running container at runtime, capture that as `Dockerfile` changes for `nemohermes onboard --from` or a manual `openshell sandbox download` before the rebuild starts. +- NemoClaw does not preserve runtime changes outside the manifest-defined state directories. This includes packages installed inside the running container with `apt` or `pip`, files in non-state paths, and in-memory or process state. If you have customized the running container at runtime, capture that as `Dockerfile` changes for `nemoclaw onboard --from` or a manual `openshell sandbox download` before the rebuild starts. @@ -472,36 +306,20 @@ See [Backup and Restore](references/backup-restore.md) for the full list of stat **If the rebuild aborts with `Missing credential: `:** - The rebuild preflight reads the provider credential recorded by your last `nemoclaw onboard` session. If you have switched providers since onboarding, for example from a remote API to a local Ollama setup, the preflight can still reference the old key and fail before any destroy step runs. To recover, re-run `nemoclaw onboard` and select your current provider. This refreshes the session metadata. - - -The rebuild preflight reads the provider credential recorded by your last `nemohermes onboard` session. -If you have switched providers since onboarding, for example from a remote API to a local Ollama setup, the preflight can still reference the old key and fail before any destroy step runs. - -To recover, re-run `nemohermes onboard` and select your current provider. -This refreshes the session metadata. - Your existing container keeps serving traffic until the new image is ready. ## Uninstall To remove NemoClaw and all resources created during setup, run the CLI's built-in uninstall command: - ```bash nemoclaw uninstall ``` - - -```bash -nemohermes uninstall -``` - | Flag | Effect | |--------------------|------------------------------------------------------| diff --git a/.agents/skills/nemoclaw-user-manage-sandboxes/references/backup-restore.md b/.agents/skills/nemoclaw-user-manage-sandboxes/references/backup-restore.md index 04e4abf3dcf..38cba2c0365 100644 --- a/.agents/skills/nemoclaw-user-manage-sandboxes/references/backup-restore.md +++ b/.agents/skills/nemoclaw-user-manage-sandboxes/references/backup-restore.md @@ -20,7 +20,7 @@ This guide covers snapshot commands, manual backup with CLI commands, and an aut -- Before running `nemohermes destroy` +- Before running `nemoclaw destroy` - Before major NemoClaw version upgrades - Periodically, if you've invested time customizing your agent or paired messaging channels @@ -34,69 +34,36 @@ 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. - ```bash nemoclaw my-assistant snapshot create nemoclaw my-assistant snapshot list nemoclaw my-assistant snapshot restore ``` - - -```bash -nemohermes my-assistant snapshot create -nemohermes my-assistant snapshot list -nemohermes 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 ``` - - -```bash -nemohermes 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 ``` - - -```bash -nemohermes my-assistant snapshot restore v3 -nemohermes my-assistant snapshot restore before-upgrade -nemohermes my-assistant snapshot restore 2026-04-14T -``` - To clone a snapshot into a different sandbox name, pass `--to `. 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 ``` - - -```bash -nemohermes my-assistant snapshot restore before-upgrade --to my-assistant-clone -nemohermes my-assistant snapshot restore before-upgrade --to my-assistant-clone --force --yes -``` - @@ -107,7 +74,7 @@ NemoClaw rejects unsafe symlinks and hard links inside sandbox state during back -The `nemohermes rebuild` command uses the same snapshot mechanism automatically. +The `nemoclaw 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 diff --git a/.agents/skills/nemoclaw-user-manage-sandboxes/references/messaging-channels.md b/.agents/skills/nemoclaw-user-manage-sandboxes/references/messaging-channels.md index 48966fc6d8c..98b9d066276 100644 --- a/.agents/skills/nemoclaw-user-manage-sandboxes/references/messaging-channels.md +++ b/.agents/skills/nemoclaw-user-manage-sandboxes/references/messaging-channels.md @@ -21,7 +21,7 @@ You can enable channels during `nemoclaw onboard` or add them later with host-si 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. -You can enable channels during `nemohermes onboard` or add them later with host-side `nemohermes channels` commands. +You can enable channels during `nemoclaw onboard` or add them later with host-side `nemoclaw 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. @@ -30,30 +30,19 @@ Do not mutate messaging configuration directly inside the sandbox because NemoCl It only starts optional host services such as the cloudflared tunnel when that binary is present. (`nemoclaw start` is kept as a deprecated alias.) -`nemohermes tunnel start` does not start Telegram, Discord, Slack, or other chat bridges. +`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. 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 machine where you can run `nemohermes 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 | @@ -62,19 +51,6 @@ For details, refer to Commands (use the `nemoclaw-user-reference` skill). | 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 | - - - -| 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 `nemohermes 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**. @@ -105,12 +81,7 @@ WeChat (experimental) delivers messages over Tencent's iLink gateway through the 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`. - - -Because the bot token only exists after a successful iLink QR handshake, NemoClaw runs the QR login on the host during `nemohermes 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 `-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. @@ -170,25 +141,13 @@ export SLACK_ALLOWED_CHANNELS= ``` 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. - - -Run `nemohermes onboard` interactively when you want to enable WeChat. - Then run onboarding: - ```bash nemoclaw onboard ``` - - -```bash -nemohermes onboard -``` - Complete the rest of the wizard so the blueprint can create OpenShell providers where needed (for example `-telegram-bridge` or `-wechat-bridge`), bake channel configuration into the image (`NEMOCLAW_MESSAGING_CHANNELS_B64`), and start the sandbox. @@ -197,20 +156,12 @@ Complete the rest of the wizard so the blueprint can create OpenShell providers 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 ``` - - -```bash -nemohermes my-assistant channels list -``` - Add the channel you want: - ```bash nemoclaw my-assistant channels add telegram nemoclaw my-assistant channels add discord @@ -218,16 +169,6 @@ nemoclaw my-assistant channels add slack nemoclaw my-assistant channels add wechat nemoclaw my-assistant channels add whatsapp ``` - - -```bash -nemohermes my-assistant channels add telegram -nemohermes my-assistant channels add discord -nemohermes my-assistant channels add slack -nemohermes my-assistant channels add wechat -nemohermes 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. @@ -240,12 +181,7 @@ When the apply step itself fails after the registry write on a fresh add, NemoCl 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 channels add `. - - -Restore the preset YAML and re-run `nemohermes channels add `. - Choose the rebuild so the running sandbox image picks up the new channel. For Telegram, Discord, and Slack, `channels add` also checks the rebuilt runtime for the selected bridge and reports startup, credential, or missing-plugin warnings before returning. If you need optional channel settings such as `TELEGRAM_ALLOWED_IDS`, `TELEGRAM_REQUIRE_MENTION`, `DISCORD_SERVER_ID`, `DISCORD_USER_ID`, `DISCORD_REQUIRE_MENTION`, `SLACK_ALLOWED_USERS`, or `SLACK_ALLOWED_CHANNELS`, export them before the rebuild starts. @@ -253,53 +189,27 @@ Telegram Bot API `sendMessage` calls prove outbound delivery from the bot; to te 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 ``` - - -```bash -nemohermes 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= \ nemoclaw my-assistant channels add telegram nemoclaw my-assistant rebuild ``` - - -```bash -NEMOCLAW_NON_INTERACTIVE=1 TELEGRAM_BOT_TOKEN= \ - nemohermes my-assistant channels add telegram -nemohermes my-assistant rebuild -``` - For Discord server access after onboarding, include the server settings when you add the channel and rebuild: - ```bash DISCORD_BOT_TOKEN= \ DISCORD_SERVER_ID= \ DISCORD_REQUIRE_MENTION=1 \ nemoclaw my-assistant channels add discord ``` - - -```bash -DISCORD_BOT_TOKEN= \ - DISCORD_SERVER_ID= \ - DISCORD_REQUIRE_MENTION=1 \ - nemohermes my-assistant channels add discord -``` - ### `channels add wechat` @@ -313,16 +223,9 @@ 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 ``` - - -```bash -nemohermes 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. @@ -337,18 +240,10 @@ Rebuild the sandbox after the update so the image reflects the current channel s To remove a channel and clear its stored credentials, run: - ```bash nemoclaw my-assistant channels remove telegram nemoclaw my-assistant channels remove wechat ``` - - -```bash -nemohermes my-assistant channels remove telegram -nemohermes my-assistant channels remove wechat -``` - `channels remove wechat` clears the bot token, deletes the `-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/`. @@ -366,8 +261,6 @@ Remove the entry from the phone if you plan to re-pair the same phone with a dif 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 @@ -376,19 +269,6 @@ nemoclaw my-assistant channels stop wechat nemoclaw my-assistant channels start wechat ``` - - - -```bash -nemohermes my-assistant channels stop telegram -nemohermes my-assistant channels start telegram - -nemohermes my-assistant channels stop wechat -nemohermes my-assistant channels start wechat -``` - - - 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`. @@ -406,12 +286,7 @@ Running two sandboxes against the same WeChat account causes one of them to lose 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. If NemoClaw only has legacy channel metadata and cannot compare credential hashes, it keeps the conservative warning. Re-run `channels add ` 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. - - -`nemohermes status` reports cross-sandbox overlaps so you can resolve duplicates before messages start dropping. - ## Stop Messaging Delivery @@ -420,7 +295,7 @@ Use `channels stop` when you want to pause one bridge and keep the sandbox runni 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. -Use `nemohermes tunnel stop` when you want to stop host auxiliary services and also ask NemoClaw to stop the Hermes gateway inside the selected sandbox. +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. Stopping the in-sandbox gateway stops Telegram, Discord, Slack, WeChat, and WhatsApp polling for that sandbox until you restart the sandbox or gateway. @@ -436,7 +311,7 @@ Use the matching policy preset (`telegram`, `discord`, `slack`, `wechat`, or `wh When the host has `cloudflared`, `nemoclaw tunnel start` starts a cloudflared tunnel that can expose the dashboard with a public URL. -When the host has `cloudflared`, `nemohermes tunnel start` starts a cloudflared tunnel that can expose the forwarded Hermes endpoint with a public URL. +When the host has `cloudflared`, `nemoclaw tunnel start` starts a cloudflared tunnel that can expose the forwarded Hermes endpoint with a public URL. Set `CLOUDFLARE_TUNNEL_TOKEN` before running the command when you want to use a Cloudflare named tunnel instead of a generated quick-tunnel URL. @@ -444,22 +319,17 @@ Set `CLOUDFLARE_TUNNEL_TOKEN` before running the command when you want to use a The older `nemoclaw start` still works as a deprecated alias. -`nemohermes tunnel stop` stops the tunnel and asks NemoClaw to stop the in-sandbox gateway for the selected or default sandbox. +`nemoclaw tunnel stop` stops the tunnel and asks NemoClaw to stop the in-sandbox gateway for the selected or default sandbox. - ```bash nemoclaw tunnel start ``` - - -```bash -nemohermes tunnel start -``` - ## Related Topics + - Deploy NemoClaw to a Remote GPU Instance (use the `nemoclaw-user-deploy-remote` skill) for remote deployment with messaging. + - 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`. diff --git a/.agents/skills/nemoclaw-user-manage-sandboxes/references/runtime-controls.md b/.agents/skills/nemoclaw-user-manage-sandboxes/references/runtime-controls.md index 46c34155d35..e7306932576 100644 --- a/.agents/skills/nemoclaw-user-manage-sandboxes/references/runtime-controls.md +++ b/.agents/skills/nemoclaw-user-manage-sandboxes/references/runtime-controls.md @@ -38,18 +38,18 @@ If a row above conflicts with what you observe, the runtime source of truth insi | 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 | `nemohermes inference set` for route changes, or `nemohermes rebuild` after changing build-time settings | -| Inference model on the current provider | Hot-reloadable through the Hermes config sync path | `nemohermes inference set` | -| Agent runtime (Hermes compared to OpenClaw) | Re-onboard required (the agent and its state layout are baked at onboard) | `nemohermes 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 | `nemohermes policy-add ` / `policy-remove ` | +| 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 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 policy-add ` / `policy-remove ` | | 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) | `nemohermes channels add ` 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) | `nemohermes channels stop ` then rebuild | -| API/dashboard forward port | Runtime. Port is re-resolved on next `connect` | `nemohermes connect` or `openshell forward start` | -| Filesystem layout (Landlock zones, read-only mounts, container caps) | **Locked at creation**. No runtime change | Re-onboard with `nemohermes onboard --recreate-sandbox` | +| 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 channels add ` 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 channels stop ` then rebuild | +| API/dashboard forward port | Runtime. Port is re-resolved on next `connect` | `nemoclaw 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 `nemohermes inference set`; image, policy, and channel changes still require rebuild. | Prefer NemoClaw host commands so the host registry and rebuilt image stay aligned | +| 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 @@ -78,6 +78,6 @@ The mutability table above is a consolidated index of information that lives in - 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 `nemohermes` and `nemoclaw` command, including the environment variables that affect runtime behavior. +- 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. diff --git a/.agents/skills/nemoclaw-user-manage-sandboxes/references/workspace-files.md b/.agents/skills/nemoclaw-user-manage-sandboxes/references/workspace-files.md index 369b8fb0a05..5dba71921c5 100644 --- a/.agents/skills/nemoclaw-user-manage-sandboxes/references/workspace-files.md +++ b/.agents/skills/nemoclaw-user-manage-sandboxes/references/workspace-files.md @@ -125,4 +125,4 @@ The main Hermes configuration lives in `/sandbox/.hermes/config.yaml`, environme 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 `nemohermes connect` when you need to inspect runtime files interactively, or use `openshell sandbox download` and `openshell sandbox upload` for manual file transfer. +Use `nemoclaw connect` when you need to inspect runtime files interactively, or use `openshell sandbox download` and `openshell sandbox upload` for manual file transfer. diff --git a/.agents/skills/nemoclaw-user-monitor-sandbox/SKILL.md b/.agents/skills/nemoclaw-user-monitor-sandbox/SKILL.md index ff81a9b653d..4f58b27d6c4 100644 --- a/.agents/skills/nemoclaw-user-monitor-sandbox/SKILL.md +++ b/.agents/skills/nemoclaw-user-monitor-sandbox/SKILL.md @@ -22,23 +22,11 @@ Use the NemoClaw status, logs, and TUI tools together to inspect sandbox health, Run the status command to view the sandbox state, gateway health, and active inference configuration: - ```bash nemoclaw status ``` - - -```bash -nemohermes status -``` - - For local Ollama and local vLLM routes, `nemoclaw status` also probes the host-side health endpoint directly. - - -For local Ollama and local vLLM routes, `nemohermes 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: @@ -48,41 +36,51 @@ Key output fields include: - 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 status` on the host to check sandbox state. - - -Run `nemohermes 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 logs ``` - - -```bash -nemohermes logs -``` - To follow the log output in real time: - ```bash nemoclaw logs --follow ``` - - -```bash -nemohermes 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/.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/.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: + +```console +$ nemoclaw sandbox exec -- ls -lh /sandbox/.openclaw/agents/main/sessions ``` - + +To copy a session log for offline review, use the OpenShell sandbox download command: + +```console +$ openshell sandbox download /sandbox/.openclaw/agents/main/sessions/.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 @@ -114,32 +112,19 @@ openclaw agent --agent main -m "Test inference" --session-id debug ```bash -nemohermes my-hermes connect +nemoclaw my-hermes connect hermes ``` If the request fails, check the following: - - 1. Run `nemoclaw 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 logs --follow` to view error messages from the blueprint runner. 3. Verify that the inference endpoint is reachable from the host. - - - -1. Run `nemohermes 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 `nemohermes 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 diff --git a/.agents/skills/nemoclaw-user-overview/references/how-it-works.md b/.agents/skills/nemoclaw-user-overview/references/how-it-works.md index d24a5ff1793..406571bb3e5 100644 --- a/.agents/skills/nemoclaw-user-overview/references/how-it-works.md +++ b/.agents/skills/nemoclaw-user-overview/references/how-it-works.md @@ -128,7 +128,7 @@ When the agent tries to reach an unlisted host, OpenShell blocks the request and -- Read [Ecosystem](ecosystem-hermes.md) for stack-level relationships and NemoClaw versus OpenShell-only paths. +- 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. diff --git a/.agents/skills/nemoclaw-user-overview/references/overview.md b/.agents/skills/nemoclaw-user-overview/references/overview.md index f2f26b0a3aa..de911146e84 100644 --- a/.agents/skills/nemoclaw-user-overview/references/overview.md +++ b/.agents/skills/nemoclaw-user-overview/references/overview.md @@ -73,8 +73,8 @@ Navigate to the following topics to learn more about NemoClaw and how to install - [Architecture Overview](how-it-works.md) to understand how NemoClaw works. -- [Ecosystem](ecosystem-hermes.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 `nemohermes`. +- [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. - Inference Options (use the `nemoclaw-user-configure-inference` skill) to check the inference providers that NemoClaw supports and how inference routing works. diff --git a/.agents/skills/nemoclaw-user-overview/references/release-notes.md b/.agents/skills/nemoclaw-user-overview/references/release-notes.md index a5c37671e6f..914733938f2 100644 --- a/.agents/skills/nemoclaw-user-overview/references/release-notes.md +++ b/.agents/skills/nemoclaw-user-overview/references/release-notes.md @@ -6,6 +6,17 @@ 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.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 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). +- Documentation generation now expands OpenClaw and Hermes variants from shared source pages, fixes generated variant route links, hides generated variant pages from navigation where appropriate, and documents remote deploy environment variables, one-off command guidance, SSRF egress interactions, and agent session state paths. For more information, refer to NemoClaw CLI Commands Reference (use the `nemoclaw-user-reference` 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: diff --git a/.agents/skills/nemoclaw-user-reference/SKILL.md b/.agents/skills/nemoclaw-user-reference/SKILL.md index e3531194721..ba86c6db821 100644 --- a/.agents/skills/nemoclaw-user-reference/SKILL.md +++ b/.agents/skills/nemoclaw-user-reference/SKILL.md @@ -12,8 +12,8 @@ license: "Apache-2.0" ## 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. -- **[references/cli-selection-guide.md](references/cli-selection-guide.md)** — Explains when to use `nemoclaw` versus `openshell` for NemoClaw-managed sandboxes, including lifecycle, inference, policy, monitoring, file transfer, and gateway operations. +- **[references/cli-selection-guide.md](references/cli-selection-guide.md)** — Explains when to use `$$nemoclaw` versus `openshell` for NemoClaw-managed sandboxes, including lifecycle, inference, policy, monitoring, file transfer, and gateway operations. - **Load [references/commands-nemohermes.md](references/commands-nemohermes.md)** when looking up a specific `nemohermes` subcommand, flag, argument, or exit code. Includes the full CLI reference for standalone NemoHermes commands and Hermes-specific in-sandbox commands. -- **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/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. diff --git a/.agents/skills/nemoclaw-user-reference/references/cli-selection-guide.md b/.agents/skills/nemoclaw-user-reference/references/cli-selection-guide.md index c6e5ba71192..818f793699b 100644 --- a/.agents/skills/nemoclaw-user-reference/references/cli-selection-guide.md +++ b/.agents/skills/nemoclaw-user-reference/references/cli-selection-guide.md @@ -95,12 +95,12 @@ Use `openshell` when the docs explicitly call for a live OpenShell gateway opera openshell doctor check ``` -- Run one-off commands or move files without starting a NemoClaw chat session: +- Move files, or run raw one-off commands when you intentionally want to bypass NemoClaw's sandbox registry and wrappers: ```bash - openshell sandbox exec -n -- ls -la /sandbox openshell sandbox upload ./local-file /sandbox/ openshell sandbox download /sandbox/output ./output + openshell sandbox exec -n -- env | grep '^HOME=' ``` - Inspect or replace raw OpenShell policy: @@ -134,7 +134,15 @@ It waits for readiness, handles stale SSH host keys after gateway restarts, and Use `openshell sandbox connect ` only when you intentionally want the raw OpenShell connection path. -For a one-off command, use `openshell sandbox exec` instead of opening an interactive shell. +For a one-off command in a NemoClaw-managed sandbox, use `nemoclaw 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 diff --git a/.agents/skills/nemoclaw-user-reference/references/commands-nemohermes.md b/.agents/skills/nemoclaw-user-reference/references/commands-nemohermes.md index 51db2edb9e4..df4b15a6771 100644 --- a/.agents/skills/nemoclaw-user-reference/references/commands-nemohermes.md +++ b/.agents/skills/nemoclaw-user-reference/references/commands-nemohermes.md @@ -463,6 +463,10 @@ If the sandbox or gateway cannot be verified, the command exits non-zero instead When a locally registered sandbox is missing from the live gateway, status preserves the registry entry so the suggested `rebuild --yes` recovery can still find the sandbox metadata. Gateway and dashboard health checks treat HTTP `401` from device auth as a live service, not as an offline gateway. +When sandbox GPU passthrough is enabled, the `Sandbox GPU` line includes the last CUDA usability proof state. +It reports `(CUDA verified)`, `(CUDA unverified)`, or `(last CUDA proof failed: