> ## Documentation Index
> Fetch the complete documentation index at: https://docs.beam.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Storage and Snapshots

> Persist the complete VM root, save restore points, fork environments, and create templates

## The root filesystem is durable

A VM's writable root is backed by a durable disk. Persistence includes installed software and files throughout the root, such as `/usr`, `/etc`, `/root`, `/workspace`, and Docker's data under `/var/lib/docker`. You do not need to confine persistent files to a special workspace directory.

Runtime mounts such as `/proc`, `/sys`, `/dev`, and `/run` are runtime state, rather than persistent application files. Volumes and additional disks are separate mounted storage.

For example, install tools and a Python environment, then stop and restart:

```bash theme={null}
beam vm exec devbox -- sh -c \
  'apt-get update && apt-get install -y jq python3-venv'
beam vm exec devbox -- python3 -m venv /opt/project-venv
beam vm exec devbox -- /opt/project-venv/bin/pip install requests
beam vm exec devbox -- sh -c 'echo saved > /root/example.txt'

beam vm stop devbox
beam vm start devbox

beam vm exec devbox -- jq --version
beam vm exec devbox -- /opt/project-venv/bin/python -c \
  'import requests; print(requests.__version__)'
beam vm exec devbox -- cat /root/example.txt
```

### Disk capacity

The default is **50 GiB of writable capacity over the base image**. Set `--disk-size` or `disk_size` at creation, up to **100 GiB**:

```bash theme={null}
beam vm new large-dev --disk-size 100Gi --protected-port 7681
beam vm exec large-dev -- df -h /
beam vm list
beam vm metrics large-dev
```

The guest sees an ext4 filesystem with a real capacity. Usable space reported by `df` is lower than the configured capacity because of filesystem metadata and overhead; a 100 GiB disk can display about 98 GiB. The configured disk size also appears in the VM list and specification.

## Read, write, and transfer files

VMs use the same filesystem API as sandboxes:

```python theme={null}
from beam import VM

with VM.connect("devbox") as vm:
    vm.fs.write_text("/workspace/config.json", '{"environment": "dev"}\n')
    print(vm.fs.read_text("/workspace/config.json"))
    vm.fs.write_bytes("/workspace/data.bin", b"\x00\x01\x02")
    vm.fs.upload_file("local.txt", "/workspace/local.txt")
    vm.fs.download_file("/workspace/data.bin", "data.bin")
```

See the [filesystem guide](/v2/sandbox/filesystem) for directories, file metadata, search, replacement, and byte operations. Use `vm.aio.fs` for async filesystem calls. For local directories and SSH file transfer, see [SCP and sync](/v2/vm/processes#copy-and-sync-files).

## Save a filesystem snapshot

Snapshots are reusable filesystem restore points. They do not include RAM or running processes; use [pause](/v2/vm/lifecycle#pause-and-resume) for that.

```bash theme={null}
beam vm snapshot create devbox --name clean-environment
beam vm snapshot list devbox
beam vm snapshot list --json
```

```python theme={null}
from beam import VM

with VM.get("devbox") as vm:
    snapshot = vm.snapshot("clean-environment")
    print(snapshot["id"])
    print(vm.snapshots())
```

Snapshot creation leaves the VM available in its current lifecycle state. Finish writes and quiesce applications that require an application-consistent backup before capturing a restore point.

### What a snapshot includes

A VM snapshot artifact captures the **root disk** and the VM's configuration. It is not a backup of every mounted dataset.

* Additional named durable disks keep their separate identities and persistence rules.
* Shared volumes keep their shared contents and are not copied into the root snapshot.
* A fork or template launch inherits those mount references unless you override them in the SDK. Root files are independent; externally mounted data may still be shared.
* A writable additional disk can have only one active writer. Stop its current owner or supply a different disk when launching another VM that uses it.

For additional-disk backups and independent datasets, use the [durable disk](/v2/data/durable-disks) and [volume](/v2/data/volume) APIs explicitly.

## Restore into a new VM

Use the snapshot's **ID** from `snapshot create` or `snapshot list` to create a new VM from that point in time:

```bash theme={null}
beam vm fork SNAPSHOT_ID restored-dev
beam vm ssh restored-dev
```

```python theme={null}
from beam import VM

restored = VM("restored-dev", snapshot="SNAPSHOT_ID").create()
print(restored.id)
restored.close()
```

This creates a new identity and new URLs. It does not overwrite the source VM. Choose the snapshot ID explicitly to restore historical contents; starting the original VM uses its latest saved root.

## Fork the current root

```bash theme={null}
beam vm fork devbox experiment
beam vm exec experiment -- sh -c 'echo experiment > /root/branch.txt'
```

```python theme={null}
from beam import VM

with VM.get("devbox") as source:
    with source.fork("experiment") as child:
        child.fs.write_text("/root/branch.txt", "experiment\n")
```

The new VM boots from the source's captured root, with an independent root disk, VM ID, and service URLs. Changing its root files does not change the source. Forking does not clone the source's RAM or active connections.

## Reusable private templates

Templates save a root and configuration for launching multiple environments:

```bash theme={null}
beam vm template create devbox python-dev --description "Python tools installed"
beam vm template list
beam vm template show python-dev
beam vm new another-dev --template python-dev
```

```python theme={null}
from beam import VM

with VM.get("devbox") as source:
    template = source.create_template("python-dev", description="Python tools installed")

vm = VM("another-dev", template=template["id"]).create()
vm.close()
```

Templates are private to the workspace. Public VM templates are unsupported. Roots can contain credentials and application data: remove anything you do not want future environments to inherit before saving a template.

## Clean up restore points

```bash theme={null}
beam vm snapshot rm SNAPSHOT_ID
beam vm template rm python-dev
```

Deleting an artifact removes that reusable restore point. It does not remove VMs already created from it. Manage VM deletion separately with `beam vm rm NAME`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.