Snapshots & persistence

MIOSA sandboxes are persistent by default. A sandbox is the long-lived workspace record; a running VM session is the current compute attached to it.

When a persistent sandbox stops or times out, MIOSA preserves the filesystem and moves the sandbox to paused. The next resume, exec, file operation, terminal session, or preview workflow can start a new session from that saved state.

Lifecycle

State	What it means
`running`	Compute is active. Exec, files, terminal, and previews work.
`paused`	Compute is stopped. Filesystem state is preserved for resume.
`snapshotting`	MIOSA is saving a checkpoint that can be restored or forked.
`destroyed`	Permanent deletion. The sandbox ID and saved state are gone.

Create a persistent sandbox

Persistence is the default. Use a longer timeout for real app-building sessions.

miosa sandbox create 
  --template nextjs 
  --name my-agent-workspace 
  --timeout 1h 
  --wait 
  --json

The sandbox can now be used like a remote development workspace:

miosa sandbox write-file <sandbox-id> /workspace/app/page.jsx ./page.jsx --json
miosa sandbox exec <sandbox-id> --json -- sh -lc "cd /workspace && npm install"
miosa sandbox exec <sandbox-id> --json -- sh -lc "cd /workspace && npm run build"

Stop and resume

Use stop when the user is done for now but may come back later.

miosa sandbox stop <sandbox-id> --json
miosa sandbox resume <sandbox-id> --json

For persistent sandboxes, timeout behaves like stop: compute shuts down, the filesystem is preserved, and billing moves from compute to saved-state storage.

Use destroy only when the workspace should be permanently removed:

miosa sandbox destroy <sandbox-id> --json

Snapshot before risky work

Snapshots are explicit checkpoints. Take one after expensive setup, before major refactors, before migrations, or before letting an agent make broad changes.

miosa sandbox snapshot <sandbox-id> 
  --name "after dependencies installed" 
  --json

miosa sandbox snapshots list <sandbox-id> --json

Create a replacement sandbox from a snapshot when the current workspace has gone bad:

miosa sandbox create 
  --snapshot <snapshot-id> 
  --name my-agent-workspace-restored 
  --timeout 1h 
  --wait 
  --json

Fork a sandbox

Fork creates a new sandbox from the current state so an agent can try another approach without corrupting the original workspace.

miosa sandbox fork <sandbox-id> 
  --name my-agent-workspace-auth-branch 
  --json

Use forks for:

trying two UI designs in parallel
testing a migration without touching the main workspace
giving another teammate or agent the same starting point
preserving a working baseline before a high-risk feature pass

Non-persistent sandboxes

Use non-persistent mode only for disposable jobs where state should be discarded.

miosa sandbox create 
  --template node 
  --name one-off-test 
  --timeout 10m 
  --non-persistent 
  --json

Non-persistent timeout destroys the VM and discards /workspace.

Persistence vs volumes

Sandbox persistence preserves the sandbox root filesystem between sessions. It is best for agent workspaces, dependency installs, generated code, and in-progress artifacts.

Volumes are a separate data-plane primitive for durable mounted storage attached to production runtimes. Use volumes for app data that must survive deployment restarts, not for ordinary sandbox editing state.

Recommended agent flow

Create or reuse a named persistent sandbox.
Write files directly into /workspace.
Run dependency install, tests, builds, and dev servers inside the sandbox.
Expose a preview port and stream logs back to the UI.
Snapshot before destructive changes.
Stop when idle; resume on the next user or agent action.
Publish to standard MIOSA Deploy or Docker Deploy when ready.

Full sandbox lifecycle, templates, files, exec, previews, and publishing.

Write code into /workspace and run commands inside the sandbox.

A worked example for checkpointing and branching experiments.

Publish sandbox artifacts to a workspace Docker host.