Skip to content
Merged
Show file tree
Hide file tree
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions docs/deployment/deploy-to-remote-gpu.md
Original file line number Diff line number Diff line change
Expand Up @@ -62,6 +62,9 @@ $ nemoclaw deploy <instance-name>
```

Replace `<instance-name>` with a name for your remote instance, for example `my-gpu-box`.
The sandbox created on the remote VM uses `NEMOCLAW_SANDBOX_NAME`, or `my-assistant` when the variable is unset.
Sandbox names must be lowercase, start with a letter, contain only letters, numbers, and internal hyphens, and end with a letter or number.
The deploy wrapper validates the sandbox name before it provisions the Brev instance, opens SSH, or starts the remote installer.

The legacy compatibility flow performs the following steps on the VM:

Expand Down
10 changes: 4 additions & 6 deletions docs/get-started/quickstart.md
Original file line number Diff line number Diff line change
Expand Up @@ -73,7 +73,7 @@ The inference provider prompt presents a numbered list.

Pick the option that matches where you want inference traffic to go, then expand the matching helper below for the follow-up prompts and the API key environment variable to set.
For the full list of providers and validation behavior, refer to [Inference Options](../inference/inference-options.md).
Local Ollama appears only when NemoClaw detects Ollama on the host.
Local Ollama appears when NemoClaw detects a usable local Ollama path or can offer an install or start action for your platform.

:::{tip}
Export the API key before launching the installer so the wizard does not have to ask for it.
Expand Down Expand Up @@ -185,9 +185,10 @@ Respond to the wizard as follows.
:::{dropdown} Option 7: Local Ollama
:icon: cpu

Routes inference to a local Ollama instance on `localhost:11434`. This option only appears when Ollama is installed or running on the host.
Routes inference to a local Ollama instance. Depending on your platform, the wizard can use an existing daemon, start an installed daemon, or offer an install action.

No API key is required. NemoClaw generates a token and starts an authenticated proxy so containers can reach Ollama without exposing it to your network.
No API key is required. On non-WSL hosts, NemoClaw generates a token and starts an authenticated proxy so containers can reach Ollama without exposing the daemon directly to your network.
On WSL, NemoClaw can also use Ollama on the Windows host through `host.docker.internal`.

Respond to the wizard as follows.

Expand All @@ -196,9 +197,6 @@ Respond to the wizard as follows.

For setup details, including GPU recommendations and starter model choices, refer to [Use a Local Inference Server](../inference/use-local-inference.md).

:::{warning}
Ollama binds to `0.0.0.0` so the sandbox can reach it through Docker. On public WiFi, any device on the same network can send prompts to your GPU through the Ollama API. Refer to CNVD-2025-04094 and CVE-2024-37032.
:::
:::

:::{dropdown} Experimental: Local NIM and Local vLLM
Expand Down
7 changes: 4 additions & 3 deletions docs/get-started/windows-preparation.md
Original file line number Diff line number Diff line change
Expand Up @@ -96,17 +96,18 @@ If you see "Cannot connect to the Docker daemon", confirm that Docker Desktop is

## Set Up Local Inference with Ollama (Optional)

If you plan to select Ollama as your inference provider during onboarding, run one Ollama instance that WSL can reach.
You can install Ollama inside WSL:
If you plan to select Ollama as your inference provider during onboarding, use one Ollama instance that WSL can reach.
You can install Ollama inside WSL yourself:

```console
$ curl -fsSL https://ollama.com/install.sh | sh
```

If Ollama is not already running in WSL, the onboarding process starts it for you.
If Ollama is installed but not already running in WSL, the onboarding process starts it for you.
You can also start it yourself beforehand with `ollama serve`.

You can also use Ollama for Windows.
During onboarding, NemoClaw can use an already-running Windows-host daemon, start or restart an installed daemon, or install Ollama on the Windows host.
When Ollama runs on the Windows host, NemoClaw detects it from WSL through `host.docker.internal` and pulls missing models through the Ollama HTTP API.
Do not run both the Windows and WSL Ollama instances on port `11434` at the same time.
Use one instance, or move one of them to a different port before running `nemoclaw onboard`.
Expand Down
30 changes: 23 additions & 7 deletions docs/inference/use-local-inference.md
Original file line number Diff line number Diff line change
Expand Up @@ -35,15 +35,16 @@ OpenShell intercepts inference traffic and forwards it to the local endpoint you

- NemoClaw installed.
Refer to the [Quickstart](../get-started/quickstart.md) if you have not installed yet.
- A local model server running, or Ollama installed. The NemoClaw onboard wizard can also start Ollama for you.
- A local model server running, or an Ollama setup that the NemoClaw onboard wizard can use, start, or install.

## Ollama

Ollama is the default local inference option.
The onboard wizard detects Ollama automatically when it is installed or running on the host.

If Ollama is not running, NemoClaw starts it for you.
On macOS, the wizard also offers to install Ollama through Homebrew if it is not present.
If Ollama is installed but not running, NemoClaw starts it for you.
On macOS and Linux, the wizard can also offer to install Ollama when it is not present.
On WSL, the wizard can use, start, restart, or install Ollama on the Windows host through PowerShell interop.

Run the onboard wizard.

Expand All @@ -54,17 +55,32 @@ $ nemoclaw onboard
Select **Local Ollama** from the provider list.
NemoClaw lists installed models or offers starter models if none are installed.
It pulls the selected model, loads it into memory, and validates it before continuing.
On WSL, if Ollama is running on the Windows host, NemoClaw pulls missing models through the Ollama HTTP API instead of requiring the `ollama` CLI inside WSL.
On WSL, if you choose the Windows-host Ollama path, NemoClaw uses `host.docker.internal:11434` and pulls missing models through the Ollama HTTP API instead of requiring the `ollama` CLI inside WSL.

### WSL with Windows-Host Ollama

When NemoClaw runs inside WSL, the provider menu can include Windows-host Ollama actions:

- **Use Ollama on Windows host** when the Windows daemon is already reachable.
- **Restart Ollama on Windows host** when the daemon is installed but only bound to Windows loopback.
- **Start Ollama on Windows host** when Ollama is installed but not running.
- **Install Ollama on Windows host** when Windows does not have Ollama installed.

The install and restart paths set `OLLAMA_HOST=0.0.0.0:11434` on the Windows side so Docker and WSL can reach the daemon through `host.docker.internal`.
Use one Ollama instance on port `11434` at a time.
If both WSL and Windows-host Ollama are running, pick the intended menu entry during onboarding so NemoClaw validates and pulls models against the right daemon.

### Authenticated Reverse Proxy

NemoClaw keeps Ollama bound to `127.0.0.1:11434` and starts a token-gated
reverse proxy on `0.0.0.0:11435`.
On non-WSL hosts, NemoClaw keeps Ollama bound to `127.0.0.1:11434` and starts a token-gated reverse proxy on `0.0.0.0:11435`.
Containers and other hosts on the local network reach Ollama only through the
proxy, which validates a Bearer token before forwarding requests.
Ollama itself is never exposed without authentication.

The onboard wizard manages the proxy automatically:
WSL Ollama paths do not use this proxy.
Windows-host Ollama uses the Windows daemon through `host.docker.internal`.

For non-WSL Ollama setups, the onboard wizard manages the proxy automatically:

- Generates a random 24-byte token on first run and stores it in
`~/.nemoclaw/ollama-proxy-token` with `0600` permissions.
Expand Down
18 changes: 15 additions & 3 deletions docs/reference/commands.md
Original file line number Diff line number Diff line change
Expand Up @@ -133,6 +133,9 @@ or:
$ NEMOCLAW_ACCEPT_THIRD_PARTY_SOFTWARE=1 nemoclaw onboard --non-interactive
```

