docs(reference): add env-var index + document gateway lifecycle tunables (#3059)#3652
Conversation
|
Note Reviews pausedIt looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
📝 WalkthroughWalkthroughThis PR expands CLI environment variables documentation by adding a quick-reference index table, documenting new VM/DNS and GPU-related toggles, and introducing a Gateway Lifecycle Tunables section with timing and polling controls, synchronized across two reference files. ChangesEnvironment Variables Reference Documentation Expansion
Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes Suggested reviewers
Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
🧹 Nitpick comments (6)
docs/reference/commands.md (3)
1096-1097: ⚡ Quick winUse more formal technical language.
Line 1096: "discover the right knob" is informal. Consider "find the appropriate variable" or "locate the relevant configuration variable."
Line 1097: "jump to the subsection below" uses an imperative without addressing the reader. Reframe as "Review the subsection below for..." or "See the subsection below for..."
As per coding guidelines: documentation should maintain a professional tone and use second person when addressing the reader.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/reference/commands.md` around lines 1096 - 1097, The phrasing in the introduction to the environment variable table uses informal language ("discover the right knob", "jump to the subsection below"); update the sentences that start with "Every documented `NEMOCLAW_*` environment variable, grouped by category." to use formal technical language and second-person where appropriate—change "discover the right knob" to "find the appropriate variable" or "locate the relevant configuration variable" and rephrase "jump to the subsection below" to "See the subsection below for" or "Review the subsection below for" so the text reads professionally and instructively.
1197-1197: ⚡ Quick winConvert passive voice to active voice.
The phrase "the override exists for cross-platform reproduction" uses passive construction. Consider active voice: "Use this override for cross-platform reproduction" or "This override enables cross-platform reproduction."
As per coding guidelines: active voice is required in documentation.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/reference/commands.md` at line 1197, Update the documentation line describing the NEMOCLAW_FORCE_VM_DNS_MONKEYPATCH environment variable to use active voice: replace the passive clause "the override exists for cross-platform reproduction" with an active construction such as "Use this override for cross-platform reproduction" or "This override enables cross-platform reproduction" so the full description for `NEMOCLAW_FORCE_VM_DNS_MONKEYPATCH` reads clearly and follows the active-voice guideline.
1234-1236: ⚡ Quick winConvert passive voice to active voice.
Line 1235: "Defaults are sized for typical local development" uses passive construction. Consider active voice: "These defaults target typical local development" or "The default values support typical local development."
As per coding guidelines: active voice is required in documentation.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/reference/commands.md` around lines 1234 - 1236, Rewrite the passive sentence "Defaults are sized for typical local development" to active voice; replace it with a phrasing such as "These defaults target typical local development" or "The default values support typical local development" in the docs section that currently reads "These variables tune the polling and timeout budgets used by gateway-recovery and health-check paths. Defaults are sized for typical local development; raise them on slow links, large image pulls, or remote-deployed hosts where round-trip latency to the gateway is high." Ensure the revised sentence reads smoothly with the surrounding guidance about raising values for slow links, large image pulls, or high-latency remote hosts..agents/skills/nemoclaw-user-reference/references/commands.md (3)
1160-1160: ⚡ Quick winConvert passive voice to active voice.
The phrase "the override exists for cross-platform reproduction" uses passive construction. Consider active voice: "Use this override for cross-platform reproduction" or "This override enables cross-platform reproduction."
As per coding guidelines: active voice is required in documentation.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In @.agents/skills/nemoclaw-user-reference/references/commands.md at line 1160, Update the table row for the environment variable NEMOCLAW_FORCE_VM_DNS_MONKEYPATCH to use active voice: replace the passive clause "the override exists for cross-platform reproduction" with an active phrasing such as "Use this override for cross-platform reproduction" or "This override enables cross-platform reproduction" so the description reads actively while preserving the rest of the entry.
1060-1061: ⚡ Quick winUse more formal technical language.
Line 1060: "discover the right knob" is informal. Consider "find the appropriate variable" or "locate the relevant configuration variable."
Line 1061: "jump to the subsection below" uses an imperative without addressing the reader. Reframe as "Review the subsection below for..." or "See the subsection below for..."
As per coding guidelines: documentation should maintain a professional tone and use second person when addressing the reader.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In @.agents/skills/nemoclaw-user-reference/references/commands.md around lines 1060 - 1061, Update the sentence that follows the "Every documented `NEMOCLAW_*` environment variable, grouped by category." header to use formal technical language: replace "discover the right knob" with "find the appropriate variable" (or "locate the relevant configuration variable") and change the imperative "jump to the subsection below" to a neutral phrasing such as "see the subsection below for" or "review the subsection below for" so the text reads professionally and uses second-person where addressing the reader; ensure the sentence still references the table and the subsections for defaults, format, and effect and keep mention of `NEMOCLAW_*` intact.
1197-1199: ⚡ Quick winConvert passive voice to active voice.
Line 1198: "Defaults are sized for typical local development" uses passive construction. Consider active voice: "These defaults target typical local development" or "The default values support typical local development."
As per coding guidelines: active voice is required in documentation.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In @.agents/skills/nemoclaw-user-reference/references/commands.md around lines 1197 - 1199, The sentence "Defaults are sized for typical local development" uses passive voice; edit the documentation in commands.md near the paragraph about polling and timeout budgets (the sentence following "These variables tune the polling and timeout budgets used by gateway-recovery and health-check paths.") to use active voice instead—e.g., replace it with "These default values support typical local development" or "These defaults target typical local development" so the paragraph reads actively.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Nitpick comments:
In @.agents/skills/nemoclaw-user-reference/references/commands.md:
- Line 1160: Update the table row for the environment variable
NEMOCLAW_FORCE_VM_DNS_MONKEYPATCH to use active voice: replace the passive
clause "the override exists for cross-platform reproduction" with an active
phrasing such as "Use this override for cross-platform reproduction" or "This
override enables cross-platform reproduction" so the description reads actively
while preserving the rest of the entry.
- Around line 1060-1061: Update the sentence that follows the "Every documented
`NEMOCLAW_*` environment variable, grouped by category." header to use formal
technical language: replace "discover the right knob" with "find the appropriate
variable" (or "locate the relevant configuration variable") and change the
imperative "jump to the subsection below" to a neutral phrasing such as "see the
subsection below for" or "review the subsection below for" so the text reads
professionally and uses second-person where addressing the reader; ensure the
sentence still references the table and the subsections for defaults, format,
and effect and keep mention of `NEMOCLAW_*` intact.
- Around line 1197-1199: The sentence "Defaults are sized for typical local
development" uses passive voice; edit the documentation in commands.md near the
paragraph about polling and timeout budgets (the sentence following "These
variables tune the polling and timeout budgets used by gateway-recovery and
health-check paths.") to use active voice instead—e.g., replace it with "These
default values support typical local development" or "These defaults target
typical local development" so the paragraph reads actively.
In `@docs/reference/commands.md`:
- Around line 1096-1097: The phrasing in the introduction to the environment
variable table uses informal language ("discover the right knob", "jump to the
subsection below"); update the sentences that start with "Every documented
`NEMOCLAW_*` environment variable, grouped by category." to use formal technical
language and second-person where appropriate—change "discover the right knob" to
"find the appropriate variable" or "locate the relevant configuration variable"
and rephrase "jump to the subsection below" to "See the subsection below for" or
"Review the subsection below for" so the text reads professionally and
instructively.
- Line 1197: Update the documentation line describing the
NEMOCLAW_FORCE_VM_DNS_MONKEYPATCH environment variable to use active voice:
replace the passive clause "the override exists for cross-platform reproduction"
with an active construction such as "Use this override for cross-platform
reproduction" or "This override enables cross-platform reproduction" so the full
description for `NEMOCLAW_FORCE_VM_DNS_MONKEYPATCH` reads clearly and follows
the active-voice guideline.
- Around line 1234-1236: Rewrite the passive sentence "Defaults are sized for
typical local development" to active voice; replace it with a phrasing such as
"These defaults target typical local development" or "The default values support
typical local development" in the docs section that currently reads "These
variables tune the polling and timeout budgets used by gateway-recovery and
health-check paths. Defaults are sized for typical local development; raise them
on slow links, large image pulls, or remote-deployed hosts where round-trip
latency to the gateway is high." Ensure the revised sentence reads smoothly with
the surrounding guidance about raising values for slow links, large image pulls,
or high-latency remote hosts.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Enterprise
Run ID: d32719b5-6c8b-4ade-89c9-313985e9c33c
📒 Files selected for processing (2)
.agents/skills/nemoclaw-user-reference/references/commands.mddocs/reference/commands.md
latenighthackathon
force-pushed
the
docs/env-vars-comprehensive-reference
branch
from
9ef3258 to
77c2f25
Compare
latenighthackathon
force-pushed
the
docs/env-vars-comprehensive-reference
branch
from
482fc91 to
34d6b4c
Compare
|
✨ Thanks for submitting this detailed PR to address the documentation gap for environment variables and gateway lifecycle tunables. This change aims to improve the discoverability of NEMOCLAW_* variables and provide a consolidated table for operators to reference. Related open issues: |
|
Docs migration heads-up: #3837 has merged the Fern MDX migration cleanup. Legacy documentation source pages under CI now validates the MDX sources directly, so deleted legacy Markdown pages should stay deleted. |
latenighthackathon
force-pushed
the
docs/env-vars-comprehensive-reference
branch
from
34d6b4c to
f2ffee4
Compare
There was a problem hiding this comment.
🧹 Nitpick comments (4)
docs/reference/commands.mdx (4)
1200-1200: ⚡ Quick winReplace sentence fragment with complete sentence.
"Installer-only." is a fragment.
Consider: "For installer use only." or "Installer use only." or combine with the following sentence: "Installer use only; skips the DGX Spark..."
As per coding guidelines: Every sentence must end with a period (and be a complete sentence).
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/reference/commands.mdx` at line 1200, The table cell contains the fragment "Installer-only."; update that fragment to a complete sentence such as "Installer use only." or merge with the next clause into a single sentence like "Installer use only; skips the DGX Spark, DGX Station, and Windows WSL express install prompt and continues with the normal interactive onboarding flow." Edit the cell referencing `NEMOCLAW_NO_EXPRESS` so the entry ends with a proper period and is a complete sentence.
1112-1112: ⚡ Quick winComplete the sentence.
This line is a noun phrase without a main verb.
Suggested rewrites:
- "This table lists every documented
NEMOCLAW_*environment variable, grouped by category."- "The following table lists every documented
NEMOCLAW_*environment variable, grouped by category."As per coding guidelines: Every sentence must end with a period (and be a complete sentence).
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/reference/commands.mdx` at line 1112, The fragment "Every documented `NEMOCLAW_*` environment variable, grouped by category." is a noun phrase; replace it with a complete sentence such as "This table lists every documented `NEMOCLAW_*` environment variable, grouped by category." or "The following table lists every documented `NEMOCLAW_*` environment variable, grouped by category." and ensure the sentence ends with a period in the docs/reference/commands.mdx content.
648-648: ⚡ Quick winUse active voice.
The phrase "is the supported path" is passive.
As per coding guidelines, active voice is required in documentation.Consider: "NemoClaw supports host-side removal because..." or "Use the host-side removal path because..."
As per coding guidelines: Active voice required. Flag passive constructions.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/reference/commands.mdx` at line 648, Replace the passive sentence "Host-side removal is the supported path because agent channel config is baked into the container image at build time (`/sandbox/.openclaw/openclaw.json` for OpenClaw and `/sandbox/.hermes/.env` for Hermes); agent-specific channel removals inside the sandbox would modify the running config but not persist changes across rebuilds." with an active-voice version (e.g., "NemoClaw supports host-side removal because the agent channel config is baked into the container image at build time (`/sandbox/.openclaw/openclaw.json` for OpenClaw and `/sandbox/.hermes/.env` for Hermes); removing channels inside the sandbox only changes the running config and does not persist across rebuilds.") while preserving the same file paths and technical details.
1190-1190: ⚡ Quick winBreak into multiple sentences for readability.
This single sentence exceeds 200 words and is difficult to parse.
While technically compliant with "one sentence per line," the cognitive load is high.Consider breaking into 3-4 shorter sentences:
- First sentence: what it does (pins the interpreter)
- Second: behavior when set (strict, no fallback)
- Third: what's rejected (relative paths)
- Fourth: behavior when unset (probing sequence)
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/reference/commands.mdx` at line 1190, Split the long single sentence describing NEMOCLAW_MODEL_ROUTER_PYTHON into 3–4 shorter sentences: 1) state its purpose (pins the host Python interpreter used to create the Model Router venv), 2) describe behavior when set (strict: NemoClaw probes only that absolute path and aborts with the failure reason; no fallback), 3) note what's rejected (relative command names such as python3.12 are rejected), and 4) describe behavior when unset (probe sequence python3.13 → python3.12 → python3.11 → python3.10 → python3, retain interpreters with versions in [3.10,3.14) whose ensurepip, pyexpat, ssl, and venv import cleanly, and try python -m venv in priority order until one succeeds). Use the environment variable name NEMOCLAW_MODEL_ROUTER_PYTHON and mention the Homebrew python@3.14 pyexpat dlopen mismatch example as a brief parenthetical.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Nitpick comments:
In `@docs/reference/commands.mdx`:
- Line 1200: The table cell contains the fragment "Installer-only."; update that
fragment to a complete sentence such as "Installer use only." or merge with the
next clause into a single sentence like "Installer use only; skips the DGX
Spark, DGX Station, and Windows WSL express install prompt and continues with
the normal interactive onboarding flow." Edit the cell referencing
`NEMOCLAW_NO_EXPRESS` so the entry ends with a proper period and is a complete
sentence.
- Line 1112: The fragment "Every documented `NEMOCLAW_*` environment variable,
grouped by category." is a noun phrase; replace it with a complete sentence such
as "This table lists every documented `NEMOCLAW_*` environment variable, grouped
by category." or "The following table lists every documented `NEMOCLAW_*`
environment variable, grouped by category." and ensure the sentence ends with a
period in the docs/reference/commands.mdx content.
- Line 648: Replace the passive sentence "Host-side removal is the supported
path because agent channel config is baked into the container image at build
time (`/sandbox/.openclaw/openclaw.json` for OpenClaw and
`/sandbox/.hermes/.env` for Hermes); agent-specific channel removals inside the
sandbox would modify the running config but not persist changes across
rebuilds." with an active-voice version (e.g., "NemoClaw supports host-side
removal because the agent channel config is baked into the container image at
build time (`/sandbox/.openclaw/openclaw.json` for OpenClaw and
`/sandbox/.hermes/.env` for Hermes); removing channels inside the sandbox only
changes the running config and does not persist across rebuilds.") while
preserving the same file paths and technical details.
- Line 1190: Split the long single sentence describing
NEMOCLAW_MODEL_ROUTER_PYTHON into 3–4 shorter sentences: 1) state its purpose
(pins the host Python interpreter used to create the Model Router venv), 2)
describe behavior when set (strict: NemoClaw probes only that absolute path and
aborts with the failure reason; no fallback), 3) note what's rejected (relative
command names such as python3.12 are rejected), and 4) describe behavior when
unset (probe sequence python3.13 → python3.12 → python3.11 → python3.10 →
python3, retain interpreters with versions in [3.10,3.14) whose ensurepip,
pyexpat, ssl, and venv import cleanly, and try python -m venv in priority order
until one succeeds). Use the environment variable name
NEMOCLAW_MODEL_ROUTER_PYTHON and mention the Homebrew python@3.14 pyexpat dlopen
mismatch example as a brief parenthetical.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Enterprise
Run ID: 9f94310b-4053-4c7e-a565-16cdc1fdd6bf
📒 Files selected for processing (2)
.agents/skills/nemoclaw-user-reference/references/commands.mddocs/reference/commands.mdx
✅ Files skipped from review due to trivial changes (1)
- .agents/skills/nemoclaw-user-reference/references/commands.md
…les (NVIDIA#3059) Closes NVIDIA#3059. `NEMOCLAW_*` environment variables are referenced across the docs portal in seven subsections of `docs/reference/commands.md` plus the credential-storage page, but the reference page has no single entry point operators can scan to discover the right knob. The reporter called this out as "scattered" and asked for a first-class consolidated table. Add an "At a Glance" index table at the top of the Environment Variables section that lists every documented `NEMOCLAW_*` variable grouped by category, with anchor links to the existing detailed subsections. The index is a discovery layer; per-variable defaults, formats, and effects remain in the per-section tables where they live today. Fill the largest documentation gap: gateway and health-poll tunables that production operators actually reach for on slow links and remote-deployed hosts but that were undocumented. Adds a new "Gateway Lifecycle Tunables" subsection covering: - `NEMOCLAW_GATEWAY_START_TIMEOUT` (default 600s) - `NEMOCLAW_GATEWAY_RECOVERY_WAIT_SECONDS` (default 30s) - `NEMOCLAW_GATEWAY_RECOVERY_POLL_INTERVAL_SECONDS` (default 3s) - `NEMOCLAW_HEALTH_POLL_COUNT` (default 12; 30 on arm64) - `NEMOCLAW_HEALTH_POLL_INTERVAL` (default 5s; 10s on arm64) - `NEMOCLAW_LOGS_PROBE_TIMEOUT_MS` (default 5000) - `NEMOCLAW_DOCKER_GPU_SUPERVISOR_RECONNECT_TIMEOUT` (default 900s) Extends "Onboarding Behavior Flags" with four onboarding toggles that were previously undocumented but are valid user-facing escape hatches: - `NEMOCLAW_DISABLE_VM_DNS_MONKEYPATCH` - `NEMOCLAW_FORCE_VM_DNS_MONKEYPATCH` - `NEMOCLAW_DARWIN_VM_COMPAT` (build-time Dockerfile ARG) - `NEMOCLAW_DOCKER_GPU_PATCH_NETWORK` Internal-only sentinels (`NEMOCLAW_DISABLE_AUTO_DISPATCH`, `NEMOCLAW_DISABLE_GATEWAY_DRIFT_PREFLIGHT`, `NEMOCLAW_RESTORE_LATEST_BACKUP_ON_RECREATE`, `NEMOCLAW_INVOKED_AS`, `NEMOCLAW_TEST_NO_SLEEP`, etc.) are intentionally left in `ci/env-var-doc-allowlist.json` with their existing internal-use reasons rather than promoted to user docs. Both `docs/reference/commands.md` and the `.agents/skills/nemoclaw-user-reference/references/commands.md` mirror are updated in lockstep. Verification: - `npx tsx scripts/check-env-var-docs.ts` passes (no doc-drift) - `markdownlint-cli2` passes on both files - `Verify docs-to-skills output` passes (mirror in sync) - Skill YAML + gitleaks + repository checks pass Signed-off-by: latenighthackathon <latenighthackathon@users.noreply.github.com>
latenighthackathon
force-pushed
the
docs/env-vars-comprehensive-reference
branch
from
69f0ca3 to
4928911
Compare
3 participants
Summary
Closes #3059.
NEMOCLAW_*environment variables are referenced across the docs portal in seven subsections ofdocs/reference/commands.mdxplus the credential-storage page, but the reference page had no single entry point for operators to scan and discover the right knob. The reporter (@oparoz) called this out as "scattered" and asked for a first-class consolidated table.Two changes
Add an "At a Glance" index table at the top of the Environment Variables section. Lists every documented
NEMOCLAW_*variable grouped by category, with anchor links to the existing detailed subsections. The index is a discovery layer; per-variable defaults, formats, and effects remain in the per-section tables where they live today.Fill the largest gap: gateway and health-poll tunables that production operators reach for on slow links and remote-deployed hosts but were undocumented. Adds a new "Gateway Lifecycle Tunables" subsection covering seven variables, plus four onboarding toggles under the existing "Onboarding Behavior Flags" section.
Newly documented
Gateway Lifecycle Tunables (new subsection)
NEMOCLAW_GATEWAY_START_TIMEOUTNEMOCLAW_GATEWAY_RECOVERY_WAIT_SECONDSNEMOCLAW_GATEWAY_RECOVERY_POLL_INTERVAL_SECONDSNEMOCLAW_HEALTH_POLL_COUNTNEMOCLAW_HEALTH_POLL_INTERVALNEMOCLAW_LOGS_PROBE_TIMEOUT_MSNEMOCLAW_DOCKER_GPU_SUPERVISOR_RECONNECT_TIMEOUTOnboarding Behavior Flags (additions)
NEMOCLAW_DISABLE_VM_DNS_MONKEYPATCHNEMOCLAW_FORCE_VM_DNS_MONKEYPATCHNEMOCLAW_DARWIN_VM_COMPATNEMOCLAW_DOCKER_GPU_PATCH_NETWORKAll defaults verified against the corresponding
process.env.*reads insrc/.Files
docs/reference/commands.mdx(At a Glance index + new Gateway Lifecycle Tunables subsection + Onboarding Behavior Flags additions).agents/skills/nemoclaw-user-reference/references/commands.md(auto-generated mirror)Test plan
prek runcleanprocess.env.NEMOCLAW_*reads insrc/Signed-off-by: latenighthackathon latenighthackathon@users.noreply.github.com