feat(sandbox): add stop and start container lifecycle commands

[Dongni-Yang]

Summary

NemoClaw sandboxes could only be destroyed, never temporarily stopped: the action surface offered connect/exec/rebuild/destroy/recover, and the deprecated global nemoclaw stop controls the tunnel, not the sandbox container. This PR adds nemoclaw <name> stop and nemoclaw <name> start, which stop and restart the sandbox's Docker container while preserving the workspace volume, registry entry, OpenShell sandbox record, and credentials — so users can free CPU/memory/GPU without losing their workspace.

Related Issue

Fixes #6026

Changes

• New sandbox:stop action (src/lib/actions/sandbox/stop.ts): gracefully stops OpenClaw-managed in-sandbox channels via the existing stopSandboxChannels, then docker stops every labeled container that is not at rest. Crash-looping Restarting (N) containers are stopped too (docker stop is what disarms an armed restart policy) instead of being misreported as already stopped. Idempotent on already-stopped sandboxes. The shared host gateway, tunnel, and NIM container are gateway-scoped and deliberately untouched.
• New sandbox:start action (src/lib/actions/sandbox/start.ts): reuses the [DGX Spark][Sandbox] post-reboot first 'nemoclaw <name> status' destroys sandbox via "Removed stale local registry entry" #4423 docker-driver recovery module (stopped original, gpu-backup-sibling rename), adds a docker unpause branch for paused containers (docker ps reports them as Up … (Paused), so the recovery classifier alone would no-op while docker start fails), then delegates to the recover body (connectSandbox probe) so the gateway and host forwards return exactly as recover restores them.
• Both actions preflight with the existing isDockerRuntimeDown/printDockerRuntimeDownGuidance ([Ubuntu 24.04][CLI] Docker restart leaves sandbox stuck in Provisioning and connect times out #4428) so a Docker daemon outage is reported as a host runtime problem instead of "no container found — run rebuild". Both gate on the direct-container drivers the privileged-exec path already allows (null/docker/vm) and refuse others.
• New dockerUnpause primitive in src/lib/adapters/docker/container.ts, mirroring dockerStop/dockerStart (consumer: the paused-container branch in startSandbox; protected by src/lib/actions/sandbox/start.test.ts).
• Thin oclif adapters src/commands/sandbox/stop.ts / start.ts (recover.ts pattern); routing, Valid actions: text, and shell completion derive automatically from the registered command IDs.
• Display entries in public-display-defaults.ts next to recover; package-contract counts updated (58→60 commands, 33→35 action tokens).
• Deprecated global stop/start deprecation messages now point at the sandbox-scoped commands (the issue's Actual Result shows this exact confusion).
• Docs: docs/reference/commands.mdx sections for both commands (dump-commands parity gate), and a "Stop and Start a Sandbox" section in docs/manage-sandboxes/lifecycle.mdx.

Type of Change

• Code change (feature, bug fix, or refactor)
• Code change with doc updates
• 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:
• Non-success, skipped, or missing CI check accepted by maintainer — check name, approval link, and follow-up issue:

Verification

• PR description includes the DCO sign-off declaration 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 --project cli src/lib/actions/sandbox/stop.test.ts src/lib/actions/sandbox/start.test.ts src/commands/sandbox/stop.test.ts src/commands/sandbox/start.test.ts src/lib/adapters/docker/index.test.ts → 52 passed; npm run build:cli && npx vitest run --project package-contract → 302 passed; npm run typecheck:cli clean
• 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)

---

Signed-off-by: Dongni Yang dongniy@nvidia.com

Summary by CodeRabbit

• New Features

  • Added advanced sandbox commands: nemoclaw <sandbox-name> stop and nemoclaw <sandbox-name> start.
  • Start/stop now preserve workspace data/config and verify gateway/host forwarding health; handles paused and already-running containers.
  • Updated CLI command display to include the new sandbox actions.

• Documentation

  • Added a “Stop and Start a Sandbox” lifecycle section and expanded the CLI command reference.
  • Enhanced deprecation messaging for legacy start/stop guidance.

• Bug Fixes

  • Improved behavior and messaging around Docker/runtime outages and missing containers (with rebuild guidance).

• Tests

  • Added command and action test coverage for stop/start flows.

[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: 468132a7-4fcd-4299-9e71-1d79fa9372e2

📥 Commits

Reviewing files that changed from the base of the PR and between f55179e and c9d01b1.

📒 Files selected for processing (3)

• docs/reference/commands.mdx
• src/lib/actions/sandbox/stop.test.ts
• src/lib/actions/sandbox/stop.ts

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

• src/lib/actions/sandbox/stop.ts
• docs/reference/commands.mdx

---

📝 Walkthrough

Walkthrough

Adds nemoclaw <name> stop and start commands for sandbox container lifecycle control, including Docker orchestration, gateway recovery, CLI registration, tests, documentation, and legacy command guidance.

Changes

Sandbox lifecycle controls

Layer / File(s)	Summary
Sandbox stop orchestration src/lib/actions/sandbox/stop.ts, src/lib/actions/sandbox/stop.test.ts	Adds gated sandbox stopping with graceful channel shutdown, container discovery, Docker stop handling, preserved registry state, and coverage for success and failure paths.
Sandbox start and recovery src/lib/actions/sandbox/start.ts, src/lib/actions/sandbox/start.test.ts, src/lib/adapters/docker/container.ts	Adds paused-container unpause, recovery-based startup, Docker runtime checks, and gateway/forward probing with lifecycle branch tests.
CLI command integration src/commands/sandbox/start.ts, src/commands/sandbox/stop.ts, src/commands/sandbox/*.test.ts, src/lib/cli/public-display-defaults.ts, test/package-contract/cli/command-registry.test.ts	Registers the new commands, propagates action exit results, adds display ordering, and updates command registry contracts.
Lifecycle documentation and legacy guidance docs/manage-sandboxes/lifecycle.mdx, docs/reference/commands.mdx, src/commands/start.ts, src/commands/stop.ts	Documents stop/start behavior and updates legacy command messages with container lifecycle instructions.

Estimated code review effort: 4 (Complex) | ~45 minutes

Possibly related PRs

• NVIDIA/NemoClaw#4605: Introduces Docker-daemon outage detection and guidance used by sandbox lifecycle gating.

Suggested labels: area: cli, area: sandbox

Suggested reviewers: ericksoa, cv, prekshivyas

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 35.29% 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 summarizes the main change: adding sandbox stop/start lifecycle commands.
Linked Issues check	✅ Passed	The PR implements nemoclaw <name> stop and start for sandbox containers, preserving workspace state and restoring stopped sandboxes as requested in #6026.
Out of Scope Changes check	✅ Passed	The docs, tests, CLI registration, and deprecation updates all directly support the new sandbox lifecycle commands.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/6026-sandbox-stop-start

---

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

[github-code-quality]

Code Coverage Overview

Languages: TypeScript

TypeScript / code-coverage/plugin

The overall coverage remains at 96%, unchanged from the main branch.

TypeScript / code-coverage/cli

The overall coverage in the fix/6026-sandbox-sto... branch remains at 79%, unchanged from the main branch.

Show a code coverage summary of the most impacted files.

File	main 3de1de6	fix/6026-sandbox-sto... c9d01b1	+/-
src/lib/core/pr...mpt-activity.ts	92%	67%	-25%
src/lib/state/m...-acquisition.ts	77%	81%	+4%
src/lib/inference/local.ts	71%	77%	+6%
src/lib/onboard...reachability.ts	63%	72%	+9%
src/lib/actions...ge-preflight.ts	74%	89%	+15%
src/lib/inferen...del-registry.ts	66%	100%	+34%
src/lib/actions...andbox/start.ts	0%	89%	+89%
src/lib/actions...sandbox/stop.ts	0%	98%	+98%
src/commands/sandbox/start.ts	0%	100%	+100%
src/commands/sandbox/stop.ts	0%	100%	+100%

---

_{Updated July 13, 2026 08:39 UTC
Code Coverage is in Public Preview. Learn more and provide us with your feedback.}

[github-actions]

🌿 Preview your docs: https://nvidia-preview-pr-6748.docs.buildwithfern.com/nemoclaw

[github-actions]

E2E Advisor Recommendation

Required E2E: onboard-repair, onboard-resume, sandbox-operations
Optional E2E: None

Dispatch hint: onboard-repair,onboard-resume,sandbox-operations

Workflow run

Full advisor summary

E2E Recommendation Advisor

Base: origin/main
Head: HEAD
Confidence: high

Required E2E

• onboard-repair: Required by the deterministic lifecycle-state risk plan: lifecycle mutations must converge cleanly after failure and repair without stale resources or state.
• onboard-resume: Required by the deterministic lifecycle-state risk plan: persisted and live sandbox state must remain resumable and converge across recovery paths.
• sandbox-operations: The PR adds real Docker-backed sandbox stop/start behavior and gateway/forward recovery; this live lifecycle job validates onboarded sandbox, registry, gateway, and multi-sandbox operational boundaries.

Optional E2E

• None.

New E2E recommendations

• sandbox-lifecycle (high): The current sandbox-operations live suite validates onboarding, recovery, multi-sandbox isolation, and destroy, but does not invoke the new stop/start commands. Unit tests cannot prove that Docker stop/unpause/restart, retained registry and workspace state, and post-start gateway/forward repair work together.
  • Suggested test: Extend the existing sandbox-operations live test to stop an onboarded sandbox, verify status reports the stopped-container failure and the registry/workspace remain intact, start it again, verify gateway and host forwards recover, and confirm the assistant can complete an agent request. Include paused-container start and a second sandbox remaining available while its peer is stopped.

Dispatch hint

• Workflow: .github/workflows/e2e.yaml
• jobs input: onboard-repair,onboard-resume,sandbox-operations

[github-actions]

PR Review Advisor — No blocking findings

Merge posture: No blocking advisor findings
Primary next action: Review the warnings below.
Findings: 0 required · 1 warning · 0 optional suggestions
Since last review: 1 prior item resolved · 1 still applies · 0 new items found

1 warning · 0 optional suggestions

Warnings

These merit maintainer attention but do not block by themselves.

PRA-1 Warning — Cover retry convergence after a post-start probe failure

• Location: src/lib/actions/sandbox/start.test.ts:216
• Category: tests
• Problem: The probe-rejection test ends after the initial failure. startSandbox has already started or unpaused the container before awaiting probeSandbox, so checked-in coverage does not establish that a retry discovers the resulting running container, avoids another lifecycle mutation, and probes again successfully.
• Impact: A regression in retry classification can make recovery after a transient gateway/forward probe failure non-convergent, issuing repeated start or unpause operations rather than converging on the existing running container.
• Recommendation: Add a stateful action-level retry test: first discover a stopped container, start it and reject the probe; then discover it as running and resolve the second probe, asserting no second recovery-start or unpause call.
• Verification: Inspect src/lib/actions/sandbox/start.ts:87-118: lifecycle mutation precedes the awaited probe; inspect the rejection test at src/lib/actions/sandbox/start.test.ts:216-223, which performs no retry.
• Test coverage: A Vitest action test that invokes startSandbox twice against stateful discovery, rejects the first post-start probe and resolves the second, then asserts two probes and exactly one lifecycle mutation.
• Evidence: src/lib/actions/sandbox/start.ts:87-118 performs docker unpause or recoverDockerDriverSandbox before awaiting probeSandbox. src/lib/actions/sandbox/start.test.ts:216-223 asserts only that the first probe rejection propagates. The tier-2 lifecycle-state risk plan requires partial failure and retry to converge without ghost resources or stale ports.

Workflow run details

This is an automated review. Required findings need action before merge. Warnings and optional suggestions do not require a response or follow-up. A human maintainer makes the final merge decision.

[coderabbitai]

Actionable comments posted: 2

🧹 Nitpick comments (2)

src/lib/actions/sandbox/stop.ts (1)

12-17: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Consider importing the adapter's real Docker types instead of a loose local shape.

DockerOpResult/DockerStopFn re-declare a subset of dockerStop's actual signature (DockerRunOptions/DockerRunResult per src/lib/adapters/docker/container.ts). Since the lazy-require pattern only defers the runtime import, a type-only import (import type { DockerRunOptions, DockerRunResult } from "../../adapters/docker") costs nothing at runtime and keeps this file in sync if the adapter's option/result shape changes.

♻️ Proposed refactor

-type DockerOpResult = { status?: number | null };
-type DockerStopFn = (name: string, opts?: Record<string, unknown>) => DockerOpResult;
+import type { DockerRunOptions, DockerRunResult } from "../../adapters/docker/container";
+type DockerStopFn = (name: string, opts?: DockerRunOptions) => DockerRunResult;

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/lib/actions/sandbox/stop.ts` around lines 12 - 17, Replace the local
DockerOpResult and DockerStopFn shapes in loadDockerStop with type-only imports
of DockerRunOptions and DockerRunResult from the Docker adapter, and type the
lazy-loaded dockerStop reference using that real adapter signature while
preserving deferred runtime loading.

src/commands/sandbox/start.test.ts (1)

20-22: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Restore the console.error spy in afterEach, not inline.

If an assertion above error.mockRestore() throws, the spy leaks into later tests in this file.

♻️ Proposed fix

+  let errorSpy: ReturnType<typeof vi.spyOn> | undefined;
+
   afterEach(() => {
     process.exitCode = 0;
+    errorSpy?.mockRestore();
+    errorSpy = undefined;
   });

   it("propagates the action's failure exit code (`#6026`)", async () => {
-    const error = vi.spyOn(console, "error").mockImplementation(() => {});
+    errorSpy = vi.spyOn(console, "error").mockImplementation(() => {});
     startSandbox.mockResolvedValue({ exitCode: 1, message: "  boom" });

     await SandboxStartCommand.run(["alpha"], rootDir);

     expect(process.exitCode).toBe(1);
-    expect(error).toHaveBeenCalledWith("  boom");
-    error.mockRestore();
+    expect(errorSpy).toHaveBeenCalledWith("  boom");
   });

Also applies to: 31-40

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/commands/sandbox/start.test.ts` around lines 20 - 22, Move restoration of
the console.error spy into the existing afterEach cleanup alongside resetting
process.exitCode. Remove inline error.mockRestore() calls from the affected
tests so cleanup still runs when assertions throw and the spy is restored for
subsequent tests.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/reference/commands.mdx`:
- Line 1142: Update the stopSandbox documentation sentence to state that the
command supports both Docker-driver and vm-driver sandboxes, while retaining the
existing behavior description for unreachable Docker daemons.

In `@src/lib/actions/sandbox/stop.ts`:
- Around line 159-173: Update the dockerStop loop in the sandbox stop flow to
attempt every container in stoppable, rather than returning on the first
non-zero result. Collect each failed container and aggregate their
names/statuses into the final failure message, while preserving a successful
exit when all stops succeed and the existing never-remove behavior.

---

Nitpick comments:
In `@src/commands/sandbox/start.test.ts`:
- Around line 20-22: Move restoration of the console.error spy into the existing
afterEach cleanup alongside resetting process.exitCode. Remove inline
error.mockRestore() calls from the affected tests so cleanup still runs when
assertions throw and the spy is restored for subsequent tests.

In `@src/lib/actions/sandbox/stop.ts`:
- Around line 12-17: Replace the local DockerOpResult and DockerStopFn shapes in
loadDockerStop with type-only imports of DockerRunOptions and DockerRunResult
from the Docker adapter, and type the lazy-loaded dockerStop reference using
that real adapter signature while preserving deferred runtime loading.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 0e2bc15b-ac69-4ebe-ae80-ac2ce55c37bd

📥 Commits

Reviewing files that changed from the base of the PR and between deed1aa and f55179e.

📒 Files selected for processing (15)

• docs/manage-sandboxes/lifecycle.mdx
• docs/reference/commands.mdx
• src/commands/sandbox/start.test.ts
• src/commands/sandbox/start.ts
• src/commands/sandbox/stop.test.ts
• src/commands/sandbox/stop.ts
• src/commands/start.ts
• src/commands/stop.ts
• src/lib/actions/sandbox/start.test.ts
• src/lib/actions/sandbox/start.ts
• src/lib/actions/sandbox/stop.test.ts
• src/lib/actions/sandbox/stop.ts
• src/lib/adapters/docker/container.ts
• src/lib/cli/public-display-defaults.ts
• test/package-contract/cli/command-registry.test.ts

[cjagwani]

Reviewed exact head c9d01b1.

All required checks are green, contributor compliance passes, the trusted PR Review Advisor recommends merge_as_is, and CodeRabbit has no unresolved major or critical findings.

I also completed the nine-category security review. No vulnerability, credential leak, injection path, SSRF, authorization bypass, dependency risk, policy weakening, or unsafe destructive-state path was found. The advisor's retry-convergence coverage request is a non-blocking test hardening item: after a successful lifecycle mutation, retry discovery reaches the canonical running-container no-op path and probes again. Two additional low-risk follow-ups are worth tracking separately: prefer canonical-original selection before unpausing if a host already contains inconsistent original/backup siblings, and add a live stop/start persistence/isolation scenario.