Persistence

View as Markdown

The writable filesystem of a Daytona sandbox lives on host-local storage and exists only while the sandbox does. Deleting a sandbox discards its filesystem, memory, and processes. To keep state beyond the sandbox, capture it as an image or a snapshot, or write it to storage outside the sandbox.

Snapshots on this page are Linux snapshots: they save memory and disk and restore on the runner that captured them. A persistent macOS sandbox keeps its disk across stop and start, and a macOS snapshot saves only the disk of a stopped persistent sandbox, as an image that restores on any Mac of the region. See macOS filesystem persistence.

Layer	What is preserved	Mechanisms
Filesystem	Files, packages, repositories, build artifacts	• Image capture
Memory	Processes, connections, states	• Snapshots

Use cases

Persistence is used when the state of a sandbox must survive past the sandbox itself.

Prepared environments: an image capture keeps installed packages, repositories, and configuration. New sandboxes start from the image with nothing to reinstall or rebuild.
Runs from a known state: a snapshot copies a configured sandbox, so several runs or every agent in a fleet start from the same state.
Results that outlive the sandbox: a sandbox writes its output to storage outside the sandbox, such as your own object storage, and the data stays after the sandbox is deleted.

Filesystem persistence

Filesystem persistence keeps the contents of a sandbox’s disk: files, installed packages, cloned repositories, and build artifacts. A sandbox’s write layer is on host-local storage: delete discards the filesystem, and a host failure loses the sandbox. Capture an image or write results to storage outside the sandbox to keep them.

from daytona import Daytona

daytona = Daytona()
sandbox = daytona.v2.create()

# Prepare the environment to capture
sandbox.process.run("pip install requests")

# An image capture keeps the filesystem beyond the sandbox
image = sandbox.snapshot_filesystem(name="my-env")

# Capture runs asynchronously; wait until the image is ready
while image.status not in ("ready", "failed"):
    image = daytona.v2.images.get(image.id, wait="ready")
if image.status == "failed":
    raise RuntimeError(image.error)

# Delete discards the sandbox; the image remains
sandbox.delete()

# Any number of new sandboxes can start from the same image
clone = daytona.v2.create("my-env")
response = clone.process.run("pip show requests")
print(response.stdout)  # requests is already installed

Memory persistence

Memory persistence keeps the runtime state of a sandbox: running processes, open connections, and everything loaded in RAM. A snapshot captures the memory and disk of a running Linux sandbox served from a warm template, and a sandbox restored from it continues from the point it was captured, with processes still running, instead of starting from a clean boot. macOS snapshots do not save memory.

Persistence beyond a sandbox

Deleting a sandbox deletes its state. To persist state beyond the sandbox itself, capture it as an image or a snapshot, or store data outside the sandbox.

Images and snapshots

An image capture saves the filesystem of a running Linux sandbox under a name, and new sandboxes boot from it. A snapshot saves the memory and disk of a running Linux sandbox served from a warm template, and a restored sandbox resumes the captured processes. A snapshot restores only on the runner that captured it. A macOS snapshot is an image of the disk of a stopped persistent sandbox and restores on any Mac of the region (macOS snapshots).

A snapshot covers the sandbox’s own state. A restored sandbox gets a fresh IP and port mappings. Deleting the source sandbox does not delete its snapshots.

Retention and lifecycle

Daytona deletes a sandbox when one of its timeouts elapses. The timeouts come from the sandbox’s lifecycle policy, the project’s lifecycle defaults, or the platform default timeout. Two platform events also act on sandboxes without a request from you:

Spot reclaim: when the platform reclaims a spot sandbox, the sandbox is deleted. Reclaimed sandboxes are stamped with spot_evicted_at. See preemption.
Host failure: a sandbox on a failed host is lost.

from daytona import Daytona

daytona = Daytona()

# Create, use, delete
sandbox = daytona.v2.create()

# Run the workload and read the results before deleting
response = sandbox.process.run("python3 -c 'print(1 + 1)'")
print(response.stdout)

# Delete discards the sandbox and all of its state
sandbox.delete()