Skip to content

docs: fix onboarding, topology, and messaging channels #3762

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
Iamkewl wants to merge 1 commit into from
Closed

docs: fix onboarding, topology, and messaging channels #3762

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
2 changes: 1 addition & 1 deletion docs/about/ecosystem.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -78,7 +78,7 @@ The following table compares the two paths.
| Image hardening | The community image includes standard system tools for general-purpose use. | NemoClaw strips build toolchains (`gcc`, `g++`, `make`) and network probes (`netcat`) from the runtime image to reduce attack surface. |
| Filesystem policy | The community sandbox bundles a policy for OpenClaw. | NemoClaw defines a targeted read-only and read-write layout. System paths (`/usr`, `/lib`, `/etc`) are read-only. The agent's home directory (`/sandbox`) and config directory (`/sandbox/.openclaw`) are writable by default so the agent can manage config, install skills, and write to standard paths natively. |
| Inference setup | The community sandbox includes an `openclaw-start` script that runs OpenClaw's onboarding wizard inside the sandbox. You can also create providers and configure OpenShell inference routing manually from the host. | NemoClaw's onboarding wizard validates your credential from the host, lets you select a provider (NVIDIA Endpoints, OpenAI, Anthropic, Google Gemini, Ollama, and compatible endpoints), and configures OpenShell's inference routing automatically. Credentials stay on the host and are delivered through OpenShell's provider system. |
| Channel messaging | OpenShell provides the credential provider system and L7 proxy that delivers channel tokens securely (including path-based resolution for Telegram's `/bot<token>/` URL pattern). You create providers and configure OpenClaw's channel settings manually. | NemoClaw automates channel setup during onboarding: it collects bot tokens, registers them as OpenShell providers, and bakes OpenClaw channel config with placeholder tokens that OpenShell's proxy resolves at egress. No separate bridge process runs on the host. |
| Channel messaging | OpenShell provides the credential provider system and L7 proxy that delivers channel tokens securely (including path-based resolution for Telegram's `/bot<token>/` URL pattern). You create providers and configure OpenClaw's channel settings manually. | NemoClaw automates channel setup during onboarding: it collects bot tokens (Telegram, Discord, Slack, WeChat), registers them as OpenShell providers, and bakes OpenClaw channel config with placeholder tokens that OpenShell's proxy resolves at egress. No separate bridge process runs on the host. |
| Blueprint versioning | No blueprint. The community sandbox uses whatever image version is currently published. | NemoClaw downloads the blueprint artifact, checks version compatibility, and verifies its digest before applying. Running `nemoclaw onboard` on different machines produces the same sandbox. |
| State migration | Not included. | NemoClaw migrates agent state across machines with credential stripping and integrity verification. |
| Process count limits | OpenShell applies seccomp and privilege dropping. You set process count limits manually with `--ulimit` or orchestrator config. | NemoClaw applies `ulimit -u 512` in the container entrypoint to cap the process count and mitigate fork-bomb attacks, on top of OpenShell's seccomp and privilege dropping. |
Expand Down
4 changes: 2 additions & 2 deletions docs/about/overview.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -32,8 +32,8 @@ NemoClaw provides the following product capabilities.
| Guided onboarding | Validates credentials, selects providers, and creates a working sandbox in one command. |
| Hardened blueprint | A security-first Dockerfile with capability drops, least-privilege network rules, and declarative policy. |
| State management | Safe migration of agent state across machines with credential stripping and integrity verification. |
| Messaging channels | OpenShell-managed processes connect Telegram, Discord, Slack, and similar platforms to the sandboxed agent. NemoClaw configures channels during onboarding; OpenShell supplies the native constructs, credential flow, and runtime supervision. |
| Routed inference | Provider-routed model calls through the OpenShell gateway, transparent to the agent. Supports NVIDIA Endpoints, OpenAI, Anthropic, Google Gemini, compatible endpoints, local Ollama, local vLLM, and the Model Router. |
| Messaging channels | OpenShell-managed processes connect Telegram, Discord, Slack, WeChat, and similar platforms to the sandboxed agent. NemoClaw configures channels during onboarding; OpenShell supplies the native constructs, credential flow, and runtime supervision. |
| Routed inference | Provider-routed model calls through the OpenShell gateway to your selected provider, transparent to the agent. You can switch providers or models. Refer to [Inference Options](/inference/inference-options). |
| Layered protection | Network, filesystem, process, and inference controls that can be hot-reloaded or locked at creation. |

## Benefits of Using NemoClaw
Expand Down
39 changes: 23 additions & 16 deletions docs/get-started/quickstart.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -69,7 +69,9 @@ If you export `NEMOCLAW_DISABLE_DEVICE_AUTH` after onboarding finishes, it has n

### Respond to the Onboard Wizard

After the installer launches `nemoclaw onboard`, the wizard runs preflight checks, starts or reuses the OpenShell gateway, and asks for an inference provider, sandbox name, optional web search, optional messaging channels, and network policy presets.
After the installer launches `nemoclaw onboard`, the wizard runs preflight checks and starts or reuses the OpenShell gateway.
It asks for an inference provider, prompts for an API key when one is missing, then asks for the model and sandbox name.
It shows a review summary for confirmation. After confirmation, it prompts for web search, messaging, and network policy presets.
At any prompt, press Enter to accept the default shown in `[brackets]`, type `back` to return to the previous prompt, or type `exit` to quit.
If existing sandbox sessions are running, the installer warns before onboarding because the setup can rebuild or upgrade sandboxes after the new sandbox launches.

Expand All @@ -82,9 +84,11 @@ The inference provider prompt presents a numbered list.
4) Anthropic
5) Other Anthropic-compatible endpoint
6) Google Gemini
7) Local Ollama (localhost:11434)
7) Local Ollama (localhost:11434) - running (suggested)
8) Model Router (experimental)
Choose [1]:

