# Persistence

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](https://www.daytona.io/docs/en/v2/macos-sandboxes.md#filesystem-persistence).

| **Layer**            | **What is preserved**                          | **Mechanisms**                                                                  |
| -------------------- | ---------------------------------------------- | ------------------------------------------------------------------------------- |
| **Filesystem**       | Files, packages, repositories, build artifacts | • [**Image capture**](https://www.daytona.io/docs/en/v2/images.md#capture-images)                        |
| **Memory**           | Processes, connections, states                 | • [**Snapshots**](https://www.daytona.io/docs/en/v2/snapshots.md#create-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**](https://www.daytona.io/docs/en/v2/images.md#capture-images) or write results to storage outside the sandbox to keep them.

```python
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**](https://www.daytona.io/docs/en/v2/snapshots.md#create-snapshots) 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](https://www.daytona.io/docs/en/v2/images.md#capture-images) saves the filesystem of a running Linux sandbox under a name, and new sandboxes boot from it. A [snapshot](https://www.daytona.io/docs/en/v2/snapshots.md) 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](https://www.daytona.io/docs/en/v2/macos-sandboxes.md#filesystem-snapshot)).

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](https://www.daytona.io/docs/en/v2/linux-sandboxes.md#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](https://www.daytona.io/docs/en/v2/preemption.md#spot-sandboxes) sandbox, the sandbox is deleted. Reclaimed sandboxes are stamped with **`spot_evicted_at`**. See [preemption](https://www.daytona.io/docs/en/v2/preemption.md).
- **Host failure**: a sandbox on a failed host is lost.

```python
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()
```