fix(snapshot): never capture or restore OpenClaw runtime auth state

[harjothkhara]

Summary

nemoclaw snapshot create runs every backed-up .json file through the credential sanitizer, which scrubs the key/token fields of OpenClaw's device identity (identity/device.json Ed25519 keypair) and paired-device token store (devices/). snapshot restore then wiped the sandbox's live pairing state and installed those scrubbed copies, so after a clone or restore the gateway destabilized and ordinary CLI clients (openclaw agent, openclaw tui) failed with GatewayCredentialsRequiredError. This surfaced at v0.0.75 once OpenClaw 2026.6.10 and the local-loopback pairing path (#6291) stopped providing an ambient gateway token that had been masking the corruption. After this change, backup no longer captures device identity or pairing state and restore never touches it; OpenClaw regenerates the device identity on demand and NemoClaw auto-pair re-pairs on connect.

Related Issue

Fixes #6852

Changes

• Add a runtime_auth_state_dirs agent-manifest field (src/lib/agent/definition-types.ts, src/lib/agent/defs.ts). Its consumer is the snapshot backup/restore path in src/lib/state/sandbox.ts, which needs to distinguish machine-local auth state (device keys, pairing tokens) from durable user state. A direct exclusion in code would hard-code OpenClaw-specific dir names into the shared backup engine; the manifest keeps the agent contract declarative and per-agent. The reader validates that every entry is also a state_dirs member. Protected by src/lib/agent/runtime-auth-state-dirs.test.ts.
• Declare identity and devices as runtime_auth_state_dirs in agents/openclaw/manifest.yaml. They stay in state_dirs so destroy still wipes them from the durable volume.
• backupSandboxState filters runtime_auth_state_dirs out of the captured set; restoreSandboxStateInternal filters them out of the pre-restore cleanup and tar extract, keyed on the current target manifest so legacy snapshots that still contain those dirs are also skipped. Protected by test/snapshot-runtime-auth-state.test.ts (a round-trip integration test that fails on unpatched main).
• Document the exclusion in docs/manage-sandboxes/backup-restore.mdx (OpenClaw variant).

_{AI-assisted contribution.}

Type of Change

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

Quality Gates

• Tests added or updated for changed behavior
• Existing tests cover changed behavior — justification:
• Tests not applicable — justification:
• Docs updated for user-facing behavior changes
• Docs not applicable — justification:
• Sensitive paths changed (security, policy, credentials, preflight, onboarding, inference, runner, sandbox, or messaging)
• Sensitive-path review completed or maintainer-approved waiver recorded — reviewer/approval link/justification: change removes credential-scrubbed device-auth state from the backup/restore path; net effect is that machine-local auth secrets are never captured into snapshots (strictly reduces credential surface). Requesting maintainer sensitive-path review.
• Non-success, skipped, or missing CI check accepted by maintainer — check name, approval link, and follow-up issue:

Verification

• PR description includes a Signed-off-by: line and every commit appears as Verified in GitHub
• Normal pre-commit, commit-msg, and pre-push hooks passed, or npm run check:diff passed when hooks were skipped or unavailable
• Targeted behavior tests pass for the current change set, or tests are marked not applicable above — command/result: npx vitest run test/snapshot-runtime-auth-state.test.ts src/lib/agent/runtime-auth-state-dirs.test.ts → 5 passed; the integration test is red on unpatched main (expected [ 'agents', 'identity', 'devices' ] to not include 'identity'), green on this branch.
• Applicable broad gate passed — npm test for broad runtime/test-harness changes; npm run check for repo-wide validation/coverage changes — command/result:
• Quality Gates section completed with required justifications or waivers
• No secrets, API keys, or credentials committed
• npm run 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)

_{Note: dynamic Linux/Brev end-to-end verification was not run, so the gateway-crash symptom is not confirmed live. The credential-loss root cause and fix are static-traced (through NemoClaw's backup sanitizer and OpenClaw's GatewayCredentialsRequiredError throw site) and covered by the red-green integration test above.}

---

Signed-off-by: harjoth harjoth.khara@gmail.com

Summary by CodeRabbit

• New Features
  • Added agent manifest support for declaring runtime authentication state directories.
  • OpenClaw runtime authentication state is excluded from backups and handled safely during restores.
• Bug Fixes
  • Backups no longer include OpenClaw identity keys and paired-device tokens.
  • Restores no longer overwrite the sandbox’s live gateway authentication state, even from legacy snapshots.
