Templates

A template is content staged inside the sandbox at create time: files, a scaffold, extra packages, and the command that starts your app. A template is never a separate image.

Every sandbox boots the same main image, which already has Node, Python, Docker Engine 29.9 with docker compose and docker buildx, a live browser with CDP on a virtual display, and the code interpreter inside.

New sandbox

Create a sandbox with no template for code, commands, and artifacts. Use template_id when you want a scaffold staged inside the same image.

Start from a template

Pass template_id to stage a scaffold inside the sandbox image and start it. The template provisions the files, the packages, and the command that runs your app; it is not a separate image.

With auto_start, MIOSA starts the template once the sandbox reaches running and the response carries the preview URL. Leave it false when you want to write your own files into /workspace first, then call Start a template app.

Next.js

Port 3000. Next.js SSR deployments need output: "standalone" in next.config.js so the builder can package the server. Static exports (output: "export") work without it.

Or do it by hand against a sandbox you created without auto_start:

curl -X POST https://api.miosa.ai/api/v1/sandboxes/$SANDBOX_ID/template/start \
  -H "Authorization: Bearer $MIOSA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "install_command": "npm install",
    "start_command": "npm run dev -- --hostname 0.0.0.0 --port 3000",
    "port": 3000
  }'

FastAPI

Port 8000. Or do it by hand:

curl -X POST https://api.miosa.ai/api/v1/sandboxes/$SANDBOX_ID/template/start \
  -H "Authorization: Bearer $MIOSA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "install_command": "pip install -r requirements.txt",
    "start_command": "uvicorn main:app --host 0.0.0.0 --port 8000",
    "port": 8000
  }'

Static HTML

Port 8000. Plain HTML, CSS, and JavaScript, with no build step. Or do it by hand:

curl -X POST https://api.miosa.ai/api/v1/sandboxes/$SANDBOX_ID/template/start \
  -H "Authorization: Bearer $MIOSA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "start_command": "python -m http.server 8000 --bind 0.0.0.0",
    "port": 8000
  }'

The builder detects a static site (no package.json, Cargo.toml, or go.mod) and packages /workspace as a Static Release, so assets are served from the edge with no Runtime Instances.

New desktop

A durable Linux desktop (Xfce and Firefox) with screenshot, click, type, and streaming, plus human takeover. It is a Computer with template_type: "miosa-desktop", not a sandbox template.

See Computers for the desktop surface, and Embed a live desktop to put it in your product.

Custom templates

When the built-in catalog does not fit - proprietary toolchains, specific CUDA/GPU stacks, pre-loaded datasets - you can build and register your own template.

1. Write a Dockerfile for your image.
2. Build it using the custom sandbox template API (or the CLI: miosa template build).
3. Verify the image boots correctly.
4. Register the slug so it is selectable in template_id.

See the Custom Templates API Reference for the full endpoint spec, including image upload, smoke-test hooks, and versioning.

BuildSpec primer

A BuildSpec is an optional JSON document you attach to a sandbox or Deployment to override the default install and start commands. It is the escape hatch for any template when defaults are not quite right:

{
  "install": "pnpm install --frozen-lockfile",
  "build": "pnpm build",
  "start": "node .next/standalone/server.js",
  "env": {
    "NODE_ENV": "production",
    "PORT": "3000"
  }
}

Pass a BuildSpec at sandbox creation time or at publish time. Build-time commands (install, build) run inside the Builder; the start command determines how Runtime Instances are launched. Environment variables set here are merged with any variables already on the Deployment.