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:

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:

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:

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 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.

Save a filesystem snapshot

Snapshots are reusable filesystem restore points. They do not include RAM or running processes; use pause for that.

beam vm snapshot create devbox --name clean-environment
beam vm snapshot list devbox
beam vm snapshot list --json

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 and 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:

beam vm fork SNAPSHOT_ID restored-dev
beam vm ssh restored-dev

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

beam vm fork devbox experiment
beam vm exec experiment -- sh -c 'echo experiment > /root/branch.txt'

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:

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

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

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.