Persistence

The writable filesystem of a Daytona sandbox 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, or on another runner of the region with the same CPU model and hypervisor version. 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.

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. Capture works on a running Linux or Windows sandbox, which keeps running during the capture.

• 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. A restored sandbox continues with its processes still running. A snapshot restores in its home region, or, where Daytona has enabled cross-region restore, in another region if the source sandbox was not persistent.

• Servers that resume without a restart. A snapshot taken after a server starts keeps the server in memory. A restored sandbox continues with the server already running, instead of starting it again after a clean boot. The restored sandbox gets a fresh IP and port mappings.

• 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. Data on a volume also stays, and a later sandbox can attach the same volume and read it. A disk volume mounts as a local filesystem, while a bucket volume writes straight to an S3 bucket.

• Work that survives timeouts and reclaims. A timeout or a spot reclaim can delete a sandbox without a request from you, and a host failure loses an ephemeral sandbox, along with its state. Results on a volume or in a captured image stay when that happens. A persistent macOS sandbox stops on a timeout instead of being deleted, and keeps its disk.

Filesystem persistence

Filesystem persistence keeps the contents of a sandbox's disk: files, installed packages, cloned repositories, and build artifacts. Delete discards a sandbox's filesystem, and a host failure loses an ephemeral 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.capture_image(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 persistent Linux sandbox or one 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.

from daytona import Daytona

daytona = Daytona()
# Snapshot capture needs a persistent sandbox or one served from a warm template
sandbox = daytona.v2.create()

# Start a server that runs in the background
sandbox.process.start("python3 -m http.server 8000")

# A snapshot keeps memory and running processes beyond the sandbox
snapshot = sandbox.create_snapshot("my-snapshot")

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

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

# The restored sandbox resumes the server without starting it again
restored = daytona.v2.create_from_snapshot("my-snapshot")
response = restored.process.run(argv=[
    "python3", "-c",
    "import urllib.request; print(urllib.request.urlopen('http://localhost:8000').status)",
])
print(response.stdout)  # 200

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 write it to storage outside the sandbox.

Images and snapshots

An image capture saves the filesystem of a running Linux or Windows sandbox under a name, and new sandboxes boot from it. A snapshot saves the memory and disk of a running persistent Linux sandbox or one served from a warm template, and a restored sandbox resumes the captured processes. A snapshot restores on the runner that captured it, or on another runner of the region with the same CPU model and hypervisor version. 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.

Volumes

A volume is project-scoped storage that a sandbox attaches when it is created. Data on a volume stays when the sandbox is deleted, and a later sandbox can attach the same volume and read it. A disk volume is mounted as a local filesystem and commits each sandbox's changes in the background; a bucket volume mounts an S3 bucket, managed by Daytona or your own, and writes go straight to the bucket.

Retention and lifecycle

When one of a sandbox's timeouts elapses, Daytona runs the action set for that timeout: delete, or stop for a persistent macOS sandbox. The timeouts and actions 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, an ephemeral sandbox is deleted, and a Windows sandbox is stopped with its disk kept. Reclaimed sandboxes record the time of the reclaim. See preemption.
• Host failure: an ephemeral 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()