Image Sources

The image field on the create request determines what your sandbox boots. It accepts either a bare string (the convenient form) or a typed object (the explicit form), covering five sources: registry images, named project images, inline Dockerfile builds, and VM-state snapshot restores. This page explains each shape, when to use it, and how the ambiguous cases are resolved.

Quick reference

Note: A bare string containing / or : is treated as a registry reference; otherwise it is treated as a named project image. If a name could be ambiguous, use the explicit object form.

Registry images

The most direct route: reference any OCI image the way you would with docker run. Public images work with no setup at all; private registries work once you configure credentials for your project, which Daytona then resolves automatically by matching the image host — see Container registries.

The first use of a given image pulls and converts it once; after that it is cached fleet-wide and sandboxes start in about 100 milliseconds. See Images for the caching model.

from rlp import Daytona, CreateSandboxFromImageParams
 
daytona = Daytona()
sandbox = daytona.create(CreateSandboxFromImageParams(image="ghcr.io/acme/agent:v3"))

curl -X POST https://api.rl.trydaytona.com/vms \
  -H "Authorization: Bearer $RLP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"image": {"type": "registry", "ref": "ghcr.io/acme/agent:v3"}}'

Named project images

A named image is one your project built ahead of time with POST /images — from a registry reference or a Dockerfile with context — and registered under a stable name. Referencing it by name decouples sandbox creation from registry tags, guarantees the image is already cached, and carries image-level settings like the docker flag (which auto-provisions a Docker data device on every sandbox created from it).

Use named images when many sandboxes share one environment and you want creates to be uniformly fast and reproducible. See the Images API for building them.

curl -X POST https://api.rl.trydaytona.com/vms \
  -H "Authorization: Bearer $RLP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"image": {"type": "named", "name": "my-env"}}'

Dockerfile builds

You can also hand Daytona a Dockerfile at create time and have it build the image before booting the sandbox. The object shape takes the Dockerfile plus a context_object referencing the uploaded build context. Because create is asynchronous, the build simply extends the time before the sandbox reaches running — poll GET /vms/:id (or let the SDK's timeout cover it) as usual.

Inline builds are best for one-off or programmatically generated environments. If you will create more than a handful of sandboxes from the same Dockerfile, build a named project image once instead so every create is a cache hit.

curl -X POST https://api.rl.trydaytona.com/vms \
  -H "Authorization: Bearer $RLP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "image": {
      "type": "dockerfile",
      "dockerfile": "FROM python:3.12-slim\nRUN pip install requests",
      "context_object": "<uploaded-context>"
    }
  }'

Snapshots (restore)

The snapshot source boots a sandbox from a VM-state snapshot — a capture of a real sandbox taken earlier with sandbox.create_snapshot(name, kind). This is how you restore checkpoints or stamp out copies of a warmed-up environment, including everything that happened after boot: installed packages, cloned repos, generated files.

Behavior depends on the snapshot's kind:

• disk snapshots capture the filesystem. Restoring boots a fresh sandbox from that filesystem — normal boot, processes start from scratch.
• full snapshots capture memory and disk. Restoring resumes the sandbox: processes continue exactly where they were. Full snapshots are region-pinned and can only be restored in the region where they were taken.

The snapshot must be in the ready state; restoring one that is still being written fails with 409. See Snapshots for the concept and VM snapshots for the full how-to.

curl -X POST https://api.rl.trydaytona.com/vms \
  -H "Authorization: Bearer $RLP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"image": {"type": "snapshot", "name": "ckpt-1"}}'

Note: Image-alias snapshots (named, pre-cached image recipes created via the snapshot service) are a different feature restored via the SDK's snapshot create parameter, not via {"type": "snapshot"}. The distinction is explained in Snapshots.