For scripted installer runs, set `NEMOCLAW_NON_INTERACTIVE=1` and `NEMOCLAW_ACCEPT_THIRD_PARTY_SOFTWARE=1` before invoking `curl -fsSL https://www.nvidia.com/nemoclaw.sh | bash`.
If the installer cannot prompt for the notice in a terminal and no explicit acceptance is set, it exits before installing Node.js or the NemoClaw CLI.

To enable Brave Search in non-interactive mode, set:

```console
Expand All @@ -145,7 +148,7 @@ If Brave Search key validation fails in non-interactive mode, onboarding prints
After fixing the key, re-enable web search with `nemoclaw config web-search`.

The wizard prompts for a sandbox name.
Names must follow RFC 1123 subdomain rules: lowercase alphanumeric characters and hyphens only, and must start and end with an alphanumeric character.
Names must be lowercase, start with a letter, contain only letters, numbers, and internal hyphens, and end with a letter or number.
Uppercase letters are automatically lowercased.
Names that match global CLI commands (`status`, `list`, `debug`, etc.) are rejected to avoid routing conflicts.
Use `--agent <name>` to target a specific installed agent profile during onboarding.
Expand Down Expand Up @@ -217,7 +220,8 @@ If a `--resume` is attempted with a different `--from` path than the original se
#### `--name <sandbox>`

Set the sandbox name without going through the interactive prompt.
The same RFC 1123 and reserved-name rules that the wizard enforces apply here too — names that match a NemoClaw CLI command (`status`, `list`, `debug`, etc.) are rejected up front.
The same name format and reserved-name rules that the wizard enforces apply here too. Names must be lowercase, start with a letter, contain only letters, numbers, and internal hyphens, and end with a letter or number.
Names that match a NemoClaw CLI command (`status`, `list`, `debug`, etc.) are rejected up front.

```console
$ nemoclaw onboard --non-interactive --name my-build --from path/to/Dockerfile
Expand Down Expand Up @@ -257,6 +261,8 @@ Prefer provisioning the remote host separately, then running the standard NemoCl

