Templates

A template is a pre-built Firecracker image with a specific language and framework already installed. Pick the closest match to your stack; you can override install/start commands per-sandbox if needed.

Template catalog

miosa-sandbox

The default general-purpose template. Use it when no other template fits, or when you want a blank slate with common tooling.

Pre-installed: Node.js 20, Python 3.11, Go toolchain, Rust toolchain, git, curl, wget, unzip, common build tools (gcc, make), uv, pnpm, yarn.

Default port: None pre-configured — open any port you choose.

node

Node.js 24 LTS with npm, pnpm, and yarn pre-installed.

Pre-installed: Node.js 24 LTS, npm, pnpm, yarn, git.

Default port: 3000.

Default install command: npm install

Default start command: npm start

nextjs

Next.js 15 with a scaffold pre-installed and pnpm dependencies cached.

Pre-installed: Node.js 24 LTS, pnpm, Next.js 15 scaffold (in /workspace), Tailwind CSS.

Default port: 3000.

Default install command: pnpm install

Default start command: pnpm dev

Production publish gotcha: Next.js SSR deployments require output: "standalone" in next.config.js so the builder can package the server. Static exports (output: "export") work without this setting.

// next.config.js — required for SSR publishing
module.exports = {
  output: 'standalone',
};

react-vite

React 18 + Vite 5 for pure SPA development.

Pre-installed: Node.js 24 LTS, pnpm, React 18, Vite 5, TypeScript.

Default port: 5173.

Default install command: pnpm install

Default start command: pnpm dev --host 0.0.0.0

Production publish gotcha: Vite produces a fully static output (dist/). The builder auto-detects this and serves it from the edge as a Static Release. No output config needed.

svelte

SvelteKit 2 with adapters pre-installed.

Pre-installed: Node.js 24 LTS, pnpm, SvelteKit 2, @sveltejs/adapter-auto, @sveltejs/adapter-node, @sveltejs/adapter-static.

Default port: 5173.

Default install command: pnpm install

Default start command: pnpm dev --host 0.0.0.0

Production publish gotcha: For SSR publishing, set adapter-node in svelte.config.js. For a static site, set adapter-static. The builder detects which adapter is configured and picks the appropriate release type.

python

Python 3.13 with uv, pip, and common ML/data tooling.

Pre-installed: Python 3.13, uv, pip, venv, fastapi, uvicorn, httpx, pydantic, git.

Default port: 8000.

Default install command: uv sync (falls back to pip install -r requirements.txt)

Default start command: uvicorn main:app --host 0.0.0.0 --port 8000

Production publish gotcha: The builder uses a Procfile or the configured start command to determine the entry point. Ensure your main.py / app.py is in /workspace and uvicorn listens on 0.0.0.0, not 127.0.0.1.

go

Go 1.24 with modules enabled.

Pre-installed: Go 1.24, git, common build tools.

Default port: 8080.

Default install command: go mod download

Default start command: go run .

Production publish gotcha: For publishing, the builder runs go build -o app . and sets the start command to ./app. Ensure your main.go reads the port from an environment variable (PORT) so the runtime instance can override it.

rust

Rust 1.85 (stable) with Cargo.

Pre-installed: Rust 1.85 stable, cargo, common build tools.

Default port: 8080.

Default install command: cargo fetch

Default start command: cargo run --release

Production publish gotcha: The builder runs cargo build --release and strips the resulting binary. Bind your listener to 0.0.0.0 and read the port from the PORT environment variable.

static

Plain HTML, CSS, and JavaScript. No build step.

Pre-installed: A static file server (caddy) that serves /workspace on port 8080.

Default port: 8080.

Default install command: (none)

Default start command: caddy file-server --root /workspace --listen :8080

Production publish: The builder detects a static site (no package.json, Cargo.toml, or go.mod) and packages /workspace as a Static Release. Assets are served from the edge — no Runtime Instances required.

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 template API (or the CLI: miosa templates 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.