Snapshots

Daytona has two distinct features that are both called "snapshot", and they solve different problems. An image-alias snapshot is a recipe: a named, pre-cached image definition you create sandboxes from. A VM-state snapshot is a capture: the actual state of a specific running sandbox, saved so it can be restored later. This page exists because the distinction matters — mixing them up leads to confusing API errors and wrong mental models.

Two different things called "snapshot"

Image-alias snapshots

An image-alias snapshot pre-caches an image — either a registry reference or an inline Dockerfile build — under a name of your choosing. The build/pull happens when the snapshot is created, not when sandboxes are created from it, so every create is a cache hit. Use this to pin a known-good environment, to warm an image before a burst of creates, and to give teams a stable name that outlives registry tags.

from rlp import Daytona, CreateSandboxFromSnapshotParams
 
daytona = Daytona()
 
# Build/cache once, under a stable name
daytona.snapshot.create(name="agent-env", image="python:3.12-slim")
 
# Fast creates from the alias
sandbox = daytona.create(CreateSandboxFromSnapshotParams(snapshot="agent-env"))

import { Daytona } from '@rlp/sdk'
 
const daytona = new Daytona()
 
await daytona.snapshot.create({ name: 'agent-env', image: 'python:3.12-slim' })
const sandbox = await daytona.create({ snapshot: 'agent-env' })

Instead of a registry image, you can pass an inline dockerfile to build. The Dockerfile must be self-contained — COPY/ADD of local files is not supported for inline builds. Builds report their state (pending → building → active, or build_failed), and you can watch build progress before pointing a fleet at the alias.

VM-state snapshots

A VM-state snapshot captures a real, existing sandbox so you can recreate it later — including everything your code did after boot: installed packages, cloned repositories, generated files, warmed caches. You create one from a sandbox with sandbox.create_snapshot(name, kind), and restore it by creating a new sandbox with {"type": "snapshot", "name": ...} as the image source.

There are two kinds:

• disk — captures the filesystem at a point in time. Restoring boots a fresh sandbox from that filesystem, so it goes through normal boot: processes start from scratch, but every file is exactly as captured. Disk snapshots replicate across regions on first use, like images.
• full — captures memory and disk. Restoring resumes the sandbox exactly where it was: running processes continue, in-memory state is intact. Full snapshots are region-pinned — they can only be restored in the region where they were taken.

A snapshot must be ready before it can be restored; creating a sandbox from a snapshot that is still being written fails with 409.

# Checkpoint a warmed-up sandbox...
sandbox.create_snapshot("worker-after-setup", kind="disk")

# ...and restore it into a brand-new sandbox
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": "worker-after-setup"}}'

Choosing between them

Use an image-alias snapshot when the environment is fully described by an image or Dockerfile — it is the cleanest, most reproducible template. Use a disk VM-state snapshot when the valuable state was produced at runtime (a long pip install, a cloned monorepo, a trained artifact) and you want new sandboxes to start from it. Use a full VM-state snapshot when you need running processes and memory to survive — checkpoint/restore semantics rather than templating.

For the full how-to, including listing and deleting VM-state snapshots, see VM snapshots and the snapshot API reference.