---
title: "Create an ephemeral sandbox."
method: POST
path: "/v1/sandboxes"
tags: ["Sandboxes"]
---

# Create an ephemeral sandbox.

`POST /v1/sandboxes`

## Request

- Base URL: `https://api.scalix.world`
- URL: `https://api.scalix.world/v1/sandboxes`
- Auth: HTTP bearer

Boots an isolated microVM. Ephemeral sandboxes are disposable: they stop
at their idle or hard timeout and nothing on the rootfs persists past
stop. Compute is billed per vCPU-hour and GB-hour of allocation while
running.

## Request body

- SandboxCreateRequest: Request body for creating an ephemeral sandbox.
  - `runtime` string, nullable: Runtime image. `node22` is available today; other values are rolling out and fail placement until their images ship.
  - `resources` object: Resource shape. Defaults: 1 vCPU, 512 MB memory, 5 GB disk.
  - `timeout_ms` integer, nullable: Hard lifetime in milliseconds (60000..86400000, default 300000). The sandbox also stops earlier at its idle timeout.
  - `ports` integer[], nullable: Guest ports to expose.
  - `source` object: `{type: "git", url, branch?}` clones a repository into the sandbox.
  - `env` object: Environment variables for the guest.

## Response `201`

Sandbox created (initially PROVISIONING)

- SandboxInfo: A sandbox as returned by create/get/list.
  - `id` string, required
  - `runtime` string, required
  - `status` string, required: PROVISIONING | RUNNING | STOPPING | STOPPED | FAILED | EXPIRED
  - `status_reason` string, nullable: Human-readable reason for the current status (set on FAILED and idle-stop transitions).
  - `vcpus` integer, required
  - `memory_mb` integer, required
  - `disk_gb` integer, required
  - `expires_at` string, required

## Other responses

- `401`: Missing or invalid API key
- `402`: Credit exhausted or plan limit reached
- `503`: No capacity for the requested resources

---

[API](https://skmtc.dev/scalix/apis/scalix-cloud-api.md) · [All operations](https://skmtc.dev/scalix/apis/scalix-cloud-api/llms.txt) · [OpenAPI document](https://skmtc.dev/scalix/apis/scalix-cloud-api/revisions/2c04ca0a90bb?raw)