diff --git a/.agents/skills/nemoclaw-user-configure-inference/SKILL.md b/.agents/skills/nemoclaw-user-configure-inference/SKILL.md index 4e33fa0d2..8bbd32248 100644 --- a/.agents/skills/nemoclaw-user-configure-inference/SKILL.md +++ b/.agents/skills/nemoclaw-user-configure-inference/SKILL.md @@ -322,7 +322,23 @@ $ NEMOCLAW_EXPERIMENTAL=1 \ To select a specific model, set `NEMOCLAW_MODEL`. -## Step 9: Verify the Configuration +## Step 9: Timeout Configuration + +Local inference requests use a default timeout of 180 seconds. +Large prompts on hardware such as DGX Spark can exceed shorter timeouts, so NemoClaw sets a higher default for local providers (Ollama, vLLM, NIM). + +To override the timeout, set the `NEMOCLAW_LOCAL_INFERENCE_TIMEOUT` environment variable before onboarding: + +```console +$ export NEMOCLAW_LOCAL_INFERENCE_TIMEOUT=300 +$ nemoclaw onboard +``` + +The value is in seconds. +This setting is baked into the sandbox at build time. +Changing it after onboarding requires re-running `nemoclaw onboard`. + +## Step 10: Verify the Configuration After onboarding completes, confirm the active provider and model. @@ -332,7 +348,7 @@ $ nemoclaw status The output shows the provider label (for example, "Local vLLM" or "Other OpenAI-compatible endpoint") and the active model. -## Step 10: Switch Models at Runtime +## Step 11: Switch Models at Runtime You can change the model without re-running onboard. Refer to Switch Inference Models (see the `nemoclaw-user-configure-inference` skill) for the full procedure. diff --git a/.agents/skills/nemoclaw-user-deploy-remote/SKILL.md b/.agents/skills/nemoclaw-user-deploy-remote/SKILL.md index 37e4d8c80..69f09b35f 100644 --- a/.agents/skills/nemoclaw-user-deploy-remote/SKILL.md +++ b/.agents/skills/nemoclaw-user-deploy-remote/SKILL.md @@ -103,7 +103,23 @@ default), so no extra configuration is needed. > If you disable device auth for a remote deployment, any device that can reach the dashboard origin can connect without pairing. > Avoid this on internet-reachable or shared-network deployments. -## Step 7: GPU Configuration +## Step 7: Proxy Configuration + +NemoClaw routes sandbox traffic through a gateway proxy that defaults to `10.200.0.1:3128`. +If your network requires a different proxy, set `NEMOCLAW_PROXY_HOST` and `NEMOCLAW_PROXY_PORT` before onboarding: + +```console +$ export NEMOCLAW_PROXY_HOST=proxy.example.com +$ export NEMOCLAW_PROXY_PORT=8080 +$ nemoclaw onboard +``` + +These values are baked into the sandbox image at build time. +Only alphanumeric characters, dots, hyphens, and colons are accepted for the host. +The port must be numeric (0-65535). +Changing the proxy after onboarding requires re-running `nemoclaw onboard`. + +## Step 8: GPU Configuration The deploy script uses the `NEMOCLAW_GPU` environment variable to select the GPU type. The default value is `a2-highgpu-1g:nvidia-tesla-a100:1`. @@ -122,12 +138,12 @@ NemoClaw configures those channels during `nemoclaw onboard`. Tokens are registe `nemoclaw start` does not start Telegram (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 (see the `nemoclaw-user-reference` skill). -## Step 8: Create a Telegram Bot +## Step 9: Create a Telegram Bot Open Telegram and send `/newbot` to [@BotFather](https://t.me/BotFather). Follow the prompts to create a bot and copy the bot token. -## Step 9: Provide the Bot Token and Optional Allowlist +## Step 10: Provide the Bot Token and Optional Allowlist Onboarding reads Telegram credentials from either host environment variables or the NemoClaw credential store (`getCredential` / `saveCredential` in the onboard flow). You do not have to export variables if you enter the token when the wizard asks. @@ -150,7 +166,7 @@ Press **1** to toggle Telegram on or off, then **Enter** when done. If the token is not already in the environment or credential store, the wizard prompts for it and saves it to the store. If `TELEGRAM_ALLOWED_IDS` is not set, the wizard can prompt for allowed sender IDs for Telegram DMs (you can leave this blank and rely on OpenClaw pairing instead). -## Step 10: Run `nemoclaw onboard` +## Step 11: Run `nemoclaw onboard` Complete the rest of the wizard so the blueprint can create OpenShell providers (for example `-telegram-bridge`), bake channel configuration into the image (`NEMOCLAW_MESSAGING_CHANNELS_B64`), and start the sandbox. @@ -160,12 +176,12 @@ If you add or change `TELEGRAM_BOT_TOKEN` (or toggle channels) after a sandbox a For a full first-time flow, refer to Quickstart (see the `nemoclaw-user-get-started` skill). -## Step 11: Confirm Delivery +## Step 12: Confirm Delivery After the sandbox is running, send a message to your bot in Telegram. If something fails, use `openshell term` on the host, check gateway logs, and verify network policy allows the Telegram API (see Customize the Network Policy (see the `nemoclaw-user-manage-policy` skill) and the `telegram` preset). -## Step 12: `nemoclaw start` (cloudflared Only) +## Step 13: `nemoclaw start` (cloudflared Only) `nemoclaw start` starts cloudflared when it is installed, which can expose the dashboard with a public URL. It does not affect Telegram connectivity. diff --git a/.agents/skills/nemoclaw-user-manage-policy/SKILL.md b/.agents/skills/nemoclaw-user-manage-policy/SKILL.md index 335c07ddb..78926afc4 100644 --- a/.agents/skills/nemoclaw-user-manage-policy/SKILL.md +++ b/.agents/skills/nemoclaw-user-manage-policy/SKILL.md @@ -140,9 +140,10 @@ Available presets: | Preset | Endpoints | |--------|-----------| +| `brave` | Brave Search API | +| `brew` | Homebrew (Linuxbrew) package manager | | `discord` | Discord webhook API | -| `docker` | Docker Hub, NVIDIA container registry | -| `huggingface` | Hugging Face model registry | +| `huggingface` | Hugging Face inference router | | `jira` | Atlassian Jira API | | `npm` | npm and Yarn registries | | `outlook` | Microsoft 365 and Outlook | diff --git a/.agents/skills/nemoclaw-user-reference/references/commands.md b/.agents/skills/nemoclaw-user-reference/references/commands.md index 814cd8326..c3fb615ca 100644 --- a/.agents/skills/nemoclaw-user-reference/references/commands.md +++ b/.agents/skills/nemoclaw-user-reference/references/commands.md @@ -167,11 +167,22 @@ $ nemoclaw my-assistant destroy Add a policy preset to a sandbox. Presets extend the baseline network policy with additional endpoints. +Before applying, the command shows which endpoints the preset would open and prompts for confirmation. ```console $ nemoclaw my-assistant policy-add ``` +| Flag | Description | +|------|-------------| +| `--dry-run` | Preview the endpoints a preset would open without applying changes | + +Use `--dry-run` to audit a preset before applying it: + +```console +$ nemoclaw my-assistant policy-add --dry-run +``` + ### `nemoclaw policy-list` List available policy presets and show which ones are applied to the sandbox. @@ -242,6 +253,28 @@ $ nemoclaw debug [--quick] [--sandbox NAME] [--output PATH] | `--sandbox NAME` | Target a specific sandbox (default: auto-detect) | | `--output PATH` | Write diagnostics tarball to the given path | +### `nemoclaw credentials list` + +List the names of all credentials stored in `~/.nemoclaw/credentials.json`. +Values are not printed. + +```console +$ nemoclaw credentials list +``` + +### `nemoclaw credentials reset ` + +Remove a stored credential by name. +After removal, re-running `nemoclaw onboard` re-prompts for that key. + +```console +$ nemoclaw credentials reset NVIDIA_API_KEY +``` + +| Flag | Description | +|------|-------------| +| `--yes`, `-y` | Skip the confirmation prompt | + ### `nemoclaw uninstall` Run `uninstall.sh` to remove NemoClaw sandboxes, gateway resources, related images and containers, and local state. diff --git a/.agents/skills/nemoclaw-user-reference/references/troubleshooting.md b/.agents/skills/nemoclaw-user-reference/references/troubleshooting.md index 5ec77a265..df6646f5a 100644 --- a/.agents/skills/nemoclaw-user-reference/references/troubleshooting.md +++ b/.agents/skills/nemoclaw-user-reference/references/troubleshooting.md @@ -54,6 +54,18 @@ $ sudo systemctl start docker On macOS with Docker Desktop, open the Docker Desktop application and wait for it to finish starting before retrying. +### Docker permission denied on Linux + +On Linux, if the Docker daemon is running but you see "permission denied" errors, your user may not be in the `docker` group. +Add your user and activate the group in the current shell: + +```console +$ sudo usermod -aG docker $USER +$ newgrp docker +``` + +Then retry `nemoclaw onboard`. + ### macOS first-run failures The two most common first-run failures on macOS are missing developer tools and Docker connection errors. @@ -231,6 +243,14 @@ $ nemoclaw status If the endpoint is correct but requests still fail, check for network policy rules that may block the connection. Then verify the credential and base URL for the provider you selected during onboarding. +For local providers (Ollama, vLLM, NIM), the default timeout is 180 seconds. +If large prompts still cause timeouts, increase it with `NEMOCLAW_LOCAL_INFERENCE_TIMEOUT` before re-running onboard: + +```console +$ export NEMOCLAW_LOCAL_INFERENCE_TIMEOUT=300 +$ nemoclaw onboard +``` + ### `NEMOCLAW_DISABLE_DEVICE_AUTH=1` does not change an existing sandbox This is expected behavior. @@ -240,6 +260,26 @@ Changing or exporting it later does not rewrite the baked `openclaw.json` inside If you need a different device-auth setting, rerun onboarding so NemoClaw rebuilds the sandbox image with the desired configuration. For the security trade-offs, refer to Security Best Practices (see the `nemoclaw-user-configure-security` skill). +### Sandbox lost after gateway restart + +Sandboxes created with OpenShell versions older than 0.0.24 can become unreachable after a gateway restart because SSH secrets were not persisted. +Running `nemoclaw onboard` automatically upgrades OpenShell to 0.0.24 or later during the preflight check. +After the upgrade, recreate the sandbox with `nemoclaw onboard`. + +### Agent cannot reach external hosts through a proxy + +NemoClaw uses a default proxy address of `10.200.0.1:3128` (the OpenShell-injected gateway). +If your environment uses a different proxy, set `NEMOCLAW_PROXY_HOST` and `NEMOCLAW_PROXY_PORT` before onboarding: + +```console +$ export NEMOCLAW_PROXY_HOST=proxy.example.com +$ export NEMOCLAW_PROXY_PORT=8080 +$ nemoclaw onboard +``` + +These are build-time settings baked into the sandbox image. +Changing them after onboarding requires re-running `nemoclaw onboard` to rebuild the image. + ### Agent cannot reach an external host OpenShell blocks outbound connections to hosts not listed in the network policy. diff --git a/docs/deployment/deploy-to-remote-gpu.md b/docs/deployment/deploy-to-remote-gpu.md index fd7fa8379..ef0011429 100644 --- a/docs/deployment/deploy-to-remote-gpu.md +++ b/docs/deployment/deploy-to-remote-gpu.md @@ -120,6 +120,22 @@ If you disable device auth for a remote deployment, any device that can reach th Avoid this on internet-reachable or shared-network deployments. ::: +## Proxy Configuration + +NemoClaw routes sandbox traffic through a gateway proxy that defaults to `10.200.0.1:3128`. +If your network requires a different proxy, set `NEMOCLAW_PROXY_HOST` and `NEMOCLAW_PROXY_PORT` before onboarding: + +```console +$ export NEMOCLAW_PROXY_HOST=proxy.example.com +$ export NEMOCLAW_PROXY_PORT=8080 +$ nemoclaw onboard +``` + +These values are baked into the sandbox image at build time. +Only alphanumeric characters, dots, hyphens, and colons are accepted for the host. +The port must be numeric (0-65535). +Changing the proxy after onboarding requires re-running `nemoclaw onboard`. + ## GPU Configuration The deploy script uses the `NEMOCLAW_GPU` environment variable to select the GPU type. diff --git a/docs/inference/use-local-inference.md b/docs/inference/use-local-inference.md index 43977a857..4f09296d8 100644 --- a/docs/inference/use-local-inference.md +++ b/docs/inference/use-local-inference.md @@ -205,6 +205,22 @@ $ NEMOCLAW_EXPERIMENTAL=1 \ To select a specific model, set `NEMOCLAW_MODEL`. +## Timeout Configuration + +Local inference requests use a default timeout of 180 seconds. +Large prompts on hardware such as DGX Spark can exceed shorter timeouts, so NemoClaw sets a higher default for local providers (Ollama, vLLM, NIM). + +To override the timeout, set the `NEMOCLAW_LOCAL_INFERENCE_TIMEOUT` environment variable before onboarding: + +```console +$ export NEMOCLAW_LOCAL_INFERENCE_TIMEOUT=300 +$ nemoclaw onboard +``` + +The value is in seconds. +This setting is baked into the sandbox at build time. +Changing it after onboarding requires re-running `nemoclaw onboard`. + ## Verify the Configuration After onboarding completes, confirm the active provider and model. diff --git a/docs/network-policy/customize-network-policy.md b/docs/network-policy/customize-network-policy.md index 6da052d3c..737b6bca0 100644 --- a/docs/network-policy/customize-network-policy.md +++ b/docs/network-policy/customize-network-policy.md @@ -103,9 +103,10 @@ Available presets: | Preset | Endpoints | |--------|-----------| +| `brave` | Brave Search API | +| `brew` | Homebrew (Linuxbrew) package manager | | `discord` | Discord webhook API | -| `docker` | Docker Hub, NVIDIA container registry | -| `huggingface` | Hugging Face model registry | +| `huggingface` | Hugging Face inference router | | `jira` | Atlassian Jira API | | `npm` | npm and Yarn registries | | `outlook` | Microsoft 365 and Outlook | diff --git a/docs/reference/commands.md b/docs/reference/commands.md index aafde7699..c65c0ed9f 100644 --- a/docs/reference/commands.md +++ b/docs/reference/commands.md @@ -195,11 +195,22 @@ $ nemoclaw my-assistant destroy Add a policy preset to a sandbox. Presets extend the baseline network policy with additional endpoints. +Before applying, the command shows which endpoints the preset would open and prompts for confirmation. ```console $ nemoclaw my-assistant policy-add ``` +| Flag | Description | +|------|-------------| +| `--dry-run` | Preview the endpoints a preset would open without applying changes | + +Use `--dry-run` to audit a preset before applying it: + +```console +$ nemoclaw my-assistant policy-add --dry-run +``` + ### `nemoclaw policy-list` List available policy presets and show which ones are applied to the sandbox. @@ -272,6 +283,28 @@ $ nemoclaw debug [--quick] [--sandbox NAME] [--output PATH] | `--sandbox NAME` | Target a specific sandbox (default: auto-detect) | | `--output PATH` | Write diagnostics tarball to the given path | +### `nemoclaw credentials list` + +List the names of all credentials stored in `~/.nemoclaw/credentials.json`. +Values are not printed. + +```console +$ nemoclaw credentials list +``` + +### `nemoclaw credentials reset ` + +Remove a stored credential by name. +After removal, re-running `nemoclaw onboard` re-prompts for that key. + +```console +$ nemoclaw credentials reset NVIDIA_API_KEY +``` + +| Flag | Description | +|------|-------------| +| `--yes`, `-y` | Skip the confirmation prompt | + ### `nemoclaw uninstall` Run `uninstall.sh` to remove NemoClaw sandboxes, gateway resources, related images and containers, and local state. diff --git a/docs/reference/troubleshooting.md b/docs/reference/troubleshooting.md index 1d91444f9..996e3d605 100644 --- a/docs/reference/troubleshooting.md +++ b/docs/reference/troubleshooting.md @@ -82,6 +82,18 @@ $ sudo systemctl start docker On macOS with Docker Desktop, open the Docker Desktop application and wait for it to finish starting before retrying. +### Docker permission denied on Linux + +On Linux, if the Docker daemon is running but you see "permission denied" errors, your user may not be in the `docker` group. +Add your user and activate the group in the current shell: + +```console +$ sudo usermod -aG docker $USER +$ newgrp docker +``` + +Then retry `nemoclaw onboard`. + ### macOS first-run failures The two most common first-run failures on macOS are missing developer tools and Docker connection errors. @@ -263,6 +275,14 @@ $ nemoclaw status If the endpoint is correct but requests still fail, check for network policy rules that may block the connection. Then verify the credential and base URL for the provider you selected during onboarding. +For local providers (Ollama, vLLM, NIM), the default timeout is 180 seconds. +If large prompts still cause timeouts, increase it with `NEMOCLAW_LOCAL_INFERENCE_TIMEOUT` before re-running onboard: + +```console +$ export NEMOCLAW_LOCAL_INFERENCE_TIMEOUT=300 +$ nemoclaw onboard +``` + ### `NEMOCLAW_DISABLE_DEVICE_AUTH=1` does not change an existing sandbox This is expected behavior. @@ -272,6 +292,26 @@ Changing or exporting it later does not rewrite the baked `openclaw.json` inside If you need a different device-auth setting, rerun onboarding so NemoClaw rebuilds the sandbox image with the desired configuration. For the security trade-offs, refer to [Security Best Practices](../security/best-practices.md). +### Sandbox lost after gateway restart + +Sandboxes created with OpenShell versions older than 0.0.24 can become unreachable after a gateway restart because SSH secrets were not persisted. +Running `nemoclaw onboard` automatically upgrades OpenShell to 0.0.24 or later during the preflight check. +After the upgrade, recreate the sandbox with `nemoclaw onboard`. + +### Agent cannot reach external hosts through a proxy + +NemoClaw uses a default proxy address of `10.200.0.1:3128` (the OpenShell-injected gateway). +If your environment uses a different proxy, set `NEMOCLAW_PROXY_HOST` and `NEMOCLAW_PROXY_PORT` before onboarding: + +```console +$ export NEMOCLAW_PROXY_HOST=proxy.example.com +$ export NEMOCLAW_PROXY_PORT=8080 +$ nemoclaw onboard +``` + +These are build-time settings baked into the sandbox image. +Changing them after onboarding requires re-running `nemoclaw onboard` to rebuild the image. + ### Agent cannot reach an external host OpenShell blocks outbound connections to hosts not listed in the network policy.