// Sandbox lifecycle debugging for vercel-openclaw: create, resume, stop, snapshotting, reset, stale-running reconciliation, persistent Sandbox v2 behavior, hot spares, and lifecycle locks. Use when sandbox state transitions, status polling, stop/resume, reset, or lifecycle recovery is wrong.
Vercel Sandbox v2 lifecycle expertise for vercel-openclaw: named persistent OpenClaw sandbox create/resume/stop/delete, persistent auto-save truth, manual snapshot diagnostics, short-lived worker sandboxes, hot spares, and SDK v2 semantics.
Admin UI and operator surface debugging for vercel-openclaw: command shell design, admin actions, request core, status panels, launch verification UI, channel readiness UI, and local read-only production-data workflows. Use when the root admin UI, controls, visual state, or operator copy is wrong.
Auth and store debugging for vercel-openclaw: admin-secret mode, Sign in with Vercel, session cookies, CSRF, LOCAL_READ_ONLY, Redis vs memory store, keyspace namespacing, and metadata shape migrations. Use when login, route authorization, Redis persistence, or metadata state is suspect.
Cron and watchdog debugging for vercel-openclaw: Vercel Cron auth, persisted OpenClaw jobs, cron wake keys, token refresh, restore oracle, hot spare, and watchdog reports. Use when scheduled OpenClaw jobs fail to wake or run, watchdog status is wrong, cron persistence is suspect, or /api/cron/watchdog behavior changes.
Firewall and Vercel AI Gateway debugging for vercel-openclaw: network policy allowlists, OIDC token refresh, AI Gateway transform rules, firewall learning/enforcement, and sandbox.update networkPolicy calls. Use when model calls, egress, token refresh, or firewall policy application fails.
Gateway and proxy debugging for vercel-openclaw: /gateway routing, HTML injection, WebSocket rewrite, gateway-token handoff, waiting page, status heartbeat, sandbox port URL cache, and proxy auth. Use when the OpenClaw UI, WebSockets, gateway proxying, or waiting-page flow breaks.
| name | sandbox-lifecycle-debug |
| description | Sandbox lifecycle debugging for vercel-openclaw: create, resume, stop, snapshotting, reset, stale-running reconciliation, persistent Sandbox v2 behavior, hot spares, and lifecycle locks. Use when sandbox state transitions, status polling, stop/resume, reset, or lifecycle recovery is wrong. |
Use this skill when the sandbox state machine is the primary suspect.
For Sandbox v2 truth-model work, also load sandbox-v2-lifecycle. Official Vercel Sandbox v2 docs override older repo guidance that treats manual snapshots as the normal restore source.
Read lat.md/sandbox-lifecycle.md sections Status State Machine, Triggers -- What Causes State Transitions, and the specific trigger involved. Run lat locate "Sandbox Lifecycle" or lat search "sandbox lifecycle <symptom>" when unsure.
Collect before edits:
GET /api/status and any UI state that triggered the action.GET /api/admin/sandbox-diag.GET /api/admin/logs filtered for sandbox., gateway., watchdog., proxy..git rev-parse HEAD, remote git ls-remote origin main, and live deployment proof.Report these separately:
SingleMeta.statusDo not use running as shorthand for gateway-ready or user-ready.
/api/admin/ensure -> ensureSandboxRunning() / ensureSandboxReady().ensureSandboxRunning() -> token refresh -> touchRunningSandbox() -> proxy.stopSandbox() -> cleanup -> cron persistence -> sandbox.stop({ blocking: false }) -> snapshotting host metadata while v2 persists state.GET /api/status -> stale running or snapshotting reconciliation.resetSandbox() destroys active sandbox and snapshots, clears cron and token metadata.snapshotId.resume:false.snapshot() is explicit/debug/checkpoint only and shuts the sandbox down.persistent:false.src/server/sandbox/lifecycle.ts, src/server/sandbox/controller.ts.src/app/api/admin/{ensure,stop,snapshot,reset,status}/** and src/app/api/status/route.ts.src/server/sandbox/**.test.ts and src/test-utils/harness.lat.md/sandbox-lifecycle.md, docs/lifecycle-and-restore.md.Use the narrowest command that covers the path, then run the repo verifier when the change has broad lifecycle impact:
node scripts/verify.mjs --steps=test,typecheck
lat check
For live lifecycle incidents, include before/after /api/status, /api/admin/sandbox-diag, and relevant log events.