Ollama displays the running suffix only when it is detected and running.
```

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.
Expand All @@ -98,7 +102,7 @@ For example, run `export NVIDIA_API_KEY=<your-key>` before `curl ... | bash`.
If you entered a key incorrectly, refer to [Reset a Stored Credential](/manage-sandboxes/lifecycle#reset-a-stored-credential) to clear and re-enter it.
</Tip>

<Accordion title="Option 1: NVIDIA Endpoints">
<Accordion title="Option 1 NVIDIA Endpoints">

Routes inference to models hosted on [build.nvidia.com](https://build.nvidia.com).

Expand All @@ -108,16 +112,17 @@ Respond to the wizard as follows.

1. At the `Choose [1]:` prompt, press Enter (or type `1`) to select **NVIDIA Endpoints**.
2. At the `NVIDIA_API_KEY:` prompt, paste your key if it is not already exported.
3. At the `Choose model [1]:` prompt, pick a curated model from the list (for example, `Nemotron 3 Super 120B`, `GLM-5`, `MiniMax M2.7`, `GPT-OSS 120B`, or `DeepSeek V4 Pro`), or pick `Other...` to enter any model ID from the [NVIDIA Endpoints catalog](https://build.nvidia.com).
3. At the `Choose model [1]:` prompt, pick a model from the dynamic list (populated based on the provider) shown in the wizard, or pick `Other...` to enter any model ID from the [NVIDIA Endpoints catalog](https://build.nvidia.com).

NemoClaw validates the model against the catalog API before creating the sandbox.

<Tip>
Use this option for Nemotron and other models hosted on `build.nvidia.com`. If you run NVIDIA Nemotron from a self-hosted NIM, an enterprise gateway, or any other endpoint, choose **Option 3** instead, since all Nemotron models expose OpenAI-compatible APIs.
Use this option for Nemotron and other models hosted on `build.nvidia.com`.
If you run NVIDIA Nemotron from a self-hosted NIM, an enterprise gateway, or any other endpoint, choose **Option 3** instead, since all Nemotron models expose OpenAI-compatible APIs.
</Tip>
</Accordion>

<Accordion title="Option 2: OpenAI">
<Accordion title="Option 2 OpenAI">

Routes inference to the OpenAI API at `https://api.openai.com/v1`.

Expand All @@ -127,10 +132,10 @@ Respond to the wizard as follows.

1. At the `Choose [1]:` prompt, type `2` to select **OpenAI**.
2. At the `OPENAI_API_KEY:` prompt, paste your key if it is not already exported.
3. At the `Choose model [1]:` prompt, pick a curated model (for example, `gpt-5.4`, `gpt-5.4-mini`, `gpt-5.4-nano`, or `gpt-5.4-pro-2026-03-05`), or pick **Other...** to enter any OpenAI model ID.
3. At the `Choose model [1]:` prompt, pick a model from the dynamic list (populated based on the provider) shown in the wizard, or pick `Other...` to enter any OpenAI model ID.
</Accordion>

<Accordion title="Option 3: Other OpenAI-Compatible Endpoint">
<Accordion title="Option 3 Other OpenAI-Compatible Endpoint">

Routes inference to any server that implements `/v1/chat/completions`, including OpenRouter, LocalAI, llama.cpp, vLLM behind a proxy, and any compatible gateway.

