From a181b63d8a2e6e79eb342fb25843de44900665f4 Mon Sep 17 00:00:00 2001 From: Miyoung Choi Date: Wed, 15 Apr 2026 09:32:57 -0700 Subject: [PATCH] docs: catch up documentation for v0.0.16 changes Document snapshot create/list/restore commands, policy-remove command, rebuild command with version staleness detection, backup-all command, live enforced policy in status output, and bump doc versions through 0.0.16. Co-Authored-By: Claude Opus 4.6 (1M context) --- .../nemoclaw-user-manage-policy/SKILL.md | 6 ++ .../references/commands.md | 86 ++++++++++++++++++- .../references/troubleshooting.md | 18 ++++ .../skills/nemoclaw-user-workspace/SKILL.md | 30 +++++-- .../customize-network-policy.md | 6 ++ docs/reference/commands.md | 79 ++++++++++++++++- docs/reference/troubleshooting.md | 18 ++++ docs/versions1.json | 4 + docs/workspace/backup-restore.md | 22 ++++- 9 files changed, 261 insertions(+), 8 deletions(-) diff --git a/.agents/skills/nemoclaw-user-manage-policy/SKILL.md b/.agents/skills/nemoclaw-user-manage-policy/SKILL.md index a1a497d6c35..bb39a63ef5b 100644 --- a/.agents/skills/nemoclaw-user-manage-policy/SKILL.md +++ b/.agents/skills/nemoclaw-user-manage-policy/SKILL.md @@ -86,6 +86,12 @@ If you only need one of the built-in presets, use `nemoclaw policy-add` i $ nemoclaw my-assistant policy-add ``` +To remove a previously applied preset, use `nemoclaw policy-remove`: + +```console +$ nemoclaw my-assistant policy-remove +``` + Use a manual YAML edit when you need to allow custom hosts that are not covered by a preset, such as an internal API or a weather service. Each entry in the `network` section defines an endpoint group with the following fields: diff --git a/.agents/skills/nemoclaw-user-reference/references/commands.md b/.agents/skills/nemoclaw-user-reference/references/commands.md index b8a379181f2..688f94a9280 100644 --- a/.agents/skills/nemoclaw-user-reference/references/commands.md +++ b/.agents/skills/nemoclaw-user-reference/references/commands.md @@ -50,6 +50,13 @@ $ nemoclaw onboard [--non-interactive] [--resume] [--recreate-sandbox] [--from < > **Warning:** For NemoClaw-managed environments, use `nemoclaw onboard` when you need to create or recreate the OpenShell gateway or sandbox. > Avoid `openshell self-update`, `npm update -g openshell`, `openshell gateway start --recreate`, or `openshell sandbox create` directly unless you intend to manage OpenShell separately and then rerun `nemoclaw onboard`. +The installer detects existing sandbox sessions before onboarding and prints a warning if any are found. +To make the installer abort instead of continuing, set `NEMOCLAW_SINGLE_SESSION=1`: + +```console +$ NEMOCLAW_SINGLE_SESSION=1 curl -fsSL https://www.nvidia.com/nemoclaw.sh | bash +``` + The wizard prompts for a provider first, then collects the provider credential if needed. Supported non-experimental choices include NVIDIA Endpoints, OpenAI, Anthropic, Google Gemini, and compatible OpenAI or Anthropic endpoints. Credentials are stored in `~/.nemoclaw/credentials.json`. For file permissions, plaintext storage behavior, and hardening guidance, see Credential Storage (see the `nemoclaw-user-configure-security` skill). @@ -163,6 +170,7 @@ $ nemoclaw deploy Connect to a sandbox by name. On a TTY, a one-shot hint prints before dropping into the sandbox shell, reminding you to run `openclaw tui` inside. Set `NEMOCLAW_NO_CONNECT_HINT=1` to suppress the hint in scripted workflows. +If the sandbox is running an outdated agent version, a non-blocking warning prints before connecting with a `nemoclaw rebuild` hint. ```console $ nemoclaw my-assistant connect @@ -174,6 +182,9 @@ Show sandbox status, health, and inference configuration. For local Ollama and local vLLM routes, the command also probes the host-side health endpoint and reports whether the backend is reachable. If the backend is down, the output includes an `Inference: unreachable` line with the local URL and a remediation hint. +The Policy section displays the live enforced policy (fetched via `openshell policy get --full`), which reflects presets added or removed after sandbox creation. +If the sandbox is running an outdated agent version, the output includes an `Update` line with the available version and a `nemoclaw rebuild` hint. + ```console $ nemoclaw my-assistant status ``` @@ -194,7 +205,8 @@ This removes the sandbox from the registry. > **Warning:** This command permanently deletes the sandbox **and its persistent volume**. > All workspace files (see the `nemoclaw-user-workspace` skill) (SOUL.md, USER.md, IDENTITY.md, AGENTS.md, MEMORY.md, and daily memory notes) are lost. -> Back up your workspace first — see Backup and Restore (see the `nemoclaw-user-workspace` skill). +> Back up your workspace first with `nemoclaw snapshot create` or see Backup and Restore (see the `nemoclaw-user-workspace` skill). +> If you want to upgrade the sandbox while preserving state, use `nemoclaw rebuild` instead. ```console $ nemoclaw my-assistant destroy @@ -228,6 +240,21 @@ List available policy presets and show which ones are applied to the sandbox. $ nemoclaw my-assistant policy-list ``` +### `nemoclaw policy-remove` + +Remove a previously applied policy preset from a sandbox. +The command lists only the presets currently applied, prompts you to select one, shows the endpoints that would be removed, and asks for confirmation before narrowing egress. + +```console +$ nemoclaw my-assistant policy-remove +``` + +| Flag | Description | +|------|-------------| +| `--dry-run` | Preview which endpoints would be removed without applying changes | + +Unchecking a preset in the onboard TUI checkbox also removes it from the sandbox. + ### `nemoclaw skill install ` Deploy a skill directory to a running sandbox. @@ -246,6 +273,63 @@ Files with unsafe path characters are rejected to prevent shell injection. If the skill already exists on the sandbox, the command updates it in place and preserves chat history. For new installs, the agent session index is refreshed so the agent discovers the skill on the next session. +### `nemoclaw rebuild` + +Upgrade a sandbox to the current agent version while preserving workspace state. +The command backs up workspace state, destroys the old sandbox, recreates it with the current image via `onboard --resume`, and restores workspace state into the new sandbox. +Credentials are stripped from backups before storage. + +```console +$ nemoclaw my-assistant rebuild [--yes] [--verbose] +``` + +| Flag | Description | +|------|-------------| +| `--yes`, `--force` | Skip the confirmation prompt | +| `--verbose` | Log SSH commands, exit codes, and session state (also enabled by `NEMOCLAW_REBUILD_VERBOSE=1`) | + +The sandbox must be running for the backup step to succeed. +After restore, the command runs `openclaw doctor --fix` for cross-version structure repair. + +### `nemoclaw backup-all` + +Back up all registered running sandboxes to `~/.nemoclaw/rebuild-backups/`. +Sandboxes that are not running are skipped. + +```console +$ nemoclaw backup-all +``` + +The installer calls `backup-all` automatically before onboarding to protect against data loss during OpenShell upgrades. + +### `nemoclaw snapshot create` + +Create a timestamped snapshot of sandbox state. +Snapshots are stored in `~/.nemoclaw/rebuild-backups//`. + +```console +$ nemoclaw my-assistant snapshot create +``` + +### `nemoclaw snapshot list` + +List available snapshots for a sandbox with timestamps and item counts. + +```console +$ nemoclaw my-assistant snapshot list +``` + +### `nemoclaw snapshot restore [timestamp]` + +Restore sandbox state from a snapshot. +If no timestamp is provided, the latest snapshot is used. +Partial timestamp prefixes are accepted if they match exactly one snapshot. + +```console +$ nemoclaw my-assistant snapshot restore +$ nemoclaw my-assistant snapshot restore 2026-04-14T +``` + ### `openshell term` Open the OpenShell TUI to monitor sandbox activity and approve network egress requests. diff --git a/.agents/skills/nemoclaw-user-reference/references/troubleshooting.md b/.agents/skills/nemoclaw-user-reference/references/troubleshooting.md index 163cb07612b..fe78fd8dac3 100644 --- a/.agents/skills/nemoclaw-user-reference/references/troubleshooting.md +++ b/.agents/skills/nemoclaw-user-reference/references/troubleshooting.md @@ -256,6 +256,24 @@ Follow these steps to reconnect. > The wizard prompts for confirmation before destroying an existing sandbox. If you confirm, it **destroys and recreates** the sandbox. Workspace files (SOUL.md, USER.md, IDENTITY.md, AGENTS.md, MEMORY.md, and daily memory notes) are lost. > Back up your workspace first by following the instructions at Back Up and Restore (see the `nemoclaw-user-workspace` skill). +### Sandbox is running an outdated agent version + +After upgrading NemoClaw, `nemoclaw connect` and `nemoclaw status` warn if the sandbox is running an older agent version than the current image. + +To upgrade the sandbox while preserving workspace state, run: + +```console +$ nemoclaw rebuild +``` + +The rebuild command backs up state, destroys the old sandbox, recreates it with the current image, and restores state. +Create a snapshot before rebuilding if you want an additional safety net: + +```console +$ nemoclaw snapshot create +$ nemoclaw rebuild +``` + ### Sandbox shows as stopped The sandbox may have been stopped or deleted. diff --git a/.agents/skills/nemoclaw-user-workspace/SKILL.md b/.agents/skills/nemoclaw-user-workspace/SKILL.md index 2b7cd9cd46a..ff83bcf31af 100644 --- a/.agents/skills/nemoclaw-user-workspace/SKILL.md +++ b/.agents/skills/nemoclaw-user-workspace/SKILL.md @@ -70,7 +70,7 @@ You can edit them in two ways: Workspace files define your agent's personality, memory, and user context. They persist across sandbox restarts but are **permanently deleted** when you run `nemoclaw destroy`. -This guide covers manual backup with CLI commands and an automated script. +This guide covers snapshot commands, manual backup with CLI commands, and an automated script. ## Step 1: When to Back Up @@ -78,7 +78,27 @@ This guide covers manual backup with CLI commands and an automated script. - Before major NemoClaw version upgrades - Periodically, if you've invested time customizing your agent -## Step 2: Manual Backup +## Step 2: Snapshot Commands + +The fastest way to back up and restore sandbox state is with the built-in snapshot commands. +Snapshots capture all workspace state directories defined in the agent manifest and store them in `~/.nemoclaw/rebuild-backups//`. + +```console +$ nemoclaw my-assistant snapshot create +$ nemoclaw my-assistant snapshot list +$ nemoclaw my-assistant snapshot restore +``` + +To restore a specific snapshot instead of the latest, pass a timestamp or prefix: + +```console +$ nemoclaw my-assistant snapshot restore 2026-04-14T +``` + +The `nemoclaw rebuild` command uses the same snapshot mechanism automatically. +For full details, see the Commands reference (see the `nemoclaw-user-reference` skill). + +## Step 3: Manual Backup Use `openshell sandbox download` to copy files from the sandbox to your host. @@ -95,7 +115,7 @@ $ openshell sandbox download "$SANDBOX" /sandbox/.openclaw/workspace/MEMORY.md " $ openshell sandbox download "$SANDBOX" /sandbox/.openclaw/workspace/memory/ "$BACKUP_DIR/memory/" ``` -## Step 3: Manual Restore +## Step 4: Manual Restore Use `openshell sandbox upload` to push files back into a sandbox. @@ -111,7 +131,7 @@ $ openshell sandbox upload "$SANDBOX" "$BACKUP_DIR/MEMORY.md" /sandbox/.openclaw $ openshell sandbox upload "$SANDBOX" "$BACKUP_DIR/memory/" /sandbox/.openclaw/workspace/memory/ ``` -## Step 4: Using the Backup Script +## Step 5: Using the Backup Script The repository includes a convenience script at `scripts/backup-workspace.sh`. @@ -137,7 +157,7 @@ Restore from a specific timestamp: $ ./scripts/backup-workspace.sh restore my-assistant 20260320-120000 ``` -## Step 5: Verifying a Backup +## Step 6: Verifying a Backup List backed-up files to confirm completeness: diff --git a/docs/network-policy/customize-network-policy.md b/docs/network-policy/customize-network-policy.md index acca7f752c8..fa28c8b8405 100644 --- a/docs/network-policy/customize-network-policy.md +++ b/docs/network-policy/customize-network-policy.md @@ -51,6 +51,12 @@ If you only need one of the built-in presets, use `nemoclaw policy-add` i $ nemoclaw my-assistant policy-add ``` +To remove a previously applied preset, use `nemoclaw policy-remove`: + +```console +$ nemoclaw my-assistant policy-remove +``` + Use a manual YAML edit when you need to allow custom hosts that are not covered by a preset, such as an internal API or a weather service. Each entry in the `network` section defines an endpoint group with the following fields: diff --git a/docs/reference/commands.md b/docs/reference/commands.md index 143865080e4..5211ab18ce0 100644 --- a/docs/reference/commands.md +++ b/docs/reference/commands.md @@ -194,6 +194,7 @@ $ nemoclaw deploy Connect to a sandbox by name. On a TTY, a one-shot hint prints before dropping into the sandbox shell, reminding you to run `openclaw tui` inside. Set `NEMOCLAW_NO_CONNECT_HINT=1` to suppress the hint in scripted workflows. +If the sandbox is running an outdated agent version, a non-blocking warning prints before connecting with a `nemoclaw rebuild` hint. ```console $ nemoclaw my-assistant connect @@ -205,6 +206,9 @@ Show sandbox status, health, and inference configuration. For local Ollama and local vLLM routes, the command also probes the host-side health endpoint and reports whether the backend is reachable. If the backend is down, the output includes an `Inference: unreachable` line with the local URL and a remediation hint. +The Policy section displays the live enforced policy (fetched via `openshell policy get --full`), which reflects presets added or removed after sandbox creation. +If the sandbox is running an outdated agent version, the output includes an `Update` line with the available version and a `nemoclaw rebuild` hint. + ```console $ nemoclaw my-assistant status ``` @@ -226,7 +230,8 @@ This removes the sandbox from the registry. :::{warning} This command permanently deletes the sandbox **and its persistent volume**. All [workspace files](../workspace/workspace-files.md) (SOUL.md, USER.md, IDENTITY.md, AGENTS.md, MEMORY.md, and daily memory notes) are lost. -Back up your workspace first — see [Backup and Restore](../workspace/backup-restore.md). +Back up your workspace first with `nemoclaw snapshot create` or see [Backup and Restore](../workspace/backup-restore.md). +If you want to upgrade the sandbox while preserving state, use `nemoclaw rebuild` instead. ::: ```console @@ -261,6 +266,21 @@ List available policy presets and show which ones are applied to the sandbox. $ nemoclaw my-assistant policy-list ``` +### `nemoclaw policy-remove` + +Remove a previously applied policy preset from a sandbox. +The command lists only the presets currently applied, prompts you to select one, shows the endpoints that would be removed, and asks for confirmation before narrowing egress. + +```console +$ nemoclaw my-assistant policy-remove +``` + +| Flag | Description | +|------|-------------| +| `--dry-run` | Preview which endpoints would be removed without applying changes | + +Unchecking a preset in the onboard TUI checkbox also removes it from the sandbox. + ### `nemoclaw skill install ` Deploy a skill directory to a running sandbox. @@ -279,6 +299,63 @@ Files with unsafe path characters are rejected to prevent shell injection. If the skill already exists on the sandbox, the command updates it in place and preserves chat history. For new installs, the agent session index is refreshed so the agent discovers the skill on the next session. +### `nemoclaw rebuild` + +Upgrade a sandbox to the current agent version while preserving workspace state. +The command backs up workspace state, destroys the old sandbox, recreates it with the current image via `onboard --resume`, and restores workspace state into the new sandbox. +Credentials are stripped from backups before storage. + +```console +$ nemoclaw my-assistant rebuild [--yes] [--verbose] +``` + +| Flag | Description | +|------|-------------| +| `--yes`, `--force` | Skip the confirmation prompt | +| `--verbose` | Log SSH commands, exit codes, and session state (also enabled by `NEMOCLAW_REBUILD_VERBOSE=1`) | + +The sandbox must be running for the backup step to succeed. +After restore, the command runs `openclaw doctor --fix` for cross-version structure repair. + +### `nemoclaw backup-all` + +Back up all registered running sandboxes to `~/.nemoclaw/rebuild-backups/`. +Sandboxes that are not running are skipped. + +```console +$ nemoclaw backup-all +``` + +The installer calls `backup-all` automatically before onboarding to protect against data loss during OpenShell upgrades. + +### `nemoclaw snapshot create` + +Create a timestamped snapshot of sandbox state. +Snapshots are stored in `~/.nemoclaw/rebuild-backups//`. + +```console +$ nemoclaw my-assistant snapshot create +``` + +### `nemoclaw snapshot list` + +List available snapshots for a sandbox with timestamps and item counts. + +```console +$ nemoclaw my-assistant snapshot list +``` + +### `nemoclaw snapshot restore [timestamp]` + +Restore sandbox state from a snapshot. +If no timestamp is provided, the latest snapshot is used. +Partial timestamp prefixes are accepted if they match exactly one snapshot. + +```console +$ nemoclaw my-assistant snapshot restore +$ nemoclaw my-assistant snapshot restore 2026-04-14T +``` + ### `openshell term` Open the OpenShell TUI to monitor sandbox activity and approve network egress requests. diff --git a/docs/reference/troubleshooting.md b/docs/reference/troubleshooting.md index 2ad1fe8fb87..a7b1c13cb03 100644 --- a/docs/reference/troubleshooting.md +++ b/docs/reference/troubleshooting.md @@ -286,6 +286,24 @@ The wizard prompts for confirmation before destroying an existing sandbox. If yo Back up your workspace first by following the instructions at [Back Up and Restore](../workspace/backup-restore.md). ::: +### Sandbox is running an outdated agent version + +After upgrading NemoClaw, `nemoclaw connect` and `nemoclaw status` warn if the sandbox is running an older agent version than the current image. + +To upgrade the sandbox while preserving workspace state, run: + +```console +$ nemoclaw rebuild +``` + +The rebuild command backs up state, destroys the old sandbox, recreates it with the current image, and restores state. +Create a snapshot before rebuilding if you want an additional safety net: + +```console +$ nemoclaw snapshot create +$ nemoclaw rebuild +``` + ### Sandbox shows as stopped The sandbox may have been stopped or deleted. diff --git a/docs/versions1.json b/docs/versions1.json index 376e9d65d97..bdeb5a24f7c 100644 --- a/docs/versions1.json +++ b/docs/versions1.json @@ -1,6 +1,10 @@ [ { "preferred": true, + "version": "0.0.16", + "url": "https://docs.nvidia.com/nemoclaw/0.0.16/" + }, + { "version": "0.0.15", "url": "https://docs.nvidia.com/nemoclaw/0.0.15/" }, diff --git a/docs/workspace/backup-restore.md b/docs/workspace/backup-restore.md index 4f4322258ce..2dcf097071f 100644 --- a/docs/workspace/backup-restore.md +++ b/docs/workspace/backup-restore.md @@ -23,7 +23,7 @@ status: published Workspace files define your agent's personality, memory, and user context. They persist across sandbox restarts but are **permanently deleted** when you run `nemoclaw destroy`. -This guide covers manual backup with CLI commands and an automated script. +This guide covers snapshot commands, manual backup with CLI commands, and an automated script. ## When to Back Up @@ -31,6 +31,26 @@ This guide covers manual backup with CLI commands and an automated script. - Before major NemoClaw version upgrades - Periodically, if you've invested time customizing your agent +## Snapshot Commands + +The fastest way to back up and restore sandbox state is with the built-in snapshot commands. +Snapshots capture all workspace state directories defined in the agent manifest and store them in `~/.nemoclaw/rebuild-backups//`. + +```console +$ nemoclaw my-assistant snapshot create +$ nemoclaw my-assistant snapshot list +$ nemoclaw my-assistant snapshot restore +``` + +To restore a specific snapshot instead of the latest, pass a timestamp or prefix: + +```console +$ nemoclaw my-assistant snapshot restore 2026-04-14T +``` + +The `nemoclaw rebuild` command uses the same snapshot mechanism automatically. +For full details, see the [Commands reference](../reference/commands.md). + ## Manual Backup Use `openshell sandbox download` to copy files from the sandbox to your host.