Deploy NemoClaw to a remote GPU instance through [Brev](https://brev.nvidia.com).
This command remains as a compatibility wrapper for the older Brev-specific bootstrap flow.
The Brev instance name is the positional argument.
The sandbox name comes from `NEMOCLAW_SANDBOX_NAME` and defaults to `my-assistant`; invalid sandbox names fail before Brev provisioning starts.

```console
$ nemoclaw deploy <instance-name>
Expand Down Expand Up @@ -306,11 +312,13 @@ The command probes every inference provider and reports one of three states on t
| `healthy` | The provider endpoint returned a reachable response. |
| `unreachable` | The probe failed. The output includes the endpoint URL and a remediation hint. |
| `not probed` | The endpoint URL is not known (for example, `compatible-*` providers). |
| `not verified` | NemoClaw could not verify the sandbox or gateway state, so it skips inference probing. |

Local providers (Ollama, vLLM) probe the host-side health endpoint.
Remote providers (NVIDIA Endpoints, OpenAI, Anthropic, Gemini) use a lightweight reachability check; any HTTP response, including `401` or `403`, counts as reachable.
No API keys are sent.
For cloud-only providers, the output omits the NIM status line unless a NIM container is registered or an unexpected NIM container is running.
If the sandbox or gateway cannot be verified, the command exits non-zero instead of reporting healthy inference from stale registry state.

A `Connected` line reports whether the sandbox has any active SSH sessions and, if so, how many.
The sandbox list in the status output includes the dashboard port suffix for sandboxes with a recorded dashboard port.
Expand Down Expand Up @@ -342,11 +350,13 @@ $ nemoclaw my-assistant doctor [--json]

View sandbox logs.
Use `--follow` to stream output in real time.
Use `--tail <lines>` or `-n <lines>` to limit the number of returned lines.
Use `--since <duration>` to show recent logs only, such as `5m`, `1h`, or `30s`.
The command reads both OpenClaw gateway output and OpenShell audit events, so policy denials appear alongside the gateway log stream.
If one log source is unavailable, NemoClaw prints a warning and keeps reading the remaining source.

```console
$ nemoclaw my-assistant logs [--follow]
$ nemoclaw my-assistant logs [--follow] [--tail <lines>|-n <lines>] [--since <duration>]
```

### `nemoclaw <name> gateway-token`
Expand Down Expand Up @@ -779,9 +789,11 @@ This command remains as a compatibility alias to `nemoclaw tunnel stop`.
### `nemoclaw status`

Show the sandbox list and the status of host auxiliary services (for example cloudflared).
Pass `--json` for machine-readable output with registered sandboxes, service state, inference routes, and messaging health.

```console
$ nemoclaw status
$ nemoclaw status --json
```

### `nemoclaw setup`
Expand Down
2 changes: 1 addition & 1 deletion docs/reference/troubleshooting.md
Original file line number Diff line number Diff line change
Expand Up @@ -304,7 +304,7 @@ The `install-openshell.sh` script also enforces this constraint and pins fresh i

### Invalid sandbox name

Sandbox names must follow RFC 1123 subdomain rules: lowercase alphanumeric characters and hyphens only, and must start and end with an alphanumeric character.
Sandbox names must be lowercase, start with a letter, contain only letters, numbers, and internal hyphens, and end with a letter or number.
Uppercase letters are automatically lowercased.

Names that collide with global CLI commands are also rejected.
Expand Down
Loading