docs: catch up documentation for v0.0.18 changes by miyoungc · Pull Request #2033 · NVIDIA/NemoClaw

miyoungc · 2026-04-17T19:20:26Z

Summary

Refresh user-facing documentation against the 34 commits merged between
v0.0.17 and v0.0.18, bump the docs version switcher to v0.0.18, and fix a
sphinx-autobuild infinite-rebuild loop triggered by docs/conf.py.

Changes

Ollama authenticated reverse proxy (fix(security): add authenticated reverse proxy for local Ollama #1922): Replace the
0.0.0.0:11434 guidance in docs/inference/use-local-inference.md with
the new token-gated proxy on 127.0.0.1:11435, including persisted token,
health-check exemption, and sandbox provider wiring. Replace the matching
troubleshooting entry in docs/reference/troubleshooting.md.
Compatible-endpoint default API path (fix(onboard): force chat completions for compatible-endpoint providers #1984): Document that the
compatible-endpoint provider now defaults to /v1/chat/completions and
update NEMOCLAW_PREFERRED_API to describe openai-responses as the
opt-in instead of openai-completions. Updates in
use-local-inference.md, switch-inference-providers.md, and
troubleshooting.md.
nemoclaw upgrade-sandboxes command (fix(upgrade): pin base image via pull-then-inspect and rebuild stale sandboxes #1943): Add a new reference
entry in docs/reference/commands.md covering --check, --auto, and
--yes flags.
Messaging token rotation auto-rebuild (fix(onboard): propagate rotated messaging credentials to sandbox L7 proxy #1967, [brev]Telegram bridge: multiple sandboxes with same bot token cause 409 polling conflict — all bridges fail silently #1953): Note the
automatic rebuild behavior and cross-sandbox overlap warning in
docs/deployment/set-up-telegram-bridge.md, commands.md, and
troubleshooting.md.
Other troubleshooting additions:
- localhost → 127.0.0.1 IPv6 note (fix(onboard): use 127.0.0.1 instead of localhost for local inference detection #1978)
- Orphan SSH port-forward cleanup on re-onboard ([All platforms] Re-onboard does not clean up orphaned SSH port-forward from previous session #1950)
- Orphan openshell process cleanup in nemoclaw uninstall (nemoclaw uninstall does not clear all the openshell process #1940)
- Non-zero exit on tar failure in nemoclaw debug --output (fix(cli): detect tar failure in debug --output and set non-zero exit code #1770)
Skip list: Extend docs/.docs-skip to exclude the experimental
sandbox-mgmt shields and config commands feature (feat(sandbox-mgmt): experimental shields and config commands #1976), which was
explicitly merged as not-yet-documented.
Build stability: docs/conf.py now writes docs/project.json only
when contents change, so make docs-live / sphinx-autobuild no longer
detects its own generated file as a source change and enters an infinite
rebuild loop.
Version switcher: Bump docs/versions1.json and docs/project.json
preferred entry to v0.0.18 so this refresh renders under the new version.
Agent skills: Regenerate nemoclaw-user-* skills from docs/ with
scripts/docs-to-skills.py.

Type of Change

Code change (feature, bug fix, or refactor)
Code change with doc updates
Doc only (prose changes, no code sample modifications)
Doc only (includes code sample changes)

Verification

npx prek run --all-files passes (ran via pre-commit hook on staged files)
npm test passes
Tests added or updated for new or changed behavior
No secrets, API keys, or credentials committed
Docs updated for user-facing behavior changes
make docs builds without warnings (doc changes only)
Doc pages follow the style guide (doc changes only)
New doc pages include SPDX header and frontmatter (new pages only)

AI Disclosure

AI-assisted — tool: Cursor

Signed-off-by: Miyoung Choi miyoungc@nvidia.com

Made with Cursor

Summary by CodeRabbit

Release Notes

New Features
- Added nemoclaw upgrade-sandboxes command to rebuild sandboxes when base-image digests change.
- Introduced authenticated reverse proxy for local Ollama inference with token-based access control.
- Automatic sandbox backup, recreation, and restore when messaging credentials are updated.
- Cross-sandbox messaging token overlap detection with status warnings.
Improvements
- Compatible-endpoint provider now defaults to /v1/chat/completions API path.
- Enhanced troubleshooting documentation with new diagnostics sections.
Documentation
- Updated onboarding and configuration guides.
- Expanded version documentation to 0.0.18.

Refresh user-facing docs against the 34 commits merged between v0.0.17 and v0.0.18. Highlights: - Replace the Ollama 0.0.0.0 binding guidance with the new authenticated reverse proxy on 127.0.0.1:11435 (#1922). - Document the compatible-endpoint provider defaulting to /v1/chat/completions and the NEMOCLAW_PREFERRED_API=openai-responses opt-in (#1984). - Add the new nemoclaw upgrade-sandboxes command with --check, --auto, and --yes flags (#1943). - Note the cross-sandbox messaging overlap warning and 409 detection in nemoclaw <name> status (#1953). - Document the messaging-token rotation auto-rebuild flow (#1967). - Cover new troubleshooting entries for the Ollama auth proxy, IPv6 localhost resolution, orphan SSH port-forward cleanup on re-onboard, and rotated messaging credentials (#1978, #1950). - Note tar failure exit code for nemoclaw debug --output (#1770) and the orphaned openshell process cleanup in nemoclaw uninstall (#1940). Also: - Extend docs/.docs-skip to exclude the experimental sandbox-mgmt shields and config commands (#1976). - Fix a sphinx-autobuild infinite rebuild loop in docs/conf.py by writing docs/project.json only when its contents change. - Bump the docs version switcher preferred entry to 0.0.18. - Regenerate nemoclaw-user-* agent skills from docs/. Signed-off-by: Miyoung Choi <miyoungc@nvidia.com> Made-with: Cursor

coderabbitai · 2026-04-17T19:20:42Z

📝 Walkthrough

Walkthrough

This pull request updates documentation and configuration across multiple files to reflect changes in NemoClaw's API selection logic, Ollama proxy authentication setup, messaging token management, and introduces a new sandbox upgrade command. Version bumped from 0.0.17 to 0.0.18.

Changes

Cohort / File(s)	Summary
Ollama Local Inference `docs/inference/use-local-inference.md`, `.agents/skills/nemoclaw-user-configure-inference/SKILL.md`	Replaced direct Ollama binding (`0.0.0.0:11434`) with authenticated reverse proxy on port `11435`. Ollama now binds to `127.0.0.1:11434` and proxy validates Bearer tokens before forwarding, with token stored in `~/.nemoclaw/ollama-proxy-token`. Updated API path selection to default `/v1/chat/completions` with optional `/v1/responses` via `NEMOCLAW_PREFERRED_API=openai-responses`.
Compatible Endpoint API Selection `docs/inference/switch-inference-providers.md`, `.agents/skills/nemoclaw-user-configure-inference/SKILL.md`	Changed default API endpoint selection from favoring `/v1/responses` to defaulting `/v1/chat/completions` without environment variable. Users can opt into `/v1/responses` by setting `NEMOCLAW_PREFERRED_API=openai-responses` before onboarding.
Messaging Token Management `docs/deployment/set-up-telegram-bridge.md`, `.agents/skills/nemoclaw-user-deploy-remote/SKILL.md`	Added documentation on SHA-256 token hashing at sandbox creation, automatic backup-delete-recreate flow during `nemoclaw onboard --non-interactive` with changed credentials, and single-token-per-bot constraints enforced across Telegram/Discord/Slack with overlap detection via `nemoclaw status`.
New Sandbox Upgrade Command `docs/reference/commands.md`, `.agents/skills/nemoclaw-user-reference/references/commands.md`	Documented new `nemoclaw upgrade-sandboxes [--check] [--auto] [--yes]` command that rebuilds sandboxes whose base-image digest differs from `ghcr.io/nvidia/nemoclaw/sandbox-base:latest`, with preservation of workspace state via existing backup/restore flow.
Status, Debug, and Uninstall Updates `docs/reference/commands.md`, `.agents/skills/nemoclaw-user-reference/references/commands.md`	`nemoclaw <name> status` now reports cross-sandbox messaging-token overlaps and Telegram `409 Conflict` errors from gateway log; `nemoclaw debug` exits non-zero on `--output` write failures; `nemoclaw uninstall` now stops additional orphaned `openshell` process types beyond `openshell forward`.
Troubleshooting Additions `docs/reference/troubleshooting.md`, `.agents/skills/nemoclaw-user-reference/references/troubleshooting.md`	Added new sections for port `18789` preflight failures, messaging token rotation pickup issues, Ollama reverse proxy startup failures, and IPv6 health-check resolution issues. Updated compatible-endpoint runtime troubleshooting to reflect new default `/v1/chat/completions` behavior.
Documentation Generation & Versioning `docs/.docs-skip`, `docs/conf.py`, `docs/project.json`, `docs/versions1.json`	Expanded skip configuration to exclude experimental shield features and related commands; updated `docs/conf.py` to conditionally write `project.json` only on content changes to prevent rebuild loops; bumped version from 0.0.17 to 0.0.18 in project metadata and added corresponding version entry.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Poem

🐰 With proxies now guarding the Ollama gates,
And tokens that hash through their rotated fates,
New sandboxes upgrade, old endpoints align—
The docs are all polished, the features now shine!
Version point eighteen hops forward with pride,
Where clarity guides every user's ride. ✨

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'docs: catch up documentation for v0.0.18 changes' clearly and concisely summarizes the main purpose of the pull request: updating documentation for a new version release.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

Create stacked PR
Commit on current branch

🧪 Generate unit tests (beta)

Create PR with unit tests
Commit unit tests in branch docs/refresh-v0.0.18

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

coderabbitai

🧹 Nitpick comments (4)

docs/.docs-skip (1)
37-37: Narrow this skip pattern to avoid hiding stable doc updates.

"src/lib/sandbox-config.ts" will skip any commit touching that file, including future non-experimental changes. Prefer narrower commit-message/path substrings tied specifically to experimental config commands (e.g., rotate-token/show only).
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@docs/.docs-skip` at line 37, The skip entry currently matches the broad
literal "src/lib/sandbox-config.ts" which will hide all commits touching that
file; narrow it by replacing that exact pattern with a more specific substring
tied to experimental commands (e.g., include the command names or TODO markers
used in commits such as "rotate-token", "show" or a commit-tag like
"sandbox-config:rotate-token") so only commits that change the experimental
rotate-token/show code are skipped; update the skip line to reference those
unique identifiers (rotate-token, show, sandbox-config:rotate-token) instead of
the full filename.
docs/inference/switch-inference-providers.md (1)
91-94: Use one sentence per line in source for this paragraph.

These sentences are wrapped across multiple lines; docs style requires one full sentence per line for clean diffs.

As per coding guidelines: "One sentence per line in source (makes diffs readable). Flag paragraphs where multiple sentences appear on the same line."
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@docs/inference/switch-inference-providers.md` around lines 91 - 94, The
paragraph starting "For the compatible-endpoint provider, NemoClaw uses
`/v1/chat/completions` by default, so no env var is required 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:" should be reformatted so each
sentence is on its own source line; split the two sentences into separate lines
(one line with "For the compatible-endpoint provider..." and a second line with
"To opt in to `/v1/responses` ... set `NEMOCLAW_PREFERRED_API` before
onboarding:") to satisfy the "one sentence per line" docs style.
docs/inference/use-local-inference.md (1)
58-84: Apply one-sentence-per-line formatting in the newly added sections.

The new prose is wrapped mid-sentence across lines; keep each sentence on one line to match the docs source style.

As per coding guidelines: "One sentence per line in source (makes diffs readable). Flag paragraphs where multiple sentences appear on the same line."

Also applies to: 152-167
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@docs/inference/use-local-inference.md` around lines 58 - 84, The new
documentation block describing the NemoClaw/Ollama proxy contains multiple
sentences on the same lines (e.g., the paragraph starting "NemoClaw keeps Ollama
bound..." and the paragraph mentioning the token file
`~/.nemoclaw/ollama-proxy-token`, proxy ports `127.0.0.1:11434`/`0.0.0.0:11435`,
and the exempted endpoint `GET /api/tags`), which violates the
one-sentence-per-line docs rule; edit those paragraphs so each sentence is on
its own line (split any mid-sentence line wraps into full sentences per line)
and apply the same fix to the other mentioned block around the section that
references the sandbox provider and `OPENAI_API_KEY` so all sentences in these
newly added sections are one sentence per line.
docs/reference/troubleshooting.md (1)
247-273: Normalize these updated troubleshooting paragraphs to one sentence per line.

Several newly added sentences are hard-wrapped across multiple source lines; keep each sentence on a single line to match docs style.

As per coding guidelines: "One sentence per line in source (makes diffs readable). Flag paragraphs where multiple sentences appear on the same line."

Also applies to: 408-425, 569-597
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@docs/reference/troubleshooting.md` around lines 247 - 273, Normalize the
hard-wrapped troubleshooting paragraphs so each sentence occupies its own source
line: in the paragraph about orphaned SSH port-forward processes (the block
starting "After destroying a sandbox and gateway...") and the paragraph about
rotated messaging tokens (the block starting "Updated messaging token is not
picked up"), reflow lines so every sentence is on a single line; apply the same
one-sentence-per-line normalization to the other reported ranges (the blocks
referenced as 408-425 and 569-597) to match the docs style guide.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Nitpick comments:
In `@docs/.docs-skip`:
- Line 37: The skip entry currently matches the broad literal
"src/lib/sandbox-config.ts" which will hide all commits touching that file;
narrow it by replacing that exact pattern with a more specific substring tied to
experimental commands (e.g., include the command names or TODO markers used in
commits such as "rotate-token", "show" or a commit-tag like
"sandbox-config:rotate-token") so only commits that change the experimental
rotate-token/show code are skipped; update the skip line to reference those
unique identifiers (rotate-token, show, sandbox-config:rotate-token) instead of
the full filename.

In `@docs/inference/switch-inference-providers.md`:
- Around line 91-94: The paragraph starting "For the compatible-endpoint
provider, NemoClaw uses `/v1/chat/completions` by default, so no env var is
required 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:"
should be reformatted so each sentence is on its own source line; split the two
sentences into separate lines (one line with "For the compatible-endpoint
provider..." and a second line with "To opt in to `/v1/responses` ... set
`NEMOCLAW_PREFERRED_API` before onboarding:") to satisfy the "one sentence per
line" docs style.

In `@docs/inference/use-local-inference.md`:
- Around line 58-84: The new documentation block describing the NemoClaw/Ollama
proxy contains multiple sentences on the same lines (e.g., the paragraph
starting "NemoClaw keeps Ollama bound..." and the paragraph mentioning the token
file `~/.nemoclaw/ollama-proxy-token`, proxy ports
`127.0.0.1:11434`/`0.0.0.0:11435`, and the exempted endpoint `GET /api/tags`),
which violates the one-sentence-per-line docs rule; edit those paragraphs so
each sentence is on its own line (split any mid-sentence line wraps into full
sentences per line) and apply the same fix to the other mentioned block around
the section that references the sandbox provider and `OPENAI_API_KEY` so all
sentences in these newly added sections are one sentence per line.

In `@docs/reference/troubleshooting.md`:
- Around line 247-273: Normalize the hard-wrapped troubleshooting paragraphs so
each sentence occupies its own source line: in the paragraph about orphaned SSH
port-forward processes (the block starting "After destroying a sandbox and
gateway...") and the paragraph about rotated messaging tokens (the block
starting "Updated messaging token is not picked up"), reflow lines so every
sentence is on a single line; apply the same one-sentence-per-line normalization
to the other reported ranges (the blocks referenced as 408-425 and 569-597) to
match the docs style guide.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: b7219321-579b-4adf-9916-c2df34ed7b37

📥 Commits

Reviewing files that changed from the base of the PR and between 6643836 and 6128b82.

📒 Files selected for processing (13)

.agents/skills/nemoclaw-user-configure-inference/SKILL.md
.agents/skills/nemoclaw-user-deploy-remote/SKILL.md
.agents/skills/nemoclaw-user-reference/references/commands.md
.agents/skills/nemoclaw-user-reference/references/troubleshooting.md
docs/.docs-skip
docs/conf.py
docs/deployment/set-up-telegram-bridge.md
docs/inference/switch-inference-providers.md
docs/inference/use-local-inference.md
docs/project.json
docs/reference/commands.md
docs/reference/troubleshooting.md
docs/versions1.json

…d reasoning env vars (#2108) ## Summary Documents the `NEMOCLAW_CONTEXT_WINDOW`, `NEMOCLAW_MAX_TOKENS`, and `NEMOCLAW_REASONING` build-time environment variables that landed in #1956. These variables now propagate through the Dockerfile ARG chain into `openclaw.json`, but were not mentioned anywhere in the published docs. ## Changes - Add a "Tune Model Metadata" section to `docs/inference/switch-inference-providers.md` with a variable reference table, defaults, value constraints, an example, and the `nemoclaw onboard --resume --recreate-sandbox` flow for applying changes to existing sandboxes. - Regenerate `.agents/skills/nemoclaw-user-configure-inference/SKILL.md` from the updated source. - Sync `.agents/skills/nemoclaw-user-reference/references/troubleshooting.md` with the current `docs/reference/troubleshooting.md` (brings the autogen reference back in line with the `openclaw update` entry added in #2033). ## Type of Change - [ ] Code change (feature, bug fix, or refactor) - [ ] Code change with doc updates - [x] Doc only (prose changes, no code sample modifications) - [ ] Doc only (includes code sample changes) ## Verification - [x] `npx prek run --all-files` passes - [ ] `npm test` passes - [ ] Tests added or updated for new or changed behavior - [x] No secrets, API keys, or credentials committed - [x] Docs updated for user-facing behavior changes - [x] `make docs` builds without warnings (doc changes only) - [x] Doc pages follow the [style guide](https://github.com/NVIDIA/NemoClaw/blob/main/docs/CONTRIBUTING.md) (doc changes only) - [ ] New doc pages include SPDX header and frontmatter (new pages only) ## AI Disclosure - [x] AI-assisted — tool: Cursor --- Signed-off-by: Miyoung Choi <miyoungc@nvidia.com> Made with [Cursor](https://cursor.com)  ## Summary by CodeRabbit * **Documentation** * Added guide for tuning model metadata via build-time configuration variables. * Documented three new parameters for context window, max tokens, and reasoning, including accepted values, defaults, and that invalid values are ignored. * Clarified that changes apply during image build and require recreating a sandbox to take effect. * Simplified update-timeout troubleshooting with a single rebuild workflow. * Updated documentation versioning to include the new release.  --------- Signed-off-by: Miyoung Choi <miyoungc@nvidia.com>

miyoungc added the documentation label Apr 17, 2026

miyoungc self-assigned this Apr 17, 2026

miyoungc added the documentation label Apr 17, 2026

brandonpelfrey approved these changes Apr 17, 2026

View reviewed changes

coderabbitai Bot reviewed Apr 17, 2026

View reviewed changes

miyoungc merged commit 9222cae into main Apr 17, 2026
14 checks passed

miyoungc mentioned this pull request Apr 20, 2026

docs: refresh for v0.0.20 and document context window, max tokens, and reasoning env vars #2108

Merged

13 tasks

This was referenced May 12, 2026

docs: refresh 0.0.39 release prep #3375

Merged

docs: prepare v0.0.40 release docs #3427

Merged

miyoungc deleted the docs/refresh-v0.0.18 branch May 27, 2026 20:52

wscurran added area: docs Documentation, examples, guides, or docs build chore Build, CI, dependency, or tooling maintenance and removed documentation labels Jun 3, 2026

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: catch up documentation for v0.0.18 changes#2033

docs: catch up documentation for v0.0.18 changes#2033
miyoungc merged 1 commit into
mainfrom
docs/refresh-v0.0.18

miyoungc commented Apr 17, 2026 •

edited by coderabbitai Bot

Loading

Uh oh!

coderabbitai Bot commented Apr 17, 2026 •

edited

Loading

Walkthrough

Changes

Estimated code review effort

Poem

Uh oh!

coderabbitai Bot left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

miyoungc commented Apr 17, 2026 • edited by coderabbitai Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Changes

Type of Change

Verification

AI Disclosure

Summary by CodeRabbit

Release Notes

Uh oh!

coderabbitai Bot commented Apr 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Changes

Estimated code review effort

Poem

Uh oh!

coderabbitai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

miyoungc commented Apr 17, 2026 •

edited by coderabbitai Bot

Loading

coderabbitai Bot commented Apr 17, 2026 •

edited

Loading