Lifecycle states

Sandbox lifecycle is a product-level contract. Backends implement it with different primitives, but the user-facing states should stay explicit so automation can decide when compute is active, when state is sensitive, and when cleanup is still required.

State model

State	What it means	Common next action	Security note
No image	No build artifact exists for the workload yet.	mvmctl build	Build inputs still need policy and secret review before launch.
Built	A launchable artifact exists, but no sandbox is running.	mvmctl up or mvmctl run	Artifact metadata can reveal package, path, and configuration choices.
Starting	The backend is creating the VM, attaching drives, and waiting for readiness.	mvmctl wait or mvmctl boot-report	Admission failures should be reported without leaking secrets.
Running	Guest compute is active and can execute commands, expose ports, write files, and emit logs.	mvmctl exec, mvmctl logs, mvmctl fs, mvmctl down, or snapshot commands	Treat command output, files, logs, ports, and receipts as boundary-crossing data.
Paused	Guest execution is suspended and can be resumed by the backend path that created the pause.	mvmctl resume	Paused memory can contain tokens, browser sessions, plaintext files, and process state.
Cold	Compute is released while recoverable state is retained through a backend snapshot or machine-state file.	mvmctl resume or mvmctl snapshot restore	Cold state is persistence, not a security boundary. Protect it like sensitive data.
Restoring	The backend is loading saved state and re-establishing runtime control.	Wait for readiness, then verify workload health	Restore can fail because of backend, host, image, or policy drift.
Stopped	Guest compute is no longer running, while build artifacts, logs, receipts, volumes, or snapshots may remain.	mvmctl up, mvmctl sandbox gc, or mvmctl cleanup	Stop is not erase. Review retained state before reusing or sharing the host.
Cleaned	Local registry entries and selected generated state have been removed by cleanup commands.	Rebuild from source if needed	Strong erasure depends on filesystem, volume, snapshot, and cache behavior.

Command map

Transition	CLI surface
Source to image	mvmctl build
Image to running sandbox	mvmctl up or mvmctl run
Wait for readiness	mvmctl wait, mvmctl boot-report
Run work	mvmctl exec, mvmctl fs, mvmctl logs, port-forwarding commands
Running to paused or cold	mvmctl pause, mvmctl snapshot save
Paused or cold to running	mvmctl resume, mvmctl snapshot restore
Running to stopped	mvmctl down
Remove retained local state	mvmctl sandbox gc, mvmctl cleanup, snapshot and volume cleanup commands

Backend behavior

Lifecycle names are shared across the product, but the implementation varies:

• Firecracker paths use sealed snapshots for pause and resume where supported.
• macOS virtualization paths use machine-state save and restore where the host platform supports that capability.
• Pool-backed flows may sleep an instance internally, but public docs should still describe the user-facing CLI state rather than provider internals.

SDKs should expose these states directly instead of hiding backend differences. When a backend cannot restore a state, the SDK should return a typed capability or restore error rather than silently falling back to a fresh VM.

Security rules

• Treat snapshots, machine-state files, logs, receipts, copied files, and volumes as sensitive artifacts.
• Do not assume down or cleanup commands securely erase guest memory, disk blocks, host caches, or external copies.
• Require explicit retention decisions for browser sessions, credentials, agent workspaces, and long-running service data.
• Keep restore failures observable without printing secrets from guest state or host configuration.
• Make detach, pause, cold, and restore policies visible in automation so a sandbox cannot quietly outlive its owner or intended TTL.

Related pages

• Sandbox management
• Persistence, pause & resume
• Cold mode
• Snapshots
• Lifecycle matrix