Expand All @@ -153,7 +158,7 @@ NVIDIA Nemotron models expose OpenAI-compatible APIs, so this option is the righ
</Tip>
</Accordion>

<Accordion title="Option 4: Anthropic">
<Accordion title="Option 4 Anthropic">

Routes inference to the Anthropic Messages API at `https://api.anthropic.com`.

Expand All @@ -163,10 +168,10 @@ Respond to the wizard as follows.

1. At the `Choose [1]:` prompt, type `4` to select **Anthropic**.
2. At the `ANTHROPIC_API_KEY:` prompt, paste your key if it is not already exported.
3. At the `Choose model [1]:` prompt, pick a curated model (for example, `claude-sonnet-4-6`, `claude-haiku-4-5`, or `claude-opus-4-6`), or pick **Other...** to enter any Claude model ID.

</Accordion>

<Accordion title="Option 5: Other Anthropic-Compatible Endpoint">
<Accordion title="Option 5 Other Anthropic-Compatible Endpoint">

Routes inference to any server that implements the Anthropic Messages API at `/v1/messages`, including Claude proxies, Bedrock-compatible gateways, and self-hosted Anthropic-compatible servers.

Expand All @@ -180,7 +185,7 @@ Respond to the wizard as follows.
4. At the `Other Anthropic-compatible endpoint model []:` prompt, enter the model ID exactly as it appears in your gateway's model catalog.
</Accordion>

<Accordion title="Option 6: Google Gemini">
<Accordion title="Option 6 Google Gemini">

Routes inference to Google's OpenAI-compatible Gemini endpoint at `https://generativelanguage.googleapis.com/v1beta/openai/`.

Expand All @@ -190,26 +195,26 @@ Respond to the wizard as follows.

1. At the `Choose [1]:` prompt, type `6` to select **Google Gemini**.
2. At the `GEMINI_API_KEY:` prompt, paste your key if it is not already exported.
3. At the `Choose model [5]:` prompt, pick a curated model (for example, `gemini-3.1-pro-preview`, `gemini-3.1-flash-lite-preview`, `gemini-3-flash-preview`, `gemini-2.5-pro`, `gemini-2.5-flash`, or `gemini-2.5-flash-lite`), or pick **Other...** to enter any Gemini model ID.

</Accordion>

<Accordion title="Option 7: Local Ollama">
<Accordion title="Option 7 Local Ollama">

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. 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.
When the wizard prints `proxy on :11435`, it refers to the authenticated reverse proxy described in [Use a Local Inference Server](/inference/use-local-inference).
On WSL, NemoClaw can also use Ollama on the Windows host through `host.docker.internal`.

Respond to the wizard as follows.

1. At the `Choose [1]:` prompt, type `7` to select **Local Ollama**.
2. At the `Choose model [1]:` prompt, pick from **Ollama models** if any are already installed. If none are installed, pick a **starter model** to pull and load now, or pick **Other...** to enter any Ollama model ID.

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

</Accordion>

<Accordion title="Option 8: Model Router">
<Accordion title="Option 8 Model Router">

