---
title: "Create a sandbox"
method: POST
path: "/sandboxes"
tags: ["sandboxes"]
---

# Create a sandbox

`POST /sandboxes`

## Request

- Base URL: `https://api.eqvps.com/api/v1/eqvps`
- URL: `https://api.eqvps.com/api/v1/eqvps/sandboxes`
- Auth: HTTP bearer

## Request body

- SandboxCreate
  - `mode` 'ephemeral' | 'persistent'
  - `tariff` 'micro' | 'small' | 'standard' | 'plus' | 'pro' | 'max': micro 0.25 vCPU/512 MB/3 GB · small 0.5/1 GB/5 GB · standard 1/2 GB/10 GB · plus 2/4 GB/15 GB · pro 4/8 GB/20 GB · max 8/16 GB/40 GB
  - `idle_timeout` integer: Seconds of inactivity before an ephemeral sandbox is deleted (default 300, max 3600)
  - `ttl` integer: Max lifetime in seconds (ephemeral ≤86400, persistent ≤2592000)
  - `env` SbxEnv: Environment variables for the process. Up to 64 names, 32 KB per value, 64 KB total. Values are stored encrypted, never returned by the API and not logged; responses show only env_keys. On create: applied to every exec/run in the sandbox. On exec/run: applied to that call and merged over the sandbox env.

## Response `201`

Created

- Sandbox
  - `id` string
  - `mode` 'ephemeral' | 'persistent'
  - `tariff` string
  - `state` 'running' | 'starting' | 'paused' | 'pausing' | 'resuming' | 'deleting': running = ready for commands (the internal sbxd state 'busy' is shown as running)
  - `created_at` string, date-time
  - `expires_at` string, date-time
  - `last_active` string, date-time
  - `idle_timeout` integer
  - `ttl` integer
  - `throttled` boolean
  - `paused_at` string, date-time
  - `pause_reason` string
  - `delete_after` string, date-time
  - `price_usd_per_hour` number
  - `ready` boolean: true when commands can run
  - `env_keys` string[]: Names of environment variables set on create (values are never returned)

## Other responses

- `402`: insufficient_balance
- `422`: invalid_request
- `429`: rate_limited / sandbox_limit (Retry-After) / budget_exceeded — spending cap reached; body: reason (daily|monthly), limit_usd, spent_usd, resets_at
- `503`: capacity / maintenance / service_unavailable (Retry-After)

---

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