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. When the work is done you destroy it, pause it, or publish it to a production deployment.

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)
• Auto-destroyed after timeout_sec of wall-clock time (default 300 s; set always_on=True to disable)
• 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. Once timeout_sec elapses with no activity the sandbox transitions directly to destroyed.

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 - 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 auto-destroy after a period of inactivity rather than a fixed wall-clock limit.

Custom templates

Build a custom template when you need a reproducible base image with dependencies pre-installed - 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. The default is 300 s. An agent loop that hangs without one will keep billing until the plan-max (up to 86400 s).
• Set idle_timeout_sec for user-facing dev environments so abandoned sessions clean themselves up.
• 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 = "destroyed" or state = "paused".

• 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 cached on every region - picking a built-in template incurs no boot-delay penalty.

See also