Sandboxes
A Sandbox is MIOSA’s fast code execution environment. Your agent writes files into it, executes commands, exposes ports as live preview URLs, and snapshots state for branching or rollback. Use it for build loops, tests, scripts, package installs, code generation, preview servers, and short-lived automation.
Sandboxes are persistent by default, which means they survive a stop.
When you stop one or its timeout expires, MIOSA preserves the disk and moves the sandbox to stopped so it can resume later.
Running processes do not survive a stop.
Persistent does not mean the sandbox survives the loss of its host; see Sandbox lifecycle.
SOMA does not support persistence yet.
Destroy only when the saved state should be removed.
1. Create a sandbox
2. Run a command
3. Write a file and open a preview
Open the preview URL MIOSA returns. Only the port you exposed is reachable, and only through the MIOSA proxy.
Image, template, and runtime
Three different things decide what a sandbox boots with, and they are not the same choice.
| What it is | Where you set it | |
|---|---|---|
| Image | The one main image, with Node, Python, Docker Engine 29.9 with Compose and Buildx, a live browser with CDP, and the code interpreter already inside. | Nothing to choose: every sandbox boots it. |
| Template | Optional content staged inside that image at create time: files, a scaffold, packages, and the start command. | template_id, for example nextjs, static-html, or a custom template. |
| Runtime | Which virtual machine monitor runs the sandbox. | runtime: firecracker (the default), soma, or auto. |
A template is never a separate image.
An older image id passed as template_id still works and boots the main image; see the Sandbox Templates API.
See Templates for the app starters, and Choosing a runtime for the runtime option.
Pick what you need
| Need | Product | Result |
|---|---|---|
| Run commands, edit files, install packages, test code | Sandbox | Isolated runtime with exec, files, snapshots, and preview URLs |
| Use a browser login, desktop app, screenshots, mouse, keyboard | Computer | Durable GUI machine with streaming and desktop control |
| Publish a 24/7 app for users | App Engine | Always-on deployment URL with custom domain support |
Sandboxes are excellent for building and previewing. They are not the final production hosting layer. When a preview becomes a user-facing app, publish it through App Engine so it gets the right routing, domains, lifecycle, and billing behavior.
Next
Fused run, full create, context managers, and connecting to an existing sandbox.
The state machine, what each state means, and how to pause and resume.
Named resource contracts, billing notes, and the opt-in runner fast path.
Default TTL, extending it, and how usage is measured.
Subscribe to lifecycle and activity events over SSE.
The defaults to set before relying on sandboxes in production.
Set and read env vars at create time, and where secrets should live instead.
What sandboxes are for, what one is, and the core capabilities.
Related
Full filesystem and process API: recursive operations, watch, detached jobs.
Live HTTPS URLs proxied to a sandbox port with share tokens and visibility controls.
Built-in images and custom BuildSpec reference.
Pause, resume, fork, and the current public snapshot boundary.