docs: add reconnect/restart steps after reboot to troubleshooting guide

[RitikKadyan]

Adds a "Reconnecting after a reboot" section to the troubleshooting guide with step-by-step instructions for restoring a NemoClaw session after a machine restart.

Fixes #469

Summary

Adds a "Reconnecting after a reboot" section to the troubleshooting guide with step-by-step instructions for restoring a NemoClaw session after a machine restart. Also clarifies the existing "Sandbox shows as stopped" entry to distinguish reboot scenarios from other causes.

Related Issue

Fixes #469

Changes

• Added "Reconnecting after a reboot" section to docs/reference/troubleshooting.md
• Steps cover verifying Docker, checking sandbox state with openshell sandbox list and nemoclaw status, reconnecting with nemoclaw <name> connect, re-running onboard if needed, and restarting auxiliary services
• Updated "Sandbox shows as stopped" to clarify non-reboot scenarios

Type of Change

• Code change for a new feature, bug fix, or refactor.
• Code change with doc updates.
• Doc only. Prose changes without code sample modifications.
• Doc only. Includes code sample changes.

Testing

• make check passes.
• npm test passes.
• make docs builds without warnings. (for doc-only changes)

Note: These steps are based on the existing CLI reference and README documentation. I have not tested the full reboot flow end-to-end on a live NemoClaw installation. Would appreciate a maintainer verifying the exact reconnect behavior before merging.

Checklist

General

• I have read and followed the contributing guide.
• I have read and followed the style guide. (for doc-only changes)

Code Changes

• make format applied (TypeScript and Python).
• Tests added or updated for new or changed behavior.
• No secrets, API keys, or credentials committed.
• Doc pages updated for any user-facing behavior changes (new commands, changed defaults, new features, bug fixes that contradict existing docs).

Doc Changes

• Follows the style guide. Try running the update-docs agent skill to draft changes while complying with the style guide. For example, prompt your agent with "/update-docs catch up the docs for the new changes I made in this PR."
• New pages include SPDX license header and frontmatter, if creating a new page.
• Cross-references and links verified.

Summary by CodeRabbit

• Documentation
  • Added a troubleshooting guide with step-by-step recovery instructions for reconnecting after a reboot.

[coderabbitai]

📝 Walkthrough

Walkthrough

Documentation enhancement adding a "Reconnecting after a reboot" troubleshooting section to guide users through recovery steps, including Docker verification, sandbox inspection, and reconnection procedures using nemoclaw commands.

Changes

Cohort / File(s)	Summary
Troubleshooting Documentation docs/reference/troubleshooting.md	Added new "Reconnecting after a reboot" section with step-by-step recovery flow: verify Docker status, inspect sandboxes via openshell sandbox list, check registered sandboxes with nemoclaw status, reconnect to stopped sandboxes or recreate with nemoclaw onboard, and restart services with nemoclaw start.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~8 minutes

Poem

🐰 A sandbox reboots, but fear not, friend!
With nemoclaw's commands, the tale won't end—
List, inspect, reconnect with care,
Your agents await you, still dwelling there! ✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'docs: add reconnect/restart steps after reboot to troubleshooting guide' clearly and concisely summarizes the main change: adding documentation for reconnecting after a reboot.
Linked Issues check	✅ Passed	The PR fully addresses issue #469 by documenting the step-by-step process to reconnect to a NemoClaw sandbox after a machine reboot, including Docker verification, sandbox status checks, and reconnection/recreation commands.
Out of Scope Changes check	✅ Passed	All changes are directly related to the linked issue #469 objective of documenting reconnection steps after a reboot; no unrelated modifications are present.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

📝 Coding Plan

• Generate coding plan for human review comments

---

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

Tip

CodeRabbit can scan for known vulnerabilities in your dependencies using OSV Scanner.

OSV Scanner will automatically detect and report security vulnerabilities in your project's dependencies. No additional configuration is required.

[coderabbitai]

🧹 Nitpick comments (1)

docs/reference/troubleshooting.md (1)

163-163: Use active voice in this sentence.

“has been removed entirely” is passive; please rewrite in active voice to match the docs style requirements.

As per coding guidelines, "Active voice required. Flag passive constructions."

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/reference/troubleshooting.md` at line 163, Rewrite the sentence "This
shows whether your sandbox still exists but is stopped, or has been removed
entirely." to use active voice; replace the passive clause "has been removed
entirely" with an active construction such as "you have removed it entirely" so
the full sentence reads: "This shows whether your sandbox still exists but is
stopped, or you have removed it entirely."

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Nitpick comments:
In `@docs/reference/troubleshooting.md`:
- Line 163: Rewrite the sentence "This shows whether your sandbox still exists
but is stopped, or has been removed entirely." to use active voice; replace the
passive clause "has been removed entirely" with an active construction such as
"you have removed it entirely" so the full sentence reads: "This shows whether
your sandbox still exists but is stopped, or you have removed it entirely."

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 24318169-7da9-46c2-b756-d5da9ca5533e

📥 Commits

Reviewing files that changed from the base of the PR and between dbfd78c and dc648a2.

📒 Files selected for processing (1)

• docs/reference/troubleshooting.md

[wscurran]

Thanks for adding reconnect/restart steps to the troubleshooting guide, this should help users get back up and running after a reboot.

[RitikKadyan]

Thanks for adding reconnect/restart steps to the troubleshooting guide, this should help users get back up and running after a reboot.

Of course!

[prekshivyas]

Hey @RitikKadyan — thanks for working on this! Just a heads-up that we have an overlapping PR at #911 that also addresses #469.

After digging into the onboard.js and OpenShell code, we found a couple of things that might be worth noting:

1. Gateway restart step: After a reboot, the OpenShell gateway doesn't auto-start. Running openshell gateway start --name nemoclaw is needed before the sandbox can recover — without it, openshell sandbox list won't return results.
2. Data loss warning: nemoclaw onboard destroys and recreates the sandbox, which means workspace files (SOUL.md, USER.md, etc.) are lost. We added a warning admonition about backing up first.

Since both PRs target the same issue, it might make sense to consolidate. Happy to coordinate either way!