Sandbox Templates API
Sandbox templates are pre-built images with toolchains, dependencies, and configuration baked in. Launching from a template is faster than installing packages at runtime and ensures reproducible environments.
Every sandbox boots the same main image. A template is content staged inside that image at create time, never a separate image. See the Templates guide.
Endpoints
| Method | Path | Description |
|---|---|---|
GET | /api/v1/sandbox-templates | List the templates available to you |
GET | /api/v1/sandbox-templates/{id} | Get a specific template |
POST | /api/v1/sandboxes | Create a sandbox from a template (via template_id) |
List templates
GET /api/v1/sandbox-templates
Returns the built-in catalog plus any custom templates your workspace has built, as a JSON array.
Each row carries the template slug, its source (builtin or workspace), and the registry status.
Alias ids are left out by default. Pass include_aliases=true to include them; each alias is nested on the row it resolves to, under aliases.
curl "https://api.miosa.ai/api/v1/sandbox-templates?include_aliases=true" \
-H "Authorization: Bearer msk_u_..."Listed templates
Five templates are listed, and all five run the one image:
template_id | Kind | What it is |
|---|---|---|
miosa-sandbox | image | The default sandbox. Everything inside, and what you get when you omit template_id. |
nextjs | starter | Stages a Next.js app in the sandbox and starts it on port 3000. |
nextjs-postgres | starter | A Next.js app with Postgres client tooling on port 3000; bind DATABASE_URL. |
static-html | starter | Static HTML, CSS, and JavaScript served from /workspace on port 8000. |
fastapi-auth | starter | A FastAPI starter with signup, login, me, and dashboard routes, on port 8000. Its health check does not work yet. |
The four starter templates add only content inside the image: the scaffold, the install command, and the start command.
Templates your workspace builds are returned with kind custom. miosa-desktop is a separate Computer product, not a sandbox template; see Computers.
Aliases
Alias ids are never listed, and still work as template_id.
These resolve to miosa-sandbox, the plain image:
miosa-sandbox-prod-1, miosa-sandbox-docker, agent-browser, instant-code, bookworm, debian-12, docker, sandbox-docker, browser-agent, code, instant, instant-node, node-20, postgres-15, postgres-16, ubuntu-22.04, ubuntu-24.04.
These resolve to a starter, which stays listed:
static to static-html; next-postgres and fullstack-next-postgres to nextjs-postgres; python-auth and fastapi-auth-starter to fastapi-auth.
Create a sandbox from a template
POST /api/v1/sandboxes
{
"template_id": "nextjs",
"size": "small"
}Omit template_id for a sandbox with nothing staged, or pass a content template to stage a scaffold inside the same image.
For a desktop, create a Computer with template_type: "miosa-desktop"; see Computers.
See the Sandboxes API for the full creation reference.
Errors
| Status | Code | Cause |
|---|---|---|
| 404 | not_found | Template ID does not exist |