Sandbox V2 Lifecycle

Sandbox v2 Lifecycle

Use this skill for vercel-openclaw sandbox lifecycle, restore, stop, reset, hot-spare, worker sandbox, and debug timing work.

Source Of Truth

Official Vercel Sandbox v2 docs are authoritative. Repo docs or agent guidance that assumes v1/manual snapshot restore is stale unless already updated.

Load references only as needed:

• references/vercel-sandbox-v2-persistent.md — persistent sandbox auto-save/resume/name/session model.
• references/vercel-sandbox-v2-sdk.md — SDK calls, resume flags, delete, command behavior, and network policy notes.
• references/vercel-sandbox-v2-snapshots.md — manual Snapshot API semantics.
• references/vercel-openclaw-lifecycle-map.md — repo-specific invariants and owner files.

Core Model

• Main OpenClaw runtime is one named persistent sandbox.
• Persistent stop() auto-saves filesystem state; no manual snapshot() is needed for normal stop.
• Normal wake resumes by name with Sandbox.get({ name, resume: true }) through the repo controller.
• resume defaults false; use resume:false for observation/status reconciliation.
• Commands may auto-resume stopped persistent sandboxes; stop() and update() do not.
• Manual snapshot() is explicit/debug/checkpoint only. It shuts the sandbox down; do not call stop() afterward.
• delete() permanently removes the persistent sandbox and its sessions/snapshots.
• Worker/debug sandboxes are short-lived; pass persistent:false.

Repo Invariants

• Preserve one persistent OpenClaw sandbox, Redis metadata, channel wake/restore, and short-lived workers.
• Keep SDK access behind src/server/sandbox/controller.ts except documented raw SDK debug routes.
• Distinguish host metadata status, SDK status/session, gateway readiness, persistent auto-saved state, and manual Snapshot APIs.
• Do not use manual snapshotId as the normal restore gate.
• Preserve resume:false during snapshotting/stopped observation.
• Keep lifecycle locks and fail-closed firewall behavior.

Workflow

• Read lat.md/sandbox-lifecycle.md, docs/lifecycle-and-restore.md, and relevant references from this skill.
• Inspect src/server/sandbox/lifecycle.ts, controller.ts, restore-attestation.ts, hot-spare.ts, and worker sandbox code.
• Classify whether the change affects persistent resume, manual snapshots, reset/delete, workers, or debug diagnostics.
• Patch the smallest surface that fixes the v2 truth model.
• Add or adjust targeted tests before broad verification.

Verification

Run the narrowest covering test first, then broader gates for lifecycle changes:

node --import tsx --test src/server/sandbox/restore-attestation.test.ts
pnpm run test:lifecycle
pnpm run typecheck
pnpm run lint
lat check

When touching launch verification or preflight, also run pnpm run verify:observability-pass.