Starts a host-side model router and routes sandbox inference through OpenShell to that router.
The router chooses from the model pool in `nemoclaw-blueprint/router/pool-config.yaml` for each request.
Expand Down Expand Up @@ -357,6 +362,8 @@ nemoclaw my-assistant connect
openclaw tui
```

NemoClaw rejects the `--local` flag inside sandboxes because it bypasses gateway protections.

## Next Steps

Navigate to the following topics to learn more about NemoClaw.
Expand Down
24 changes: 15 additions & 9 deletions docs/inference/set-up-sub-agent.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -55,8 +55,9 @@ Fetch the current OpenClaw config from the sandbox, patch it with your auxiliary

```console
$ export SANDBOX=my-assistant
$ export DOCKER_CTR=openshell-cluster-nemoclaw
$ docker exec "$DOCKER_CTR" kubectl exec -n openshell "$SANDBOX" -c agent -- cat /sandbox/.openclaw/openclaw.json > /tmp/openclaw.json
$ export DOCKER_CTR=$(docker ps --filter "name=openshell-$SANDBOX" --format "{{.Names}}" | head -n 1)
$ if [ -z "$DOCKER_CTR" ]; then echo "Error: No container found for sandbox $SANDBOX" >&2; exit 1; fi
$ docker exec "$DOCKER_CTR" cat /sandbox/.openclaw/openclaw.json > /tmp/openclaw.json
Comment thread
coderabbitai[bot] marked this conversation as resolved.
```

Create `/tmp/openclaw.updated.json` with the OpenClaw sub-agent config.
Expand All @@ -66,12 +67,17 @@ Upload the patched config and refresh the hash.
In the default mutable state, this keeps the local hash consistent but does not make it tamper-proof; lock the config root-owned and read-only afterward if the sandbox should enforce config integrity at startup.

```console
$ docker exec "$DOCKER_CTR" kubectl exec -n openshell "$SANDBOX" -c agent -- chmod 644 /sandbox/.openclaw/openclaw.json
$ docker exec "$DOCKER_CTR" kubectl exec -n openshell "$SANDBOX" -c agent -- chmod 644 /sandbox/.openclaw/.config-hash
$ cat /tmp/openclaw.updated.json | docker exec -i "$DOCKER_CTR" kubectl exec -i -n openshell "$SANDBOX" -c agent -- sh -c 'cat > /sandbox/.openclaw/openclaw.json'
$ docker exec "$DOCKER_CTR" kubectl exec -n openshell "$SANDBOX" -c agent -- /bin/bash -c "cd /sandbox/.openclaw && sha256sum openclaw.json > .config-hash"
$ docker exec "$DOCKER_CTR" kubectl exec -n openshell "$SANDBOX" -c agent -- chmod 444 /sandbox/.openclaw/openclaw.json
$ docker exec "$DOCKER_CTR" kubectl exec -n openshell "$SANDBOX" -c agent -- chmod 444 /sandbox/.openclaw/.config-hash
$ docker exec "$DOCKER_CTR" chmod 644 /sandbox/.openclaw/openclaw.json
$ docker exec "$DOCKER_CTR" chmod 644 /sandbox/.openclaw/.config-hash
$ cat /tmp/openclaw.updated.json | docker exec -i "$DOCKER_CTR" sh -c 'cat > /sandbox/.openclaw/openclaw.json'
$ docker exec "$DOCKER_CTR" /bin/bash -c "cd /sandbox/.openclaw && sha256sum openclaw.json > .config-hash"
# Optional: Lock the config to be root-owned and read-only to enforce integrity at startup
$ docker exec --user root "$DOCKER_CTR" chown root:root /sandbox/.openclaw/openclaw.json
$ docker exec --user root "$DOCKER_CTR" chmod 444 /sandbox/.openclaw/openclaw.json
$ docker exec --user root "$DOCKER_CTR" chown root:root /sandbox/.openclaw/.config-hash
$ docker exec --user root "$DOCKER_CTR" chmod 444 /sandbox/.openclaw/.config-hash
# Rollback: If you need to edit the config again, restore write permissions
# $ docker exec --user root "$DOCKER_CTR" sh -c 'chown sandbox:sandbox /sandbox/.openclaw/openclaw.json /sandbox/.openclaw/.config-hash && chmod 644 /sandbox/.openclaw/openclaw.json /sandbox/.openclaw/.config-hash'
```
Comment thread
coderabbitai[bot] marked this conversation as resolved.

Check `/tmp/gateway.log` after upload and confirm the gateway hot-reloaded the provider or `agents.list` change.
Expand All @@ -89,7 +95,7 @@ Use the same provider ID that appears in `models.providers`, such as `nvidia-omn
After uploading the auth profile, make sure the sub-agent directory is owned by the sandbox user:

```console
$ docker exec "$DOCKER_CTR" kubectl exec -n openshell "$SANDBOX" -c agent -- chown -R sandbox:sandbox /sandbox/.openclaw/agents/vision-operator
$ docker exec "$DOCKER_CTR" chown -R sandbox:sandbox /sandbox/.openclaw/agents/vision-operator
```

## Allow Auxiliary Provider Egress
Expand Down
5 changes: 3 additions & 2 deletions docs/monitoring/monitor-sandbox-activity.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,8 @@
title: "Monitor Sandbox Activity and Debug Issues"
sidebar-title: "Monitor Sandbox Activity"
description: "Inspect sandbox health, trace agent behavior, and diagnose problems."
description-agent: "Inspects sandbox health, traces agent behavior, and diagnoses problems. Use when monitoring a running sandbox, debugging agent issues, or checking sandbox logs."
description-agent: "Inspects sandbox health, traces agent behavior, and diagnoses problems.
Use when monitoring a running sandbox, debugging agent issues, or checking sandbox logs."
keywords: ["monitor nemoclaw sandbox", "debug nemoclaw agent issues"]
content:
type: "how_to"
Expand All @@ -20,7 +21,7 @@ Use the NemoClaw status, logs, and TUI tools together to inspect sandbox health,

## Check Sandbox Health

Run the status command to view the sandbox state, gateway health, and active inference configuration:
Run the status command to view the sandbox state, gateway health, and active inference configuration.

```console
$ nemoclaw <name> status
Expand Down
Loading
Loading