Images

Every sandbox boots from an image. Daytona accepts standard OCI images — the same ones you already build and push with Docker — and converts them into a boot-optimized format the first time they are used, so subsequent sandboxes start in about 100 milliseconds. You never manage that conversion; you just reference an image and create sandboxes.

Three ways to get an image

There are three routes to a bootable image, ordered roughly by how much you want Daytona to do for you:

1. Registry image — reference any public or private OCI image directly at create time: python:3.12-slim, ghcr.io/acme/agent:v3, and so on. This is the fastest way to get started. Private registries work by configuring credentials once per project; Daytona matches them to the image host automatically. See Container registries.

2. Named project image — build an image once via POST /images (from a registry reference or a Dockerfile plus build context) and give it a name. From then on, sandboxes reference it by that name — a stable, project-scoped alias that decouples your create calls from registry tags and pre-warms the image for fast creates. See the Images API.

3. Dockerfile at create time — pass a Dockerfile (and context) directly in the sandbox create request, and Daytona builds it before booting. This is convenient for one-off or programmatically-generated environments; if you will reuse the result, build a named image instead.

All three shapes are expressed through the image parameter on the create request — see Image sources for the exact JSON shapes and examples.

from rlp import Daytona, CreateSandboxFromImageParams
 
daytona = Daytona()
 
# 1. Straight from a registry
sandbox = daytona.create(CreateSandboxFromImageParams(image="python:3.12-slim"))

# 2. Reference a named project image (no "/" or ":" ⇒ treated as a name)
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-agent-env"}}'

Caching behavior

The first time a project uses a given image, Daytona pulls it from the registry and converts it into its boot format. This happens once per image, fleet-wide — not once per host, and not once per sandbox. Every subsequent create from that image starts from the shared cache, which is what makes ~100 ms sandbox creation possible.

The practical consequence: the very first create with a new image is as slow as the pull and conversion, and everything after it is fast. If you know a burst of creates is coming — an evaluation run, a fleet of agents — warm the image first by creating one sandbox from it, or by registering it as a named image or image-alias snapshot ahead of time.

Note: Caching is keyed to the image, so pushing a new tag (or overwriting one) means the new content is pulled and converted on its first use, just like a brand-new image.

Docker-enabled images

If sandboxes from an image will run Docker inside themselves, build the named image with the docker: true flag. Sandboxes created from a docker-enabled image automatically get a dedicated ephemeral device for /var/lib/docker (default size 10 GiB), so the Docker daemon works out of the box without any per-create configuration.

You can also enable Docker per sandbox — for any image — by setting docker_data_mib on the create request. See Docker in sandboxes for sizing, limitations, and examples.

Regions and architecture

Images are region-aware. When a sandbox in a given region references an image for the first time, the converted image is replicated into that region automatically; subsequent creates there hit the local copy. You do not need to pre-place images per region, though the first create in a new region pays the replication cost once.

Images are also architecture-aware. A region runs on either x86_64 or arm64, and the image you boot must be available for that architecture. Multi-architecture images (most official images, like python or node) resolve to the region's architecture automatically; a single-architecture image only works in a matching region. See Architecture support.

See Regions for how a sandbox's region is chosen and which regions are available.