---
title: "Create Sandbox"
method: POST
path: "/sandboxes"
---

# Create Sandbox

`POST /sandboxes`

Create, boot, and register a new sandbox.

Builds a :class:`~smolvm.SmolVM` from the request's auto-config
fields, starts it, stores it in the registry under its id, and
returns the client-safe view.

## Request body

- CreateSandboxRequest — Request body for creating (and booting) a sandbox. Mirrors the auto-config arguments of the :class:`smolvm.SmolVM` constructor. All fields are optional; omitting them boots the default Alpine micro-VM.
  - `image` string, nullable — Image reference to boot (S3 ref, file:// URI, or path). Omit to use the default built-in image.
  - `os` 'alpine' | 'ubuntu' | 'windows' | 'macos', nullable — Guest OS for auto-configured images: 'alpine', 'ubuntu', 'windows', or 'macos'.
  - `memory` integer, nullable — Guest memory in MiB.
  - `disk_size` integer, nullable — Guest disk size in MiB.
  - `backend` 'firecracker' | 'qemu' | 'libkrun' | 'vz', nullable — Runtime backend override: 'firecracker', 'qemu', 'libkrun', or 'vz'.

## Response `201`

Successful Response

- SandboxResponse — A sandbox's public, client-safe state. Host-internal details (disk paths, PID, network device) are intentionally omitted — clients address a sandbox only by ``id``.
  - `id` string, required — Stable sandbox identifier.
  - `status` 'created' | 'running' | 'paused' | 'stopped' | 'error', required — VM lifecycle states.

## Other responses

- `400` — The request was invalid or the sandbox failed to boot.
- `422` — Validation Error

---

[API](https://skmtc.dev/celestoai/apis/smolvm.md) · [All operations](https://skmtc.dev/celestoai/apis/smolvm/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/celestoai/smolvm/revisions/ad347836d68f/schema)