Sandboxes

A Sandbox is a mutable isolated environment for agent-driven development. Your agent writes files into it, executes commands, exposes ports as live preview URLs, and snapshots state for branching or rollback. Sandboxes are persistent by default: when you stop them or their timeout expires, MIOSA preserves the filesystem and moves the session to paused so it can resume later.

What a Sandbox is, concretely

• Isolated compute for code generation, builds, tests, and dev servers
• Configurable CPU, memory, disk, timeout, and environment variables
• /workspace is the editable filesystem root
• Boots from a versioned template (miosa-sandbox by default; see Templates)
• Persistent by default: timeout_sec stops compute and preserves state instead of deleting the workspace
• Use destroy only when the sandbox and its saved state should be permanently removed
• Network-isolated by default; preview URLs open specific ports to the internet

Lifecycle

Activity that resets the idle clock: exec calls, file writes, preview HTTP traffic, terminal stdin. For persistent sandboxes, once timeout_sec elapses the running session stops and the sandbox becomes paused. For explicitly non-persistent sandboxes, timeout destroys the VM and discards the filesystem.

See Snapshots & persistence for the full stop/resume/snapshot/fork flow.

Current production benchmark

On June 9, 2026, MIOSA ran production sandbox benchmarks through the real HTTP API: 100 sandboxes, concurrency 10, template miosa-sandbox, size xs.

Result: 100 / 100 sandboxes completed create -> ready -> exec -> destroy, with 0 capacity rejections.

See Benchmarks for methodology, caveats, and the difference between VM boot time and full command-ready time.

Fast path: create and run

For agents that need a sandbox and immediately run the first command, use the fused run endpoint. It is faster because MIOSA owns the readiness wait on the server and avoids an extra client poll loop plus a second public exec request.

Response shape:

{
  "data": {
    "id": "sbx_a1b2c3d4",
    "state": "running",
    "template_id": "miosa-sandbox",
    "boot_ms": 34,
    "boot_path": "warm"
  },
  "exec": {
    "stdout": "2\n",
    "stderr": "",
    "exit_code": 0
  },
  "timings": {
    "server_wait_and_exec_ms": 512
  }
}

Create with full options

Use full create when you need to provision the sandbox first, write files, start a preview server, attach databases, or keep the ID for a longer session.

The response body contains id, state, template_id, cpu_count, memory_mb, boot_ms, boot_path, and created_at. Save the id; every subsequent call needs it.

Context manager (auto-destroy)

The Python SDK supports with / async with; the sandbox is destroyed on exit even if an exception is raised:

Connect to an existing sandbox

Run a command: exec

exec.run blocks until the process exits and returns stdout, stderr, exit_code, and duration_ms.

Stream stdout/stderr in real time

exec.stream returns an iterator of SSE events. Use this for long commands (builds, test runs, installs) where you want to surface output progressively.

Files: write, read, list, stat

All file paths are absolute. Parent directories are created automatically on write. File content is base64-encoded over the wire.

Filesystem layout

Previews: expose a port

previews.create maps a sandbox port to a public HTTPS URL managed by MIOSA. The URL is live as long as the sandbox is running.

See Previews for visibility controls, custom domains, and embedding.

Snapshots: save and fork state

A snapshot freezes the entire VM state (memory + disk). You can restore the same sandbox to an earlier state, or create a branch by restoring into a new sandbox.

Pause and resume

pause() and resume() give you explicit control over the running ↔ paused transition without destroying state.

Environment variables

Env vars set at create time are injected into the VM at boot and visible to all processes. They are read-only once the sandbox is running; env.list() returns the live set.

Subscribe to sandbox events

The events.stream() endpoint emits lifecycle and activity SSE events for a sandbox, which is useful for monitoring agent runs.

List and filter sandboxes

Sizing reference

Pass size: "medium" (or equivalent cpu_count/memory_mb) for any sandbox that runs npm install, pip install, or a build tool. The default small is sufficient for pure code-gen or exec-only workloads.

Raw resource overrides (still accepted):

Set always_on=True to disable timeout_sec enforcement entirely. Useful for long-lived development environments or hosted IDEs. Set idle_timeout_sec to stop an abandoned persistent session after a period of inactivity. Set persistent=False only for one-off jobs where the filesystem should be discarded on stop or timeout.

Custom templates

Build a custom template when you need a reproducible base image with dependencies pre-installed. This reduces every sandbox cold-start by eliminating the install step.

See Templates for the full BuildSpec reference, available base images, and template versioning.

Production checklist

Before relying on sandboxes in production:

• Set an explicit timeout_sec. Interactive app-building workflows should usually use 1h; short one-shot commands can use less.
• Keep the default persistent=True for agent workspaces so timeout preserves /workspace and dependency installs.
• Set idle_timeout_sec for user-facing dev environments so abandoned sessions stop compute and preserve state.
• Pass idempotency_key on sandboxes.create calls in agent retry loops. The platform deduplicates creates with the same key within a 24-hour window.
• Use templates instead of installing dependencies inside every sandbox. A pnpm install that takes 45 s becomes a 150 ms warm boot.
• Snapshot before destructive operations. Restore is ~200 ms; re-running an install is not.
• Subscribe to sbx.events.stream() to detect unexpected exits and trigger retries.
• Never store long-lived secrets in env; pass them per-exec or use the Secrets API.
• Filter by external_workspace_id in your list calls to avoid scanning your entire tenant’s sandbox set.

Billing notes

Billing accrues from state = "running" until state = "paused" or state = "destroyed".

• Running: billed at the vCPU-second + GiB-second rate for your plan
• Paused: billed at storage rate only (disk GiB-second)
• Destroyed: billing stops immediately

Templates are cached in every region, so picking a built-in template incurs no boot-delay penalty.

See also