diff --git a/bin/config/onboard-notice.json b/bin/config/onboard-notice.json new file mode 100644 index 000000000..a8a894163 --- /dev/null +++ b/bin/config/onboard-notice.json @@ -0,0 +1,8 @@ +{ + "version": "2026-04-01", + "title": "Usage Notice", + "summary": "NemoClaw can provision local or cloud resources and retrieve external materials that may be governed by separate terms, conditions, and licenses.", + "details": "Review the full usage notice and disclaimer before continuing:", + "url": "https://docs.nvidia.com/nemoclaw/latest/reference/usage-notice.html", + "prompt": "Press Enter to continue onboarding: " +} diff --git a/bin/lib/onboard-notice.js b/bin/lib/onboard-notice.js new file mode 100644 index 000000000..839774c61 --- /dev/null +++ b/bin/lib/onboard-notice.js @@ -0,0 +1,155 @@ +// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +// SPDX-License-Identifier: Apache-2.0 + +const fs = require("fs"); +const os = require("os"); +const path = require("path"); + +const DEFAULT_NOTICE_CONFIG_PATH = path.join(__dirname, "..", "config", "onboard-notice.json"); + +function getOnboardNoticeStatePath() { + const home = process.env.HOME || os.homedir() || "/tmp"; + return ( + process.env.NEMOCLAW_ONBOARD_NOTICE_STATE || path.join(home, ".nemoclaw", "onboard-notice.json") + ); +} + +function getOnboardNoticeConfigPath() { + return process.env.NEMOCLAW_ONBOARD_NOTICE_CONFIG || DEFAULT_NOTICE_CONFIG_PATH; +} + +function validateNoticeConfig(config, sourcePath) { + const requiredFields = ["version", "title", "summary", "details", "url", "prompt"]; + if (!config || typeof config !== "object" || Array.isArray(config)) { + throw new Error(`Invalid onboard notice config: ${sourcePath}`); + } + for (const field of requiredFields) { + if (typeof config[field] !== "string" || config[field].trim().length === 0) { + throw new Error(`Invalid onboard notice config field '${field}': ${sourcePath}`); + } + } + return { + version: config.version.trim(), + title: config.title.trim(), + summary: config.summary.trim(), + details: config.details.trim(), + url: config.url.trim(), + prompt: config.prompt, + }; +} + +function loadOnboardNoticeConfig(configPath = getOnboardNoticeConfigPath()) { + const raw = fs.readFileSync(configPath, "utf-8"); + return validateNoticeConfig(JSON.parse(raw), configPath); +} + +function loadOnboardNoticeState(statePath = getOnboardNoticeStatePath()) { + try { + const raw = JSON.parse(fs.readFileSync(statePath, "utf-8")); + return { + lastSeenVersion: + typeof raw?.lastSeenVersion === "string" && raw.lastSeenVersion.length > 0 + ? raw.lastSeenVersion + : null, + lastSeenAt: + typeof raw?.lastSeenAt === "string" && raw.lastSeenAt.length > 0 ? raw.lastSeenAt : null, + }; + } catch { + return { lastSeenVersion: null, lastSeenAt: null }; + } +} + +function shouldShowOnboardNotice(config, state = loadOnboardNoticeState()) { + return !config || state.lastSeenVersion !== config.version; +} + +function saveOnboardNoticeState(version, statePath = getOnboardNoticeStatePath()) { + const dir = path.dirname(statePath); + const tmpPath = path.join( + dir, + `.onboard-notice.${process.pid}.${Date.now()}.${Math.random().toString(36).slice(2, 8)}.tmp`, + ); + fs.mkdirSync(dir, { recursive: true, mode: 0o700 }); + const payload = JSON.stringify( + { + lastSeenVersion: version, + lastSeenAt: new Date().toISOString(), + }, + null, + 2, + ); + try { + fs.writeFileSync(tmpPath, payload, { mode: 0o600 }); + fs.renameSync(tmpPath, statePath); + } catch (error) { + try { + fs.unlinkSync(tmpPath); + } catch { + // Best-effort cleanup; preserve the original write/rename error. + } + throw error; + } +} + +function renderOnboardNoticeLines(config) { + return [ + "", + ` ${config.title}`, + ` ${"─".repeat(config.title.length)}`, + ` ${config.summary}`, + ` ${config.details}`, + ` ${config.url}`, + ]; +} + +async function showOnboardNoticeIfNeeded(options = {}) { + const config = loadOnboardNoticeConfig(options.configPath); + const statePath = options.statePath || getOnboardNoticeStatePath(); + const state = loadOnboardNoticeState(statePath); + if (!shouldShowOnboardNotice(config, state)) { + return { shown: false, version: config.version }; + } + + const writeLine = + options.writeLine || + ((line) => { + process.stderr.write(`${line}\n`); + }); + + for (const line of renderOnboardNoticeLines(config)) { + writeLine(line); + } + + if (options.nonInteractive) { + writeLine(" [non-interactive] Continuing after logging the usage notice."); + } else { + const promptFn = options.promptFn; + if (typeof promptFn !== "function") { + throw new Error("Interactive onboard notice requires a prompt function."); + } + await promptFn(` ${config.prompt}`); + } + + try { + saveOnboardNoticeState(config.version, statePath); + } catch (error) { + writeLine( + ` Warning: could not persist usage notice state at ${statePath}: ${error?.message || String(error)}`, + ); + } + + return { shown: true, version: config.version }; +} + +module.exports = { + DEFAULT_NOTICE_CONFIG_PATH, + getOnboardNoticeConfigPath, + getOnboardNoticeStatePath, + loadOnboardNoticeConfig, + loadOnboardNoticeState, + renderOnboardNoticeLines, + saveOnboardNoticeState, + shouldShowOnboardNotice, + showOnboardNoticeIfNeeded, + validateNoticeConfig, +}; diff --git a/bin/lib/onboard.js b/bin/lib/onboard.js index 07666068b..5dfb80b01 100644 --- a/bin/lib/onboard.js +++ b/bin/lib/onboard.js @@ -46,6 +46,7 @@ const { } = require("./credentials"); const registry = require("./registry"); const nim = require("./nim"); +const { showOnboardNoticeIfNeeded } = require("./onboard-notice"); const onboardSession = require("./onboard-session"); const policies = require("./policies"); const { ensureUsageNoticeConsent } = require("./usage-notice"); @@ -4017,6 +4018,11 @@ async function onboard(opts = {}) { onboardSession.markStepComplete("preflight"); } + await showOnboardNoticeIfNeeded({ + nonInteractive: isNonInteractive(), + promptFn: prompt, + }); + const gatewayStatus = runCaptureOpenshell(["status"], { ignoreError: true }); const gatewayInfo = runCaptureOpenshell(["gateway", "info", "-g", GATEWAY_NAME], { ignoreError: true, diff --git a/docs/index.md b/docs/index.md index f9f613026..fe9cfd0c1 100644 --- a/docs/index.md +++ b/docs/index.md @@ -283,6 +283,7 @@ Architecture Commands Network Policies Troubleshooting +Usage Notice ``` ```{toctree} diff --git a/docs/reference/commands.md b/docs/reference/commands.md index c312c6991..7b4a5e4ea 100644 --- a/docs/reference/commands.md +++ b/docs/reference/commands.md @@ -103,6 +103,9 @@ Uppercase letters are automatically lowercased. Before creating the gateway, the wizard runs preflight checks. It verifies that Docker is reachable, warns on unsupported runtimes such as Podman, and prints host remediation guidance when prerequisites are missing. +On systems with cgroup v2 (Ubuntu 24.04, DGX Spark, WSL2), it verifies that Docker is configured with `"default-cgroupns-mode": "host"` and provides fix instructions if the setting is missing. +On first-run onboarding, NemoClaw also shows a usage notice before provisioning starts. +Set `NEMOCLAW_ONBOARD_NOTICE_CONFIG` to override the bundled JSON notice without changing the CLI code. ### `nemoclaw list` diff --git a/docs/reference/usage-notice.md b/docs/reference/usage-notice.md new file mode 100644 index 000000000..82fb5823c --- /dev/null +++ b/docs/reference/usage-notice.md @@ -0,0 +1,53 @@ +--- +title: + page: "NemoClaw Usage Notice" + nav: "Usage Notice" +description: "Usage notice and disclaimer shown during NemoClaw onboarding." +keywords: ["nemoclaw usage notice", "nemoclaw disclaimer", "nemoclaw terms"] +topics: ["generative_ai", "ai_agents"] +tags: ["openclaw", "openshell", "nemoclaw", "legal"] +content: + type: reference + difficulty: technical_beginner + audience: ["developer", "engineer"] +status: published +--- + + + +# NemoClaw Usage Notice + +NemoClaw shows this notice during first-run onboarding before it provisions a sandbox. +If the bundled notice version changes, NemoClaw shows the updated notice again on the next onboarding run. + +:::{warning} +Notice and Disclaimer + +This software automatically retrieves, accesses or interacts with external materials. +Those retrieved materials are not distributed with this software and are governed solely by separate terms, conditions and licenses. +You are solely responsible for finding, reviewing and complying with all applicable terms, conditions, and licenses, and for verifying the security, integrity and suitability of any retrieved materials for your specific use case. +This software is provided "AS IS", without warranty of any kind. +The author makes no representations or warranties regarding any retrieved materials, and assumes no liability for any losses, damages, liabilities or legal consequences from your use or inability to use this software or any retrieved materials. +Use this software and the retrieved materials at your own risk. +::: + +## Operator Override + +The bundled notice config lives in the CLI package. +To supply a different notice without changing JavaScript code, set `NEMOCLAW_ONBOARD_NOTICE_CONFIG` to a JSON file that contains: + +- `version` +- `title` +- `summary` +- `details` +- `url` +- `prompt` + +## Next Steps + +- Review the [`nemoclaw onboard` command reference](commands.md#nemoclaw-onboard) for the full onboarding flow and the `NEMOCLAW_ONBOARD_NOTICE_CONFIG` override. +- Follow the [Quickstart guide](../get-started/quickstart.md) for installation and first-run onboarding. +- Use the [Troubleshooting guide](troubleshooting.md) if onboarding or notice display fails on your host. diff --git a/test/onboard-notice.test.js b/test/onboard-notice.test.js new file mode 100644 index 000000000..c1c5c5db3 --- /dev/null +++ b/test/onboard-notice.test.js @@ -0,0 +1,169 @@ +// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +// SPDX-License-Identifier: Apache-2.0 + +import fs from "node:fs"; +import os from "node:os"; +import path from "node:path"; +import { describe, expect, it, vi } from "vitest"; + +import { + DEFAULT_NOTICE_CONFIG_PATH, + loadOnboardNoticeConfig, + loadOnboardNoticeState, + renderOnboardNoticeLines, + saveOnboardNoticeState, + shouldShowOnboardNotice, + showOnboardNoticeIfNeeded, +} from "../bin/lib/onboard-notice"; + +describe("onboard notice", () => { + it("loads the bundled notice config", () => { + const config = loadOnboardNoticeConfig(DEFAULT_NOTICE_CONFIG_PATH); + expect(config.version).toBeTruthy(); + expect(config.url).toBe("https://docs.nvidia.com/nemoclaw/latest/reference/usage-notice.html"); + expect(renderOnboardNoticeLines(config).join("\n")).toContain(config.summary); + }); + + it("records the last seen notice version", () => { + const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "nemoclaw-onboard-notice-state-")); + const statePath = path.join(tmpDir, "onboard-notice.json"); + + saveOnboardNoticeState("2026-04-01", statePath); + + expect(loadOnboardNoticeState(statePath)).toMatchObject({ + lastSeenVersion: "2026-04-01", + }); + }); + + it("cleans up the temp state file when the atomic rename fails", () => { + const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "nemoclaw-onboard-notice-rename-")); + const statePath = path.join(tmpDir, "onboard-notice.json"); + const renameError = new Error("rename failed"); + const renameSpy = vi.spyOn(fs, "renameSync").mockImplementation(() => { + throw renameError; + }); + + try { + expect(() => saveOnboardNoticeState("2026-04-01", statePath)).toThrow(renameError); + expect(fs.existsSync(statePath)).toBe(false); + expect(fs.readdirSync(tmpDir)).toEqual([]); + } finally { + renameSpy.mockRestore(); + } + }); + + it("shows the notice once in non-interactive mode and writes to stderr", async () => { + const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "nemoclaw-onboard-notice-show-")); + const statePath = path.join(tmpDir, "onboard-notice.json"); + const lines = []; + + const first = await showOnboardNoticeIfNeeded({ + nonInteractive: true, + statePath, + writeLine: (line) => lines.push(line), + }); + const second = await showOnboardNoticeIfNeeded({ + nonInteractive: true, + statePath, + writeLine: (line) => lines.push(line), + }); + + expect(first).toMatchObject({ shown: true }); + expect(second).toMatchObject({ shown: false }); + expect(lines.join("\n")).toContain("Usage Notice"); + expect(lines.join("\n")).toContain( + "[non-interactive] Continuing after logging the usage notice.", + ); + }); + + it("warns and continues when notice state cannot be persisted", async () => { + const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "nemoclaw-onboard-notice-unwritable-")); + const stateParent = path.join(tmpDir, "state"); + const statePath = path.join(stateParent, "onboard-notice.json"); + const lines = []; + + fs.writeFileSync(stateParent, "not a directory"); + + const result = await showOnboardNoticeIfNeeded({ + nonInteractive: true, + statePath, + writeLine: (line) => lines.push(line), + }); + + expect(result).toMatchObject({ shown: true }); + expect(lines.join("\n")).toContain("Warning: could not persist usage notice state"); + expect(lines.join("\n")).toContain(statePath); + }); + + it("re-shows the notice when the configured version changes", async () => { + const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "nemoclaw-onboard-notice-version-")); + const statePath = path.join(tmpDir, "onboard-notice.json"); + const configPath = path.join(tmpDir, "notice.json"); + + fs.writeFileSync( + configPath, + JSON.stringify({ + version: "2026-04-01", + title: "Usage Notice", + summary: "First version.", + details: "Review before continuing:", + url: "https://example.com/notice", + prompt: "Continue: ", + }), + ); + await showOnboardNoticeIfNeeded({ + nonInteractive: true, + statePath, + configPath, + writeLine: () => {}, + }); + + fs.writeFileSync( + configPath, + JSON.stringify({ + version: "2026-05-01", + title: "Usage Notice", + summary: "Updated version.", + details: "Review before continuing:", + url: "https://example.com/notice", + prompt: "Continue: ", + }), + ); + + const shown = await showOnboardNoticeIfNeeded({ + nonInteractive: true, + statePath, + configPath, + writeLine: () => {}, + }); + + expect(shown).toMatchObject({ shown: true, version: "2026-05-01" }); + }); + + it("blocks in interactive mode until the user acknowledges the notice", async () => { + const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "nemoclaw-onboard-notice-ack-")); + const statePath = path.join(tmpDir, "onboard-notice.json"); + const prompts = []; + + const result = await showOnboardNoticeIfNeeded({ + nonInteractive: false, + statePath, + promptFn: async (question) => { + prompts.push(question); + return ""; + }, + writeLine: () => {}, + }); + + expect(result).toMatchObject({ shown: true }); + expect(prompts).toEqual([" Press Enter to continue onboarding: "]); + }); + + it("tracks whether the current notice version still needs to be shown", () => { + const config = loadOnboardNoticeConfig(DEFAULT_NOTICE_CONFIG_PATH); + expect(shouldShowOnboardNotice(config, { lastSeenVersion: null, lastSeenAt: null })).toBe(true); + expect( + shouldShowOnboardNotice(config, { lastSeenVersion: config.version, lastSeenAt: null }), + ).toBe(false); + }); +}); diff --git a/test/onboard.test.js b/test/onboard.test.js index 5633baa99..94d18ce44 100644 --- a/test/onboard.test.js +++ b/test/onboard.test.js @@ -3037,4 +3037,15 @@ const { setupMessagingChannels } = require(${onboardPath}); assert.match(fnBody, /isNonInteractive\(\)/); assert.match(fnBody, /process\.exit\(1\)/); }); + + it("shows the onboarding notice after preflight completes", () => { + const source = fs.readFileSync( + path.join(import.meta.dirname, "..", "bin", "lib", "onboard.js"), + "utf-8", + ); + assert.match( + source, + /onboardSession\.markStepComplete\("preflight"\);[\s\S]*?showOnboardNoticeIfNeeded\(\{/, + ); + }); });