• Documentation
  • Clarified what is excluded from snapshots and how identity/device state is regenerated.
• Tests
  • Added validation and regression coverage for backup exclusion and restore safety.

[copy-pr-bot]

This pull request requires additional validation before any workflows can run on NVIDIA's runners.

Pull request vetters can view their responsibilities here.

Contributors can view more details about this message here.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 22b63dc4-5769-4e6c-9381-99593c0cdfde

📥 Commits

Reviewing files that changed from the base of the PR and between 5f2fe26 and 10637bc.

📒 Files selected for processing (1)

• test/snapshot-runtime-auth-state.test.ts

🚧 Files skipped from review as they are similar to previous changes (1)

• test/snapshot-runtime-auth-state.test.ts

---

📝 Walkthrough

Walkthrough

OpenClaw declares identity and devices as runtime authentication directories. Agent loading validates and exposes them, while sandbox backup and restore exclude them. Tests cover parsing, legacy snapshots, and preservation of live authentication state.

Changes

Runtime authentication state

Layer / File(s)	Summary
Runtime authentication contract and agent loading agents/openclaw/manifest.yaml, src/lib/agent/definition-types.ts, src/lib/agent/defs.ts, src/lib/agent/*test*, test/helpers/base-image-test-harness.ts	Adds runtime_auth_state_dirs, validates entries against state_dirs, exposes runtimeAuthStateDirs, and updates fixtures and parsing tests.
Snapshot backup and restore filtering src/lib/state/sandbox.ts, test/snapshot-runtime-auth-state.test.ts, docs/manage-sandboxes/backup-restore.mdx	Excludes runtime authentication directories from backup manifests and restore operations, with regression coverage for legacy snapshots and documentation of the restore behavior.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Suggested labels: area: sandbox, bug-fix

Suggested reviewers: cv

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 25.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly matches the main change: preventing OpenClaw runtime auth state from being captured or restored.
Linked Issues check	✅ Passed	[#6852] The PR excludes OpenClaw identity/devices from snapshot backup/restore and adds tests/docs covering the reported credential-loss regression.
Out of Scope Changes check	✅ Passed	All changes relate to snapshot safety for OpenClaw runtime auth state, with supporting manifest, code, tests, and docs updates.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

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

[github-actions]

PR Review Advisor — Informational

Advisor assessment: Informational / high confidence
Next action: No advisor follow-up needed.
Findings: 0 blockers · 0 warnings · 0 suggestions
Status: No actionable findings remain in the canonical review ledger.

Model lanes

• GPT-5.6 Terra (primary): Completed · high confidence · 0 blockers · 0 warnings · 0 suggestions
• Nemotron 3 Ultra (second opinion): Completed · high confidence · 0 blockers · 0 warnings · 0 suggestions
• Model comparison: normalized findings match; normalized E2E selections differ; severity counts match.

Nemotron output stays in workflow artifacts and does not change the assessment above.

E2E guidance

Advisory only. E2E / PR Gate selects and runs jobs independently.

Recommended E2E: full-e2e, hermes-e2e, onboard-repair, onboard-resume

3 optional E2E recommendations

• state-backup-restore
• snapshot-commands
• ubuntu-repo-cloud-openclaw

Workflow run details

This automated review informs maintainers. Warnings and suggestions do not require a response. A maintainer decides whether to merge.

[wscurran]

✨ Thanks for the fix. Preventing snapshot from capturing and restoring OpenClaw runtime auth state avoids gateway destabilization after clone or restore. Ready for maintainer review.

---

Related open issues:

• #6852 gateway crashes and loses auth credentials in cloned/restored sandboxes on v0.0.75

---

Related open PRs:

• #6291 fix(openclaw): restore local CLI pairing path

---

Related open issues:

• #6852 gateway crashes and loses auth credentials in cloned/restored sandboxes on v0.0.75

[prekshivyas]

@cv Exact head 10637bc861c636d4019ad51b72a7c6884c0aefb9 has been maintainer-reviewed and all non-credentialed CI is green. The E2E gate selected full-e2e, hermes-e2e, onboard-repair, and onboard-resume and is waiting on the protected approve-credentialed-e2e-skip-for-fork-pr deployment. Please approve Review deployments on run 29373914686. No fork code received repository secrets.

[cv]

@prekshivyas approved, please review

[prekshivyas]

Reviewed exact head 10637bc. Snapshot filtering and legacy-restore behavior are correct and covered; CI, PR Advisor, CodeRabbit, and the policy-approved fork E2E gate are clear.