Description

After a host reboot, users must manually run multiple commands to reconnect to their sandbox: start Docker, restart the OpenShell gateway, check sandbox state, then connect. This is documented in the troubleshooting guide but could be a single command.

A nemoclaw reconnect command would automate the recovery sequence:

1. Verify the container runtime is running
2. Start the OpenShell gateway if it's not running (openshell gateway start --name nemoclaw)
3. Wait for the gateway to become healthy
4. Check sandbox state (openshell sandbox list)
5. Start port forward and connect to the default (or named) sandbox

Context

• Issue Please add restart commands to documentation #469 requested documentation for reconnecting after a reboot — addressed by the docs PR
• PR docs(troubleshooting): explain reconnect flow after host reboot #904 (by @WuKongAI-CMU) also attempted to document this but was closed due to PR limit
• The building blocks already exist in the codebase:
  • sandboxConnect() in bin/nemoclaw.js handles port forwarding and connection
  • bin/lib/onboard.js has gateway start, health check, and CoreDNS fix logic
  • registry.listSandboxes() provides the default sandbox name

Open questions

• Does openshell gateway start --name nemoclaw work correctly when the gateway container exists but is stopped? Or does it require a destroy/recreate cycle?
• Is the CoreDNS fix needed again after a reboot, or only on first setup?
• Should this be a new nemoclaw reconnect command, or should nemoclaw <name> connect be smarter about detecting and recovering from a stopped gateway?

Suggested implementation

async function reconnect(sandboxName) {
  // 1. Check gateway
  const gwInfo = runCaptureOpenshell(["gateway", "info", "-g", "nemoclaw"], { ignoreError: true });
  if (!gwInfo || !gwInfo.includes("Running")) {
    console.log("  Starting OpenShell gateway...");
    runOpenshell(["gateway", "start", "--name", "nemoclaw"]);
    // wait for health
  }
  // 2. Find sandbox
  const name = sandboxName || registry.listSandboxes().defaultSandbox;
  if (!name) {
    console.error("  No sandbox registered. Run `nemoclaw onboard` first.");
    process.exit(1);
  }
  // 3. Connect
  sandboxConnect(name);
}

Related

• Please add restart commands to documentation #469 — original user request for reboot recovery docs
• PR docs(troubleshooting): explain reconnect flow after host reboot #904 — previous docs-only attempt (closed, PR limit)