Persistence, pause, and forks

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

Lifecycle

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.