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

Field	Type	Required / default	Description
`name`	string	generated (`sandbox-<8 hex>`)	Display name. Not unique per project.
`image`	string \| object	required	Image name, registry ref (`"node:20"`), an explicit source object (`{"type":"registry","ref":...}`, `{"type":"named","name":...}`, `{"type":"dockerfile",...}`), or a snapshot source `{"type":"snapshot","name":...}`. A bare string containing `/` or `:` is treated as a registry ref, otherwise as a named image.
`mode`	string	`"burstable"`	`"burstable"` or `"dedicated"`. See Burstable vs Dedicated.
`cpu`	float	derived from `vcpus`	Guaranteed CPU cores (fractional allowed, rounded to 3 decimals). Must be > 0.
`vcpus`	int	`2`	Guaranteed cores as an integer; `cpu` wins when both are set.
`mem_mib`	int	`1024`	Guaranteed memory (MiB), ≥ 1.
`scratch_mib`	int	`512`	Guaranteed disk (MiB), ≥ 1.
`docker_data_mib`	int	none	Size (MiB) of a dedicated `/var/lib/docker` device for Docker-in-sandbox. Fresh per boot, never captured by snapshots. See Docker in Sandboxes.
`ports`	array	`[]`	Ports to expose: `{ "vm_port": 8080, "proto": "tcp" }` (`proto` defaults to `"tcp"`).
`volumes`	array	`[]`	Volume attachments: `{ "volume": "<id-or-name>", "mount_path": "/data", "subpath"?: "..." }`. Max 8. See Volumes.
`object_store_mounts`	array	`[]`	Object-store mounts: `{ "object_store": "<id-or-name>", "mount_path": "/mnt/bucket", "read_only"?: bool }`. Max 8. See Object Stores.
`secrets`	array of strings	`[]`	Names of project secrets to attach. Unknown names fail with `400`. See Secrets.
`env`	object	`{}`	Environment variables injected verbatim. Names must match `[A-Za-z_][A-Za-z0-9_]*`; values ≤ 64 KiB.
`persistent`	bool	`false`	Persistent write layer: enables warm stop/start, pause/resume, fork. See Persistent Sandboxes.
`spot`	bool	`false`	Spot tier: discounted, but reclaimable (paused if persistent, deleted if ephemeral). Immutable after create. See Spot Sandboxes.
`region`	string	resolved default	Target region slug. Resolution: request → project default → org default → platform default. Unknown/disabled regions fail with `400`.

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

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, 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, 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.

Query param	Type	Default	Description
`limit`	int	`100`	Page size, clamped to [1, 200].
`cursor`	string	—	Opaque token from a previous page's `next_cursor`. Malformed cursors return `400`.

cURL

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.

Query param	Type	Default	Description
`wait`	string	—	Block until the sandbox reaches this status or any terminal-bound state (`stopping`, `stopped`, `deleting`, `deleted`, `failed`, `lost`).
`wait_exact`	string	—	Block until the status matches exactly (only `failed`/`lost` short-circuit). Use `wait_exact=stopped` to wait past the transient `stopping`. Takes precedence over `wait`.
`timeout_ms`	int	`30000`	Max wait, clamped to [0, 60000]. On timeout the current state is returned with `200`.

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

cURL

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

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.

On this page