Sandboxes

Sandboxes are isolated micro-VMs created from an image, snapshot, or Dockerfile. Creation is asynchronous: the API returns immediately with status: "pending" and you poll (or long-poll) until running. See Creating Sandboxes for a conceptual guide.

POST /vms

Create a sandbox. Returns immediately; poll GET /vms/:id?wait=running for readiness. The response includes a per-sandbox access_token shown once — store it if you need direct sandbox access (SSH, preview URLs).

Request

Each class in the cpu_type / network_class / disk_class registries carries an ordered tier (1 = lowest), returned by their GET discovery endpoints. Pinning a class sets a floor: you always get that class or a higher one, never lower. cpu_type tiers are ranked per architecture.

Explicitly supplied resource values are clamped up to platform minimums; the defaults are exempt. In burstable mode the guarantees must not exceed the platform burst caps (400 otherwise).

curl -X POST https://api.rl.trydaytona.com/vms \
  -H "Authorization: Bearer $RLP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "worker-1",
    "image": "node:20",
    "cpu": 2,
    "mem_mib": 4096,
    "scratch_mib": 20480,
    "env": { "NODE_ENV": "production" },
    "persistent": true
  }'

{
  "vm_id": "us1-3kTMbBWbdML5UWJHfyPyhF",
  "job_id": "0d9cbd2e-8422-4be0-9a2e-59f28e1a2d10",
  "name": "worker-1",
  "status": "pending",
  "access_token": "rlpv_92c4f0a1d9b64f6f8b3f2a1c0d5e7a44"
}

Errors

• 400 — invalid mode, resource guarantees over burstable caps, dedicated cpu over the CPU cap, cpu <= 0, invalid env name or value > 64 KiB, unknown secret name, invalid/duplicate/reserved mount_path, more than 8 volumes or object-store mounts, unknown or disabled region (or a global region with no active members), invalid cpu_arch, unknown cpu_type or a cpu_type/cpu_arch mismatch, unknown network_class/disk_class (or either combined with gpu_host/Windows), full snapshot restored outside its home region.
• 402 — owning organization is out of credits.
• 404 — snapshot named in image does not exist.
• 409 — snapshot not ready; volume or object store not ready; image/snapshot still replicating into the target region (retry shortly).
• 429 — create queue at capacity. Honor the Retry-After header (default 2 s) and retry.
• 503 — queue temporarily degraded; nothing was created, safe to retry.

GET /vms

List the project's sandboxes, newest first, with cursor pagination.

curl "https://api.rl.trydaytona.com/vms?limit=2" \
  -H "Authorization: Bearer $RLP_API_KEY"

{
  "vms": [
    {
      "id": "us1-3kTMbBWbdML5UWJHfyPyhF",
      "name": "worker-1",
      "image_ref": "node:20",
      "manifest_name": "mani-7f3a1c.json",
      "runner_id": "runner-a12",
      "status": "running",
      "mode": "burstable",
      "cpu": 2.0,
      "vcpus": 16,
      "mem_mib": 4096,
      "scratch_mib": 20480,
      "vm_ip": "10.64.3.17",
      "host_ip": "10.0.1.4",
      "port_map": [],
      "error": null,
      "region": "us1",
      "spot": false,
      "spot_evicted_at": null,
      "persistent": true
    }
  ],
  "next_cursor": "MjAyNi0wNy0zMVQxMjozNDo1Ni4wMDAwMDAwMDBafDNr..."
}

next_cursor is null on the last page.

GET /vms/:id

Fetch one sandbox, with optional long-polling on status.

Statuses: pending, assigned, booting, building, running, stopping, stopped, pausing, paused, deleting, deleted, failed, lost.

curl "https://api.rl.trydaytona.com/vms/us1-3kTMbBWbdML5UWJHfyPyhF?wait=running&timeout_ms=30000" \
  -H "Authorization: Bearer $RLP_API_KEY"

{
  "id": "us1-3kTMbBWbdML5UWJHfyPyhF",
  "name": "worker-1",
  "image_ref": "node:20",
  "manifest_name": "mani-7f3a1c.json",
  "runner_id": "runner-a12",
  "status": "running",
  "mode": "burstable",
  "cpu": 2.0,
  "vcpus": 16,
  "mem_mib": 4096,
  "scratch_mib": 20480,
  "vm_ip": "10.64.3.17",
  "host_ip": "10.0.1.4",
  "port_map": [],
  "error": null,
  "region": "us1",
  "forked_from": null,
  "spot": false,
  "spot_evicted_at": null,
  "persistent": true
}

Errors

• 404 — unknown id, malformed id, or a sandbox in another project.

DELETE /vms/:id

Delete a sandbox. A live sandbox transitions deleting → deleted once teardown is confirmed; a resting sandbox (stopped, paused, failed, lost) is finalized to deleted immediately. Repeating a delete is idempotent. A persistent sandbox's write layer is reclaimed as part of the delete.

curl -X DELETE https://api.rl.trydaytona.com/vms/us1-3kTMbBWbdML5UWJHfyPyhF \
  -H "Authorization: Bearer $RLP_API_KEY"

{ "vm_id": "us1-3kTMbBWbdML5UWJHfyPyhF", "status": "deleting" }

Use GET /vms/:id?wait_exact=deleted to wait for teardown confirmation.

Errors

• 404 — unknown id or a sandbox in another project.