diff --git a/docs/deployment/sandbox-hardening.mdx b/docs/deployment/sandbox-hardening.mdx index 24d16871bac..d145c1cf175 100644 --- a/docs/deployment/sandbox-hardening.mdx +++ b/docs/deployment/sandbox-hardening.mdx @@ -55,7 +55,8 @@ To make the drop fail-closed instead, set `NEMOCLAW_REQUIRE_CAP_DROP=1` in the e This is opt-in because many hosts cannot drop capabilities, including cloud VMs, Docker Desktop, and WSL environments without `CAP_SETPCAP`. 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: +For defense-in-depth, also drop all Linux capabilities at the container runtime when you launch the image directly. +In the examples below, `nemoclaw-sandbox` is a placeholder for the sandbox image NemoClaw builds during onboarding; substitute the image tag your install produced, which you can find with `docker images`. ```bash docker run --rm \ @@ -138,6 +139,9 @@ Verify Landlock availability: ls /sys/kernel/security/landlock ``` +On a kernel with Landlock support, the path exists and `ls` succeeds. +If it reports `No such file or directory`, the kernel does not expose Landlock, and the sandbox falls back to DAC-only enforcement as described above. + For production deployments, use kernel 5.13+ with Landlock enabled. The `test/e2e/e2e-cloud-experimental/checks/04-landlock-readonly.sh` script validates enforcement at runtime. diff --git a/docs/get-started/quickstart.mdx b/docs/get-started/quickstart.mdx index 07251e261c9..72aefcc5387 100644 --- a/docs/get-started/quickstart.mdx +++ b/docs/get-started/quickstart.mdx @@ -53,9 +53,17 @@ curl -fsSL https://www.nvidia.com/nemoclaw.sh | bash -s -- --yes-i-accept-third- To run both installation and onboarding without prompts, also set non-interactive mode and the provider variables your chosen inference path requires: ```bash -curl -fsSL https://www.nvidia.com/nemoclaw.sh | NEMOCLAW_NON_INTERACTIVE=1 NEMOCLAW_ACCEPT_THIRD_PARTY_SOFTWARE=1 bash +curl -fsSL https://www.nvidia.com/nemoclaw.sh | \ + NEMOCLAW_NON_INTERACTIVE=1 \ + NEMOCLAW_ACCEPT_THIRD_PARTY_SOFTWARE=1 \ + NEMOCLAW_PROVIDER=build \ + NVIDIA_INFERENCE_API_KEY= \ + NEMOCLAW_SANDBOX_NAME=my-gpt-claw \ + bash ``` +The example above uses the NVIDIA Endpoints path. Set `NEMOCLAW_PROVIDER` and the matching API key variable for your chosen path (see the provider table above), and set `NEMOCLAW_SANDBOX_NAME` so the run does not depend on a default left behind by a previous, possibly interrupted, onboard session. + If a scripted installer rerun finds a failed onboarding session, choose whether to discard the saved state with `--fresh` or retry it with `nemoclaw onboard --resume`. For the recovery commands, refer to [Previous onboarding session failed](../reference/troubleshooting#previous-onboarding-session-failed). @@ -274,7 +282,7 @@ openshell term ``` ```bash -nemoclaw my-assistant connect +nemoclaw my-gpt-claw connect # inside the sandbox: openclaw tui ``` diff --git a/docs/inference/inference-options.mdx b/docs/inference/inference-options.mdx index 77936673aa9..e3c8e8eb007 100644 --- a/docs/inference/inference-options.mdx +++ b/docs/inference/inference-options.mdx @@ -211,6 +211,7 @@ To opt in to `/v1/responses`, set `NEMOCLAW_PREFERRED_API=openai-responses` befo Start your model server. The examples below use vLLM, but any OpenAI-compatible server works. +Install vLLM first if it is not already on the host (for example, `pip install vllm`), then start it: ```bash vllm serve meta-llama/Llama-3.1-8B-Instruct --port 8000 @@ -236,7 +237,8 @@ Route, configuration, and authentication failures still fail immediately. ### Non-Interactive Setup -Set the following environment variables for scripted or CI/CD deployments. +Start your OpenAI-compatible server first; the endpoint in `NEMOCLAW_ENDPOINT_URL` must already be serving, or onboarding fails its validation probe. +Then set the following environment variables for scripted or CI/CD deployments. Set `NEMOCLAW_REASONING=true` when the compatible endpoint serves a reasoning-only model. diff --git a/docs/inference/set-up-sub-agent.mdx b/docs/inference/set-up-sub-agent.mdx index 83c6b2ae3c1..93ca525fe58 100644 --- a/docs/inference/set-up-sub-agent.mdx +++ b/docs/inference/set-up-sub-agent.mdx @@ -84,6 +84,7 @@ python3 "$VLM_DEMO_DIR/vlm-subagent/openclaw-patch.py" "$NVIDIA_API_KEY" < /tmp/ ``` The helper reads `/tmp/openclaw.json` from standard input, adds the Omni provider and `vision-operator` entry, and writes the patched config to `/tmp/openclaw.updated.json`. +For a sub-agent other than the Omni example, create `/tmp/openclaw.updated.json` from the exported config with `cp /tmp/openclaw.json /tmp/openclaw.updated.json`, then edit it before the upload step with your provider under `models.providers` and your sub-agent under `agents`. Do not commit `/tmp/openclaw.updated.json` or any other file that contains a real API key. Upload the patched config and refresh the hash. diff --git a/docs/inference/switch-inference-providers.mdx b/docs/inference/switch-inference-providers.mdx index 1c1545386bd..d8387cdbd44 100644 --- a/docs/inference/switch-inference-providers.mdx +++ b/docs/inference/switch-inference-providers.mdx @@ -21,6 +21,17 @@ You do not need to restart the sandbox. - A running NemoClaw sandbox. - The OpenShell CLI on your `PATH`, which NemoClaw uses internally. +## Find the Provider Name + +The `--provider` value must match a provider already configured on the sandbox. +If you are not sure of the exact name, list the configured providers first: + +```bash +$$nemoclaw credentials list +``` + +Use the provider ID shown there in the `inference set` commands below. + ## Switch to a Different Model diff --git a/docs/inference/use-local-inference.mdx b/docs/inference/use-local-inference.mdx index 415e3dd29a4..166e91ebe5c 100644 --- a/docs/inference/use-local-inference.mdx +++ b/docs/inference/use-local-inference.mdx @@ -144,7 +144,8 @@ On native Linux hosts, a firewall can allow the host proxy health check while st 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 +SUBNET=$(docker network inspect openshell-docker --format '{{(index .IPAM.Config 0).Subnet}}') +sudo ufw allow from "$SUBNET" to any port 11435 proto tcp $$nemoclaw onboard ``` @@ -171,9 +172,14 @@ This does not delete downloaded model files. ```bash NEMOCLAW_PROVIDER=ollama \ NEMOCLAW_MODEL=qwen3.5:9b \ - $$nemoclaw onboard --non-interactive --yes + $$nemoclaw onboard --non-interactive --yes --yes-i-accept-third-party-software ``` +Non-interactive runs cannot prompt for the third-party software notice, so include `--yes-i-accept-third-party-software` (or set `NEMOCLAW_ACCEPT_THIRD_PARTY_SOFTWARE=1`) whenever the path may install or start Ollama. +For interactive local inference, choose the provider menu option that matches the local server you already started; use the Ollama option only when NemoClaw should manage Ollama for you. +For vLLM, NIM, or another OpenAI-compatible endpoint, choose the compatible endpoint or custom provider path and enter the host URL from the server setup above. +When later commands use ``, replace it with the sandbox name you chose during onboarding, for example `my-assistant`. + If `NEMOCLAW_MODEL` is not set, NemoClaw selects a default model based on available memory. If `NEMOCLAW_MODEL` names a known bootstrap model (for example `qwen3.6:35b`) that does not fit the host's currently available GPU memory, NemoClaw warns and falls back to the largest known model that does fit. Unknown or custom tags, meaning any value the bootstrap registry has not seen, still pass through. diff --git a/docs/manage-sandboxes/lifecycle.mdx b/docs/manage-sandboxes/lifecycle.mdx index 0cc57c357e2..e968419d2b0 100644 --- a/docs/manage-sandboxes/lifecycle.mdx +++ b/docs/manage-sandboxes/lifecycle.mdx @@ -222,7 +222,7 @@ The standard installer follows the admin-promoted `lkg` release tag by default. If you need a specific release, set `NEMOCLAW_INSTALL_TAG` on the `bash` side of the install pipeline. ```bash -curl -fsSL https://www.nvidia.com/nemoclaw.sh | NEMOCLAW_INSTALL_TAG=v0.0.63 bash +curl -fsSL https://www.nvidia.com/nemoclaw.sh | NEMOCLAW_INSTALL_TAG=v0.0.65 bash $$nemoclaw upgrade-sandboxes --check ``` diff --git a/docs/manage-sandboxes/messaging-channels.mdx b/docs/manage-sandboxes/messaging-channels.mdx index 56cdff49ce5..07da2b66702 100644 --- a/docs/manage-sandboxes/messaging-channels.mdx +++ b/docs/manage-sandboxes/messaging-channels.mdx @@ -175,21 +175,24 @@ NemoClaw also selects the matching network policy preset during policy setup so For scripted setup, export the credentials and optional settings for the channels you want to enable before you run onboarding: ```bash -export TELEGRAM_BOT_TOKEN= +export TELEGRAM_BOT_TOKEN="" export TELEGRAM_REQUIRE_MENTION=1 -export DISCORD_BOT_TOKEN= -export DISCORD_SERVER_ID= -export SLACK_BOT_TOKEN= -export SLACK_APP_TOKEN= -export SLACK_ALLOWED_USERS= -export SLACK_ALLOWED_CHANNELS= -export MSTEAMS_APP_ID= -export MSTEAMS_APP_PASSWORD= -export MSTEAMS_TENANT_ID= -export TEAMS_ALLOWED_USERS= +export DISCORD_BOT_TOKEN="" +export DISCORD_SERVER_ID="" +export SLACK_BOT_TOKEN="" +export SLACK_APP_TOKEN="" +export SLACK_ALLOWED_USERS="" +export SLACK_ALLOWED_CHANNELS="" +export MSTEAMS_APP_ID="" +export MSTEAMS_APP_PASSWORD="" +export MSTEAMS_TENANT_ID="" +export TEAMS_ALLOWED_USERS="" export MSTEAMS_PORT=3978 ``` +The placeholder values are quoted because angle brackets are shell metacharacters; the quotes keep the export from triggering a redirection or syntax error when you paste a real token in place. +Before you run onboarding or channel commands, make sure Docker is running and that your user can access the Docker socket, either through the `docker` group or by using the documented `sudo` workflow for your host. + 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. diff --git a/docs/monitoring/monitor-sandbox-activity.mdx b/docs/monitoring/monitor-sandbox-activity.mdx index e7db15fcb6d..0248b3b371e 100644 --- a/docs/monitoring/monitor-sandbox-activity.mdx +++ b/docs/monitoring/monitor-sandbox-activity.mdx @@ -72,7 +72,7 @@ Use these files for audit trails, compliance review, or replay tooling that incl Inspect the session directory from the host by running a sandbox command. ```bash -$$nemoclaw sandbox exec -- ls -lh /sandbox/.openclaw/agents/main/sessions +$$nemoclaw exec -- ls -lh /sandbox/.openclaw/agents/main/sessions ``` Copy a session log for offline review with the OpenShell sandbox download command. @@ -108,13 +108,13 @@ Send a test inference request to verify that the provider responds. ```bash -$$nemoclaw my-assistant connect +$$nemoclaw connect openclaw agent --agent main -m "Test inference" --session-id debug ``` ```bash -$$nemoclaw my-hermes connect +$$nemoclaw connect hermes ``` @@ -126,6 +126,7 @@ If the request fails, check these items. 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 host can reach the inference endpoint. +4. If the agent reports a context-overflow or token-limit error, clear the conversation with `/reset` (or start a fresh one with `/new`) in the TUI before retrying. ## Related Topics diff --git a/docs/network-policy/integration-policy-examples.mdx b/docs/network-policy/integration-policy-examples.mdx index 171a2b9d646..108246ae37a 100644 --- a/docs/network-policy/integration-policy-examples.mdx +++ b/docs/network-policy/integration-policy-examples.mdx @@ -96,7 +96,9 @@ $$nemoclaw my-assistant policy-add outlook --dry-run $$nemoclaw my-assistant policy-add outlook --yes ``` -Configure the email or calendar tool credentials through the integration you run in the sandbox. +`policy-add` exits non-zero if the `outlook` preset is already applied. If you applied it in the lifecycle example above, run `$$nemoclaw my-assistant policy-remove outlook --yes` first (or skip this apply step). + +Then configure the email or calendar tool credentials through the integration you run in the sandbox. Keep OAuth client secrets and refresh tokens out of policy files. If the tool still fails, run `openshell term`, trigger the workflow again, and inspect the blocked request. diff --git a/docs/reference/troubleshooting.mdx b/docs/reference/troubleshooting.mdx index 905096ad291..c953a330946 100644 --- a/docs/reference/troubleshooting.mdx +++ b/docs/reference/troubleshooting.mdx @@ -13,6 +13,10 @@ content: This page covers common installation, onboarding, and runtime issues, along with resolution steps. + +The diagnostic commands on this page assume `$$nemoclaw` is on your `PATH` (re-source your shell profile after an nvm- or fnm-managed install) and that your user can reach the Docker socket — either as a member of the `docker` group or by running the Docker commands with `sudo`. + + If your issue is not listed here, join the [NemoClaw Discord channel](https://discord.gg/XFpfPv9Uvx) to ask questions and get help from the community. @@ -669,9 +673,11 @@ It also forwards standard CA bundle variables for subprocesses, including `GIT_S If Git still reports `server certificate verification failed`, reconnect to the sandbox and check that the CA variables are present: ```bash -env | grep -E 'SSL_CERT_FILE|GIT_SSL_CAINFO|CURL_CA_BUNDLE|REQUESTS_CA_BUNDLE' +env | grep -E 'SSL_CERT_FILE|GIT_SSL_CAINFO|CURL_CA_BUNDLE|REQUESTS_CA_BUNDLE' || true ``` +`grep` exits non-zero when it finds no matches, so empty output (with the trailing `|| true`) simply means none of these CA variables are set in the current shell. + If they are missing on an older sandbox, upgrade NemoClaw and run: ```bash