> ## Documentation Index > Fetch the complete documentation index at: https://docs.superserve.ai/llms.txt > Use this file to discover all available pages before exploring further. # Create a template and kick off the first build > Creates a template and queues the first build. The response includes both the template id and the build id, so clients can immediately poll `GET /templates/{id}` for overall status or subscribe to `GET /templates/{id}/builds/{build_id}/logs` for live output. Template starts in status `building`. Poll until it reaches `ready` before creating sandboxes from it. On failure the status becomes `failed` and `error_message` is populated. To rebuild an existing template (e.g. after a failure or when the base image updates), use `POST /templates/{id}/builds`. ## OpenAPI ````yaml https://raw.githubusercontent.com/superserve-ai/sandbox/refs/heads/main/api/openapi.yaml post /templates openapi: 3.1.0 info: title: Superserve API version: 0.1.0 description: > Superserve provides sandbox infrastructure to run AI agents in the cloud. Powered by Firecracker MicroVMs. ## Sandbox lifecycle ``` active <--> paused --> deleted ``` A sandbox is `active` when running and `paused` after being paused. Resuming a paused sandbox returns it to `active`. Deleting releases all resources. | Endpoint | What it does | |----------|-------------| | `POST /sandboxes` | Create a new sandbox (optionally `from_template`) | | `PATCH /sandboxes/:id` | Partially update a running sandbox (e.g. network rules) | | `POST /sandboxes/:id/pause` | Snapshot full state, suspend the VM | | `POST /sandboxes/:id/resume` | Restore from snapshot, continue where it left off | | `DELETE /sandboxes/:id` | Delete sandbox and all resources | ## Sandbox environment By default sandboxes boot from the curated `superserve/base` template (Ubuntu 24.04, 1 vCPU, 1 GB RAM, 4 GB disk, with Python 3.12, Node.js 22, npm, git, curl, and build-essential pre-installed). Callers can override with any template name (e.g. `superserve/python-3.11`, `superserve/node-22`) or a team-owned template UUID via the `from_template` field on `POST /sandboxes`. ## Files and commands `/files`, `/exec`, and `/exec/stream` run against a single sandbox and use its `X-Access-Token` (returned by create, resume, and activate), not the team API key. Two host forms reach them: - `https://sandbox.superserve.ai/...` with `X-Superserve-Sandbox-Id: `. - `https://boxd-{sandbox_id}.sandbox.superserve.ai/...` — no routing header needed. contact: name: Superserve Team license: name: Proprietary servers: - url: https://api.superserve.ai description: Production security: [] paths: /templates: post: tags: - Templates summary: Create a template and kick off the first build description: | Creates a template and queues the first build. The response includes both the template id and the build id, so clients can immediately poll `GET /templates/{id}` for overall status or subscribe to `GET /templates/{id}/builds/{build_id}/logs` for live output. Template starts in status `building`. Poll until it reaches `ready` before creating sandboxes from it. On failure the status becomes `failed` and `error_message` is populated. To rebuild an existing template (e.g. after a failure or when the base image updates), use `POST /templates/{id}/builds`. operationId: createTemplate requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateTemplateRequest' responses: '202': description: Template created; first build queued content: application/json: schema: $ref: '#/components/schemas/CreateTemplateResponse' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '409': $ref: '#/components/responses/Conflict' '429': description: | Quota reached. The `error.code` distinguishes: - `too_many_builds` — team has reached its concurrent build limit; wait for an active build to finish. - `too_many_templates` — team has reached its total template count limit; delete templates or contact support to raise the cap. content: application/json: schema: $ref: '#/components/schemas/Error' '500': $ref: '#/components/responses/InternalError' security: - apiKey: [] components: schemas: CreateTemplateRequest: type: object required: - name - build_spec properties: name: type: string minLength: 1 maxLength: 128 pattern: ^[a-z0-9]([a-z0-9._/-]*[a-z0-9])?$ description: > Human-readable name, unique per team. Used as the `from_template` value when creating sandboxes. Lowercase letters, digits, and `.` `_` `/` `-` only; must start and end with a letter or digit. Names starting with `superserve/` are reserved for curated system templates and rejected for team-owned templates. example: my-python-env vcpu: type: integer minimum: 1 maximum: 10 default: 1 memory_mib: type: integer minimum: 256 maximum: 20480 default: 1024 disk_mib: type: integer minimum: 1024 maximum: 30720 default: 4096 build_spec: $ref: '#/components/schemas/BuildSpec' CreateTemplateResponse: type: object description: | Returned by `POST /templates` — includes both the new template id and the id of the first build that was queued for it. Clients can immediately open the build-log SSE stream or poll the template for status transitions. properties: id: type: string format: uuid team_id: type: string format: uuid name: type: string status: type: string enum: - building - ready - failed vcpu: type: integer memory_mib: type: integer disk_mib: type: integer created_at: type: string format: date-time build_id: type: string format: uuid description: ID of the first build. Use it to stream logs or poll status. Error: type: object description: | Error envelope. `error.code` is a stable, machine-readable identifier (e.g. `bad_request`, `not_found`, `conflict`, `rate_limited`, `too_many_builds`, `too_many_templates`, `too_many_sandboxes`, `image_pull_failed`, `step_failed`, `snapshot_failed`, `start_cmd_failed`, `ready_cmd_failed`, `build_failed`). `error.message` is human-readable and may change between releases; clients should branch on `code`, not `message`. properties: error: type: object properties: code: type: string message: type: string BuildSpec: type: object required: - from description: Declaration of how to build a template. properties: from: type: string description: > OCI image reference for the base. Examples: `python:3.11`, `node:22-slim`, `ghcr.io/myorg/foo:v1`. Resolved to a digest at build time and recorded for reproducibility. Must be a Linux/amd64 image. Alpine and distroless bases are rejected at validation. example: python:3.11 steps: type: array items: $ref: '#/components/schemas/BuildStep' description: Ordered list of build steps executed inside the build VM. start_cmd: type: string description: > Optional command started after build steps complete. The snapshot captures the running process, so sandboxes restored from this template come up with the process already live. ready_cmd: type: string description: > Optional readiness probe. Polled every 2s after `start_cmd`, until it exits 0 or 10 minutes elapse. Use to wait for a server to bind its port before snapshotting. BuildStep: type: object description: > A single build step. Exactly one of `run`, `env`, `workdir`, or `user` must be set. properties: run: type: string description: Shell command. Wrapped in `/bin/sh -c` inside the build VM. example: pip install -r requirements.txt env: type: object required: - key - value description: > Sets an environment variable for subsequent build steps AND the template's runtime default. Sandboxes created from this template inherit it; caller-supplied `env_vars` on sandbox create override on conflict. properties: key: type: string value: type: string workdir: type: string description: > Working directory for subsequent build steps AND the template's runtime default cwd. Absolute paths are used as-is; relative paths resolve against the current workdir (base `/` when none has been set). Auto-created and chowned to the current build user. Per-exec `working_dir` overrides at runtime. example: /srv/app user: type: object required: - name description: > Switches the user subsequent build steps execute as, and sets the template's runtime default exec user. The user is created if it doesn't exist. Per-exec `user` overrides at runtime. properties: name: type: string description: > Linux username. Must start with a lowercase letter or underscore; allowed characters are [a-z0-9_-], max 31 chars. example: appuser sudo: type: boolean default: false description: When true, grants passwordless sudo to the user. responses: BadRequest: description: Invalid request content: application/json: schema: $ref: '#/components/schemas/Error' Unauthorized: description: Missing or invalid API key content: application/json: schema: $ref: '#/components/schemas/Error' Conflict: description: Operation conflicts with the resource's current state content: application/json: schema: $ref: '#/components/schemas/Error' InternalError: description: Internal server error content: application/json: schema: $ref: '#/components/schemas/Error' securitySchemes: apiKey: type: apiKey in: header name: X-API-Key ````