Sandbox Lifecycle

Warm lifecycle operations — stop/start, pause/resume, and fork — are available only for sandboxes created with "persistent": true. Ephemeral sandboxes support only create and delete. Transitions are enforced atomically server-side, so concurrent lifecycle calls resolve to one winner and a 409 for the rest. See the guides: Stop & Start, Pause & Resume, Fork.

POST /vms/:id/stop

Warm-stop a running persistent sandbox: processes end, the filesystem persists, and billing for cpu/mem stops. The sandbox moves running → stopping → stopped; a later start boots the same filesystem on any capable host. Already stopping/stopped sandboxes return success (idempotent).

No request body.

cURL

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

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

Wait for confirmation with GET /vms/:id?wait_exact=stopped.

Errors

404 — unknown id or another project's sandbox.
409 — not persistent (delete instead), or not in a stoppable state (must be live: running, booting, assigned, or building).

POST /vms/:id/start

Cold-boot a stopped persistent sandbox from its persisted filesystem. Also works from paused as an escape hatch: the memory artifact is discarded and the intact filesystem cold-boots (processes are lost) — use resume to continue processes. The new incarnation gets a fresh IP; create-time env, volumes, object-store mounts, and secrets are restored.

No request body.

cURL

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

{
  "vm_id": "us1-3kTMbBWbdML5UWJHfyPyhF",
  "job_id": "5f2f9b3a-6a3f-4c86-9a1e-77e2b31f61aa",
  "status": "assigned"
}

Poll GET /vms/:id?wait=running for readiness.

Errors

402 — organization out of credits (a start resumes billing).
404 — unknown id or another project's sandbox.
409 — not persistent; not stopped/paused; no bootable filesystem manifest; or a concurrent start already in progress.

POST /vms/:id/pause

Memory-preserving pause of a running persistent sandbox: guest RAM and device state are captured, then the sandbox is torn down while the filesystem persists. A resume continues processes exactly where they left off. Pause is refused (409) for sandboxes with attached volumes, and for sandboxes with a Docker data device (enforced at capture time). Already pausing/paused returns success (idempotent).

No request body.

cURL

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

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

Wait with GET /vms/:id?wait_exact=paused.

Errors

404 — unknown id or another project's sandbox.
409 — not persistent; attached volumes; or not running.

POST /vms/:id/resume

Resume a paused persistent sandbox: memory and device state are restored, so in-flight processes continue. The resumed sandbox gets a fresh IP. If the pause left no memory artifact, resume fails with 409 — use start (cold boot) instead.

No request body.

cURL

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

{
  "vm_id": "us1-3kTMbBWbdML5UWJHfyPyhF",
  "job_id": "b3a1f0aa-9d0e-4a3c-8f61-2f11c6a0be71",
  "status": "assigned"
}

Poll GET /vms/:id?wait=running.

Errors

402 — organization out of credits.
404 — unknown id or another project's sandbox.
409 — not persistent; not paused; no memory artifact (use start); or a concurrent resume in progress.

POST /vms/:id/fork

Duplicate a persistent sandbox — filesystem and memory — into a new sandbox with its own id and lineage (forked_from). Two source states are forkable:

paused source: the pause artifact is copied; the fork lands paused (resume it to run).
running source: state is captured inside a brief freeze window, the source resumes, and the fork is automatically resumed to running.

The fork inherits the source's resources, secrets, and spot tier. Fork mirrors pause's restrictions: the source must be persistent and volume-free.

Request (optional body)

Field	Type	Required / default	Description
`name`	string	`"<source name>-fork"`	Display name for the fork.

cURL

curl -X POST https://api.rl.trydaytona.com/vms/us1-3kTMbBWbdML5UWJHfyPyhF/fork \
  -H "Authorization: Bearer $RLP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "worker-1-experiment" }'

{
  "vm_id": "us1-9rWvNq2xPzKfBdT7hLmA3c",
  "forked_from": "us1-3kTMbBWbdML5UWJHfyPyhF",
  "status": "pending"
}

Poll the returned vm_id: forks of a paused source settle at paused; forks of a running source settle at running.

Errors

402 — organization out of credits (a fork is a new billable sandbox).
404 — unknown id or another project's sandbox.
409 — not persistent; attached volumes; source not running/paused; a paused source with no memory artifact; or a fork of this sandbox is already in progress.

On this page