Snapshots, restore, pause, and forks

MIOSA sandboxes are persistent by default. The sandbox record and workspace outlive an individual running session until the sandbox is destroyed.

Sandbox state lifecycle

The sandbox record has five public states. Snapshots and forks are separate resources and operations, not additional sandbox states.

State	Meaning
`provisioning`	The sandbox is being prepared and is not ready for work.
`running`	Compute is active and the sandbox is ready for supported operations.
`paused`	Compute is stopped and the persistent workspace is preserved for resume.
`error`	Provisioning or runtime recovery failed. Inspect the failure reason before destroying or replacing the sandbox.
`destroyed`	The sandbox and saved workspace have been permanently released.

A snapshot is a durable checkpoint resource with its own lifecycle. Creating one does not change the sandbox into a snapshot state. Restore and fork both produce a new sandbox while leaving the source sandbox unchanged.

Operation	Source requirement	Result	Source changes?
Create snapshot	Running sandbox	A snapshot progresses through `creating`, `uploading`, then `ready`, or ends in `failed` or `quarantined`.	No.
Restore snapshot	Ready snapshot	A new sandbox is provisioned from the checkpoint.	No.
Fork sandbox	Running sandbox	MIOSA captures a copy-on-write checkpoint and provisions a new sandbox.	The source is briefly coordinated for capture, then continues running.
Delete snapshot	Existing snapshot	The snapshot becomes `deleted`; sandboxes previously restored from it are unaffected.	No.

Snapshot statuses

Status	Meaning
`creating`	MIOSA is capturing the checkpoint files.
`uploading`	MIOSA is compressing, uploading, and finalizing the checkpoint.
`ready`	The snapshot passed validation and can be restored.
`restoring`	A restore job is using the checkpoint to create a new sandbox.
`failed`	Snapshot creation or restore encountered an unrecoverable error.
`quarantined`	Artifact integrity validation failed, so MIOSA will not restore it.
`deleted`	The snapshot was explicitly deleted or removed by retention policy.

Pause and resume

Pause a running persistent sandbox when work should stop without discarding the workspace. Command and file operations can automatically resume a paused persistent sandbox before dispatch, but an explicit resume is clearer when the application needs to wait for running state.

curl -X POST https://api.miosa.ai/api/v1/sandboxes/$SBX/pause 
  -H "Authorization: Bearer $MIOSA_API_KEY"

curl -X POST https://api.miosa.ai/api/v1/sandboxes/$SBX/resume 
  -H "Authorization: Bearer $MIOSA_API_KEY" 
  -H "Idempotency-Key: resume-session-001"

Pause returns 409 when the sandbox is not running. Resume returns 409 when the sandbox is not paused.

Timeout and persistence

timeout_sec defaults to 3600 and accepts values from 1 through 86400. For persistent sandboxes, timeout policy preserves filesystem state for a later session. idle_timeout_sec: 0 disables idle auto-stop. always_on: true disables timeout and idle-timeout enforcement until an explicit lifecycle action, subject to tenant policy.

Replace the active-session timeout with the extend endpoint:

curl -X POST https://api.miosa.ai/api/v1/sandboxes/$SBX/extend 
  -H "Authorization: Bearer $MIOSA_API_KEY" 
  -H "Content-Type: application/json" 
  -d '{"timeout_sec": 7200}'

The value replaces the timeout rather than adding time to it. Omitting the request body preserves the current timeout.

Fork from a snapshot

Fork creates a new sandbox from a copy-on-write snapshot of a running sandbox. The source is unchanged, and the response is the newly created sandbox. Use an idempotency key when retrying a fork request.

curl -X POST https://api.miosa.ai/api/v1/sandboxes/$SBX/fork 
  -H "Authorization: Bearer $MIOSA_API_KEY" 
  -H "Content-Type: application/json" 
  -H "Idempotency-Key: fork-auth-experiment-001" 
  -d '{"timeout_sec": 3600}'

The optional body accepts timeout_sec and template_id for the new sandbox.

miosa sandbox snapshot <sandbox-id> --name "before migration" --json
miosa sandbox snapshots list <sandbox-id> --json
miosa sandbox snapshots get <sandbox-id> <snapshot-id> --json
miosa sandbox create --snapshot <snapshot-id> --name restored-copy --wait --json
miosa sandbox snapshots delete <sandbox-id> <snapshot-id> --json

Managed and BYOC behavior

The lifecycle contract is the same on MIOSA-managed capacity and supported BYOC capacity. Applications send sandbox parameters such as template, size, and timeout. Placement configuration remains outside the sandbox request, and sandbox responses do not expose internal host or provider fields.

Resource contracts, create parameters, usage, files, exec, and previews.

Deployment model, private-preview status, and the shared sandbox contract.