> ## 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. # Snapshot a sandbox > Captures the sandbox into a saved snapshot of its memory and disk, kept until deleted. Creating a sandbox from a snapshot, resuming with its processes intact, arrives in a later release; until then a snapshot can be listed, renamed and deleted. The sandbox must be active or paused. A running sandbox is paused for the capture: under a second for the first memory snapshot of a sandbox, longer when all of memory has to be written. The call returns once the snapshot is ready; if the host's answer is lost on the way, it returns the snapshot still `creating` and the platform settles it with the host shortly. Snapshots outlive the sandbox they came from. Pass `idempotency_key` to make a retry return the snapshot the first request made instead of taking another, whatever became of it since. ## OpenAPI ````yaml https://raw.githubusercontent.com/superserve-ai/sandbox/refs/heads/main/api/openapi.yaml post /sandboxes/{sandbox_id}/snapshot 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: /sandboxes/{sandbox_id}/snapshot: parameters: - $ref: '#/components/parameters/SandboxId' post: tags: - Snapshots summary: Snapshot a sandbox description: | Captures the sandbox into a saved snapshot of its memory and disk, kept until deleted. Creating a sandbox from a snapshot, resuming with its processes intact, arrives in a later release; until then a snapshot can be listed, renamed and deleted. The sandbox must be active or paused. A running sandbox is paused for the capture: under a second for the first memory snapshot of a sandbox, longer when all of memory has to be written. The call returns once the snapshot is ready; if the host's answer is lost on the way, it returns the snapshot still `creating` and the platform settles it with the host shortly. Snapshots outlive the sandbox they came from. Pass `idempotency_key` to make a retry return the snapshot the first request made instead of taking another, whatever became of it since. operationId: createSandboxSnapshot requestBody: required: false content: application/json: schema: $ref: '#/components/schemas/CreateSnapshotRequest' responses: '200': description: A snapshot an earlier request with the same `idempotency_key` made content: application/json: schema: $ref: '#/components/schemas/SnapshotResponse' '201': description: Snapshot ready content: application/json: schema: $ref: '#/components/schemas/SnapshotResponse' '202': description: > The host's answer was lost; the snapshot is still `creating` and is settled with the host shortly. Poll `GET /snapshots/{snapshot_id}`. headers: Retry-After: schema: type: integer content: application/json: schema: $ref: '#/components/schemas/SnapshotResponse' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' '409': description: >- The sandbox is not active or paused, or the host cannot capture it as it stands content: application/json: schema: $ref: '#/components/schemas/Error' '410': description: >- The snapshot an earlier request with the same `idempotency_key` made has since been deleted content: application/json: schema: $ref: '#/components/schemas/Error' '429': description: > The team's snapshot limit or its limit on snapshots being created at once is reached (`too_many_snapshots`, `too_many_snapshots_in_flight`), or the request rate limit (`rate_limited`). content: application/json: schema: $ref: '#/components/schemas/Error' '500': $ref: '#/components/responses/InternalError' '503': description: >- The host cannot take the snapshot as it stands, or does not support snapshots yet; retry content: application/json: schema: $ref: '#/components/schemas/Error' security: - apiKey: [] components: parameters: SandboxId: name: sandbox_id in: path required: true schema: $ref: '#/components/schemas/PublicSandboxId' description: The unique identifier of the sandbox. schemas: CreateSnapshotRequest: type: object properties: kind: type: string enum: - mem+fs default: mem+fs description: > `mem+fs` captures memory and disk. A disk-only kind is not offered yet. name: type: string minLength: 1 maxLength: 64 description: Optional label. Can be changed later with PATCH. idempotency_key: type: string minLength: 1 maxLength: 255 description: > Caller-chosen key, unique per sandbox. A retry carrying the same key returns the snapshot the first request made. SnapshotResponse: type: object required: - id - sandbox_id - kind - status - size_bytes - resources - created_at properties: id: type: string format: uuid sandbox_id: type: string format: uuid description: >- The sandbox the snapshot was taken from. It may since have been deleted. template_id: type: string format: uuid nullable: true description: The template the captured sandbox was created from. kind: type: string enum: - mem+fs status: type: string enum: - creating - ready - failed - deleting name: type: string nullable: true size_bytes: type: integer format: int64 description: Bytes the snapshot holds on disk; 0 until ready. resources: type: object required: - vcpu_count - memory_mib - disk_mib properties: vcpu_count: type: integer memory_mib: type: integer disk_mib: type: integer created_at: type: string format: date-time ready_at: type: string format: date-time nullable: true 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 PublicSandboxId: type: string pattern: >- ^(sb-[a-z0-9]+-)?[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$ description: > Public sandbox ID: a bare UUID, or the region-tagged form `sb--` (e.g. `sb-use-1b4e28ba-…`). Treat as an opaque string; the tagged form routes the request to the sandbox's home region. Endpoints accept both forms interchangeably. 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' NotFound: description: Resource not found 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 ````