Fork a sandbox safely

Fork creates a new sandbox from a copy-on-write snapshot of a running source sandbox. The source remains unchanged, and the fork receives its own ID, lifecycle, and timeout.

Use this pattern

known-good running source
  |-- fork -> experiment A -> compare -> destroy or keep
  |-- fork -> experiment B -> compare -> destroy or keep
  `-- fork -> recovery retry -> verify

Use forks for parallel agent strategies, risky dependency upgrades, migrations, UI variants, and reproducible retries.

Create the source

The default small contract is 2 vCPU, 4096 MiB RAM, and 10240 MiB disk.

curl -X POST https://api.miosa.ai/api/v1/sandboxes 
  -H "Authorization: Bearer $MIOSA_API_KEY" 
  -H "Content-Type: application/json" 
  -H "Idempotency-Key: baseline-create-001" 
  -d '{
    "template_id":"miosa-sandbox",
    "size":"small",
    "timeout_sec":3600,
    "persistent":true
  }'

Prepare and verify the source before branching. Keep it running while creating forks.

Fork an experiment

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: experiment-a-001" 
  -d '{"timeout_sec":3600}'

The optional body accepts timeout_sec and template_id for the new sandbox. Use a different idempotency key for each intended branch. Retry the same branch request with the same key.

Compare and clean up

Run each experiment in its returned sandbox and collect the outcome. Destroy branches that are no longer needed. Pause the source when it should remain available for later work without active execution.

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

curl -X DELETE https://api.miosa.ai/api/v1/sandboxes/$BRANCH 
  -H "Authorization: Bearer $MIOSA_API_KEY"

Failure recovery

If a branch is corrupted, leave the source unchanged, destroy the failed branch, and fork the source again with a new idempotency key. If the source itself must change, first fork it and make the change in the new sandbox.