docs: document workspace file persistence and backup/restore guidance#476
docs: document workspace file persistence and backup/restore guidance#476BenediktSchackenberg wants to merge 3 commits intoNVIDIA:mainfrom
Conversation
- Add docs/workspace/workspace-files.md explaining SOUL.md, USER.md, IDENTITY.md, AGENTS.md, MEMORY.md and their persistence behavior - Add docs/workspace/backup-restore.md with manual and scripted backup instructions - Add scripts/backup-workspace.sh for automated backup and restore - Add warning to 'nemoclaw destroy' command docs about data loss - Add Workspace section to docs index and navigation Closes NVIDIA#434 AI-assisted: Built with Claude, reviewed by human.
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: Path: .coderabbit.yaml Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (1)
✅ Files skipped from review due to trivial changes (1)
📝 WalkthroughWalkthroughAdds documentation and navigation for OpenClaw workspace files, warns that they are removed by Changes
Sequence Diagram(s)sequenceDiagram
autonumber
participant User as User
participant Script as Backup Script
participant CLI as openshell CLI
participant Sandbox as Sandbox (PVC)
User->>Script: run `scripts/backup-workspace.sh backup <name>`
Script->>CLI: `openshell sandbox download <name> /sandbox/.openclaw/workspace/...`
CLI->>Sandbox: fetch files from `/sandbox/.openclaw/workspace/`
Sandbox-->>CLI: returns files or per-item errors
CLI-->>Script: save files to `${HOME}/.nemoclaw/backups/<timestamp>/`
Script-->>User: print backup path and summary
sequenceDiagram
autonumber
participant User as User
participant Script as Backup Script
participant CLI as openshell CLI
participant Sandbox as Sandbox (PVC)
User->>Script: run `scripts/backup-workspace.sh restore <name> [timestamp]`
Script->>Script: select backup directory (arg or latest)
Script->>CLI: `openshell sandbox upload <name> /sandbox/.openclaw/workspace/<file>`
CLI->>Sandbox: write files to `/sandbox/.openclaw/workspace/`
Sandbox-->>CLI: ack or per-item error
CLI-->>Script: report successes/failures
Script-->>User: print restored item count and status
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes Poem
🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Comment Tip You can disable poems in the walkthrough.Disable the |
There was a problem hiding this comment.
Pull request overview
Adds documentation and tooling to clarify how OpenClaw “workspace files” persist inside sandboxes and how users can back them up before destructive operations.
Changes:
- Adds new docs describing workspace files, their on-sandbox location, and persistence behavior.
- Adds a backup/restore how-to guide (manual CLI steps + convenience script workflow).
- Introduces
scripts/backup-workspace.shto automate backup/restore of workspace files, and adds a destroy-data-loss warning in the commands reference + navigation updates.
Reviewed changes
Copilot reviewed 5 out of 5 changed files in this pull request and generated 6 comments.
Show a summary per file
| File | Description |
|---|---|
| scripts/backup-workspace.sh | New helper script to backup/restore workspace files via openshell sandbox download/upload. |
| docs/workspace/workspace-files.md | New concept page defining workspace files, location, and persistence/loss conditions. |
| docs/workspace/backup-restore.md | New how-to page for manual backup/restore and using the convenience script. |
| docs/reference/commands.md | Adds a warning that nemoclaw <name> destroy deletes persistent workspace data. |
| docs/index.md | Adds workspace docs to the homepage grid and toctree navigation. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
docs/workspace/workspace-files.md
Outdated
| @@ -0,0 +1,83 @@ | |||
| --- | |||
| title: | |||
| page: "Workspace Files — SOUL.md, USER.md, IDENTITY.md, and AGENTS.md" | |||
There was a problem hiding this comment.
The Workspace Files page title enumerates specific files but omits MEMORY.md even though it is listed and described on the page. Consider either including MEMORY.md in the title or removing the explicit enumeration to avoid the title drifting as the set of workspace files evolves.
| page: "Workspace Files — SOUL.md, USER.md, IDENTITY.md, and AGENTS.md" | |
| page: "Workspace Files" |
There was a problem hiding this comment.
Good catch — simplified the title to just "Workspace Files". No more incomplete enumeration.
docs/workspace/workspace-files.md
Outdated
| Sandbox restarts (`nemoclaw <name> restart` or `openshell sandbox restart`) preserve workspace files. | ||
| The sandbox uses a **Persistent Volume Claim (PVC)** that outlives individual container restarts. | ||
|
|
||
| ### Lost: Gateway Destroy |
There was a problem hiding this comment.
This section header says “Lost: Gateway Destroy”, but the text below refers to nemoclaw <name> destroy, which is the sandbox destroy command. To avoid confusion, rename the header to match the actual destructive operation (or explicitly distinguish gateway vs sandbox destroy if both apply).
| ### Lost: Gateway Destroy | |
| ### Lost: Sandbox Destroy |
There was a problem hiding this comment.
Fixed — header now says "Sandbox Destroy" to match the actual command.
docs/workspace/workspace-files.md
Outdated
| ```{warning} | ||
| Always back up your workspace files before running `nemoclaw <name> destroy`. | ||
| See [Backup and Restore](backup-restore.md) for instructions. | ||
| ``` |
There was a problem hiding this comment.
This warning uses the fenced-code admonition form (```{warning}), but the repo’s doc style guidance and many existing pages use the :::{warning} / `:::` MyST admonition syntax. Please switch to the `:::{warning}` form for consistency.
| ```{warning} | |
| Always back up your workspace files before running `nemoclaw <name> destroy`. | |
| See [Backup and Restore](backup-restore.md) for instructions. | |
| ``` | |
| :::{warning} | |
| Always back up your workspace files before running `nemoclaw <name> destroy`. | |
| See [Backup and Restore](backup-restore.md) for instructions. | |
| ::: |
There was a problem hiding this comment.
Switched to :::{warning} / ::: MyST syntax. Also fixed the same pattern in commands.md.
| ts="$(date +%Y%m%d-%H%M%S)" | ||
| local dest="${BACKUP_BASE}/${ts}" | ||
|
|
||
| mkdir -p "$dest" |
There was a problem hiding this comment.
Backups will contain user context and long-term memory content. The script creates the backup directory with default permissions, which may be group/world-readable depending on the user’s umask. Consider explicitly setting restrictive permissions (e.g., creating the backup base/dir with 0700) to better protect potentially sensitive data; this matches the repo’s pattern of using 0700/0600 under ~/.nemoclaw for credentials.
| mkdir -p "$dest" | |
| mkdir -p -m 700 "$BACKUP_BASE" | |
| mkdir -p -m 700 "$dest" |
There was a problem hiding this comment.
Added mkdir -p -m 0700 for the backup base directory before creating the timestamped subdirectory.
docs/workspace/backup-restore.md
Outdated
| ```console | ||
| $ ./scripts/backup-workspace.sh backup my-assistant | ||
| Backing up workspace from sandbox 'my-assistant'... | ||
| Backup saved to /home/user/.nemoclaw/backups/20260320-120000/ |
There was a problem hiding this comment.
The sample script output here doesn’t match the current script behavior. scripts/backup-workspace.sh prints Backup saved to … (N items) (and may also print skipped-file lines). Consider updating this example output to match the script so users can recognize a successful run.
| Backup saved to /home/user/.nemoclaw/backups/20260320-120000/ | |
| Backup saved to /home/user/.nemoclaw/backups/20260320-120000/ (6 items) |
There was a problem hiding this comment.
Updated the sample output to include the (6 items) count suffix to match what the script actually prints.
docs/reference/commands.md
Outdated
| ```{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). | ||
| ``` |
There was a problem hiding this comment.
The docs use MyST admonitions with the :::{warning} / ::: syntax elsewhere in this file (e.g., the nemoclaw deploy section). This new block uses the fenced-code admonition form (```{warning}), which is inconsistent with the repo’s documented style in docs/CONTRIBUTING.md. Please convert this warning to the :::{warning} form for consistency.
| ```{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). | |
| ``` | |
| :::{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). | |
| ::: |
There was a problem hiding this comment.
Fixed — same :::{warning} / ::: treatment as the other admonition.
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🧹 Nitpick comments (1)
scripts/backup-workspace.sh (1)
85-97: Restore uploads lack error handling.The backup function logs skipped files on failure, but restore silently continues if
openshell sandbox uploadfails. Consider adding error handling for consistency.Proposed improvement
for f in "${FILES[@]}"; do if [ -f "${src}/${f}" ]; then - openshell sandbox upload "$sandbox" "${src}/${f}" "${WORKSPACE_PATH}/" - count=$((count + 1)) + if openshell sandbox upload "$sandbox" "${src}/${f}" "${WORKSPACE_PATH}/"; then + count=$((count + 1)) + else + echo " Failed to restore ${f}" + fi fi done for d in "${DIRS[@]}"; do if [ -d "${src}/${d}" ]; then - openshell sandbox upload "$sandbox" "${src}/${d}/" "${WORKSPACE_PATH}/${d}/" - count=$((count + 1)) + if openshell sandbox upload "$sandbox" "${src}/${d}/" "${WORKSPACE_PATH}/${d}/"; then + count=$((count + 1)) + else + echo " Failed to restore ${d}/" + fi fi done🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@scripts/backup-workspace.sh` around lines 85 - 97, The restore loops that call openshell sandbox upload for FILES and DIRS currently ignore failures; update both loops (the one iterating over FILES and the one iterating over DIRS) to check the upload command's exit status and handle errors consistently: after running openshell sandbox upload "$sandbox" "${src}/${f}" ... and openshell sandbox upload "$sandbox" "${src}/${d}/" ..., capture the return code and on failure log an error including the path and $sandbox (e.g., via echo or processLogger), optionally increment a failure counter and exit with non-zero status or mark the file as skipped to match existing behavior for backups, so failures are not silently ignored.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@docs/workspace/workspace-files.md`:
- Around line 41-51: The fenced directory tree block is missing a language
identifier; update the opening fence for the directory listing (the
triple-backtick that precedes the "/sandbox/.openclaw/workspace/" tree) to
include the language `text` (i.e., change ``` to ```text) so the code block for
the directory tree (the lines showing AGENTS.md, IDENTITY.md, MEMORY.md, etc.,
and the memory/ subentries) has a language specified.
In `@scripts/backup-workspace.sh`:
- Around line 60-62: The current cleanup uses rmdir "$dest" which fails if any
subdirectories (e.g. the memory/ dir) exist and leaves a partial directory;
change the cleanup to remove the entire destination directory recursively and
safely (e.g. replace rmdir "$dest" 2>/dev/null || true with a safe recursive
removal like rm -rf "$dest" 2>/dev/null || true) so that when count is 0 the
full $dest (including memory/) is removed before calling die; ensure you
reference the same $dest and sandbox variables and keep the error
suppression/behaviour consistent.
---
Nitpick comments:
In `@scripts/backup-workspace.sh`:
- Around line 85-97: The restore loops that call openshell sandbox upload for
FILES and DIRS currently ignore failures; update both loops (the one iterating
over FILES and the one iterating over DIRS) to check the upload command's exit
status and handle errors consistently: after running openshell sandbox upload
"$sandbox" "${src}/${f}" ... and openshell sandbox upload "$sandbox"
"${src}/${d}/" ..., capture the return code and on failure log an error
including the path and $sandbox (e.g., via echo or processLogger), optionally
increment a failure counter and exit with non-zero status or mark the file as
skipped to match existing behavior for backups, so failures are not silently
ignored.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
Run ID: ed643d03-5f65-4a52-92aa-9f6b7127cb32
📒 Files selected for processing (5)
docs/index.mddocs/reference/commands.mddocs/workspace/backup-restore.mddocs/workspace/workspace-files.mdscripts/backup-workspace.sh
- Make page title generic ('Workspace Files' without enumeration)
- Fix 'Gateway Destroy' header to 'Sandbox Destroy'
- Convert admonitions to MyST syntax (:::{warning}/:::)
- Add language specifier to code block (```text)
- Secure backup base directory with mkdir -m 0700
- Fix sample output to match script output format
- Use rm -rf instead of rmdir for partial backup cleanup
- Add error handling to restore uploads
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (1)
docs/workspace/workspace-files.md (1)
57-62: Remove colons from section titles.The H3 titles "Survives: Sandbox Restart" and "Lost: Sandbox Destroy" contain colons.
Rephrase to remove the colons, for example: "Sandbox Restart Preserves Files" and "Sandbox Destroy Deletes Files".As per coding guidelines: "No colons in titles."
Proposed fix
-### Survives: Sandbox Restart +### Sandbox Restart Preserves Files Sandbox restarts (`nemoclaw <name> restart` or `openshell sandbox restart`) preserve workspace files. The sandbox uses a **Persistent Volume Claim (PVC)** that outlives individual container restarts. -### Lost: Sandbox Destroy +### Sandbox Destroy Deletes Files🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/workspace/workspace-files.md` around lines 57 - 62, Update the two H3 headings that contain colons: change "Survives: Sandbox Restart" to "Sandbox Restart Preserves Files" and change "Lost: Sandbox Destroy" to "Sandbox Destroy Deletes Files"; locate the headings by their exact current text and replace them (in the H3 markdown lines starting with ###) so the titles no longer contain colons and match the suggested phrasing.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@scripts/backup-workspace.sh`:
- Around line 40-41: The mkdir invocation in scripts/backup-workspace.sh uses
`-p -m 0700` but that only sets mode on the deepest directory; parent dirs may
be created with the default umask and remain world-readable. Change the logic so
parent directories are created with restrictive permissions too: create the
parent path(s) first or create with a tool that accepts mode for all created
segments (or use mkdir -p then explicitly chmod the whole BACKUP_BASE and dest
paths to 0700). Update the lines that reference BACKUP_BASE and dest (the
existing mkdir -p -m 0700 "$BACKUP_BASE" and mkdir -p "$dest") to ensure both
resulting directories end up with mode 0700.
---
Nitpick comments:
In `@docs/workspace/workspace-files.md`:
- Around line 57-62: Update the two H3 headings that contain colons: change
"Survives: Sandbox Restart" to "Sandbox Restart Preserves Files" and change
"Lost: Sandbox Destroy" to "Sandbox Destroy Deletes Files"; locate the headings
by their exact current text and replace them (in the H3 markdown lines starting
with ###) so the titles no longer contain colons and match the suggested
phrasing.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
Run ID: b158953e-67fc-4f6c-bade-0e90c191e3a5
📒 Files selected for processing (4)
docs/reference/commands.mddocs/workspace/backup-restore.mddocs/workspace/workspace-files.mdscripts/backup-workspace.sh
✅ Files skipped from review due to trivial changes (2)
- docs/reference/commands.md
- docs/workspace/backup-restore.md
|
Thanks for documenting workspace file persistence and backup/restore guidance, this will help users understand how to manage their workspace files. |
wscurran
added
Getting Started
- Make page title generic ('Workspace Files' without enumeration)
- Fix 'Gateway Destroy' header to 'Sandbox Destroy'
- Convert admonitions to MyST syntax (:::{warning}/:::)
- Add language specifier to code block (```text)
- Secure backup base directory with mkdir -m 0700
- Fix sample output to match script output format
- Use rm -rf instead of rmdir for partial backup cleanup
- Add error handling to restore uploads
Summary
Addresses #434 — documents the persistence behavior of workspace files (SOUL.md, USER.md, IDENTITY.md, AGENTS.md, MEMORY.md) and provides backup/restore guidance.
Changes
docs/workspace/workspace-files.md— New page explaining what workspace files are, where they live (/sandbox/.openclaw/workspace/), that they survive sandbox restarts (PVC) but are lost ongateway destroy.docs/workspace/backup-restore.md— How-to guide for manual backup/restore withopenshell sandbox download/uploadcommands, plus usage of the convenience script.scripts/backup-workspace.sh— Bash script for automated backup and restore of workspace files. Supportsbackup <sandbox>andrestore <sandbox> [timestamp].docs/reference/commands.md— Added warning tonemoclaw <name> destroyabout permanent workspace data loss.docs/index.md— Added Workspace section to navigation and Explore grid.Closes #434
AI-assisted: Built with Claude, reviewed by human.
Summary by CodeRabbit
Documentation
New Features