Creating a Sandbox

Creating a sandbox is a single API call, but it helps to understand what happens behind it: creation is asynchronous, the response carries a one-time credential, and the platform can push back under load. This page covers the mechanics; the rest of the section covers every parameter and feature in depth.

The create flow

POST /vms does not block while the microVM boots. It validates the request, enqueues the boot, and returns immediately with the new sandbox's identifiers and a pending status. You then poll GET /vms/:id until the sandbox reaches running; the endpoint supports a long-poll form (?wait=running&timeout_ms=...) so you do not need a tight polling loop.

The SDKs hide all of this: create() submits the request and polls for you, returning a ready sandbox (default timeout 60 seconds). For cached images this whole round trip typically completes in about 100 milliseconds of boot time.

from rlp import Daytona, CreateSandboxFromImageParams
 
daytona = Daytona()
 
# Submits POST /vms, then polls GET /vms/:id until the sandbox is running.
sandbox = daytona.create(
    CreateSandboxFromImageParams(image="python:3.12-slim"),
    timeout=60,
)
print(sandbox.id)

import { Daytona } from '@rlp/sdk'
 
const daytona = new Daytona()
 
const sandbox = await daytona.create({ image: 'python:3.12-slim' }, { timeout: 60 })
console.log(sandbox.id)

# Create (returns immediately with status "pending")
curl -s -X POST https://api.rl.trydaytona.com/vms \
  -H "Authorization: Bearer $RLP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"image": "python:3.12-slim"}'
 
# Long-poll until running (up to 60s)
curl -s "https://api.rl.trydaytona.com/vms/$VM_ID?wait=running&timeout_ms=60000" \
  -H "Authorization: Bearer $RLP_API_KEY"

What you get back

The immediate POST /vms response is small — just enough to track and access the new sandbox:

{
  "vm_id": "…",
  "job_id": "…",
  "name": "sandbox-1a2b3c4d",
  "status": "pending",
  "access_token": "rlpv_…"
}

The access_token (rlpv_...) is a per-sandbox credential for calling the sandbox's toolbox directly, and it is returned only in this response — it cannot be fetched again later. If you call the toolbox yourself (rather than through an SDK), store it now. The SDKs capture it automatically.

Once the sandbox is running, GET /vms/:id returns the full sandbox object: id, name, state, resolved resources (mode, cpu, memory, disk), and the port_map that tells you which host ports were assigned to any ports you requested — see Port forwarding.

Note: Unknown fields in the create request body are silently ignored. Double-check field spelling — a typo like presistent will not produce an error; the field simply won't apply.

Admission and backpressure

Two conditions can prevent a create from being accepted, and they behave differently:

• Platform overload. If the platform is momentarily saturated, POST /vms returns 429 with a Retry-After header. This is transient — honor the header and retry. Well-behaved clients (including batch drivers creating large fleets) should treat 429 as normal flow control, not an error.
• Out of credits. If your organization has no remaining credits, creates are refused outright. Retrying will not help until credits are topped up — see Spending.

Where to go next

• Parameter reference — every field on the create request, with defaults and limits.
• Image sources — the five ways to specify what boots.
• Choosing sandbox options — how durability, resource mode, and pricing tier combine.
• Burstable vs dedicated — the two resource modes.
• Persistent sandboxes — durable storage, stop/start, pause, fork.
• Spot sandboxes — discounted, reclaimable capacity.
• Docker in sandboxes — run a Docker daemon inside a sandbox.
• Environment & secrets — configuration and protected credentials.