Overview

Beam virtual machines are named, persistent Linux environments. Each VM runs in a CPU microVM with its own kernel, systemd, a durable root filesystem, and stable service URLs. Use a VM for development environments, coding agents, browser automation, or services that need to keep their installed software and files between sessions. Manage VMs with beam vm, the Python VM class, or Virtual machines in the dashboard.

Create your first VM

Install or upgrade the CLI, then sign in:

uv tool install beam-client
# If already installed: uv tool upgrade beam-client
beam login
beam whoami

Create a VM and connect over SSH:

beam vm new devbox --protected-port 7681
beam vm ssh devbox

The default VM has 4 CPUs, 8 GiB RAM, Ubuntu 22.04, and 50 GiB of writable root storage over the base image. SSH is enabled. Creation waits until commands can run; SSH also waits for its service to be ready. The first image build takes longer than creating another VM from an already built image. The protected port in this example secures the built-in browser terminal. SSH uses your workspace credentials and a local SSH key.

Files survive stop and start

beam vm exec devbox -- sh -c 'echo hello > /root/hello.txt'
beam vm stop devbox
beam vm start devbox
beam vm exec devbox -- cat /root/hello.txt

Stopping saves the filesystem and releases compute. Starting boots the same root disk, so files, apt packages, Python environments, and systemd units remain. Use pause and resume to preserve running processes and RAM too.

VMs keep running until you stop or pause them, remove them, or configure an idle TTL. Closing your terminal or Python client does not stop a VM. Running VMs incur compute usage even when no command is executing.

Use the Python SDK

Install beam-client in your Python environment as well as your CLI environment:

python -m pip install --upgrade beam-client

from beam import VM

vm = VM("python-devbox", protected_ports=[7681]).create()
try:
    vm.fs.write_text("/workspace/hello.txt", "Hello from Beam\n")
    process = vm.process.exec("cat", "/workspace/hello.txt")
    print(process.wait())
    print(process.stdout.read())
    print(vm.id)
    vm.stop()
finally:
    vm.close()

Use VM.get("python-devbox") to resolve an existing VM, or VM.connect("python-devbox") to resolve it and start it when necessary. VM.list() returns VM records. Names and IDs work for management operations; IDs start with vm-.

VMs and sandboxes

	Virtual machines	Sandboxes
Lifecycle	Named resource; stop/start and pause/resume	Temporary environment with a sandbox lifetime
Root filesystem	Persistent across stop/start	Use snapshots or mounted storage to retain data
Runtime	CPU microVM with its own kernel	Container runtime, or microVM with `use_vm=True`
GPUs	Unsupported	Supported by GPU-capable sandbox runtimes
Services	systemd, SSH, browser terminal, optional desktop	Process and networking APIs
URLs	Stay with the VM across lifecycle operations	Belong to the sandbox instance

Sandbox(use_vm=True) selects a microVM runtime for a sandbox. It does not turn the sandbox into a persistent, named VM. Use VM when you need this section’s lifecycle and durable root behavior.

Explore the VM guides

Configuration

Resources, images, environment variables, secrets, and metadata.

Lifecycle

Stop/start, pause/resume, idle TTLs, and automatic resume.

Storage and snapshots

Durable files, restore points, forks, and private templates.

Commands and SSH

Execution, stdin, logs, systemd, file transfers, and coding agents.

Networking

Stable subdomains, protected URLs, private tunnels, and egress controls.

Desktop

Browser access, screenshots, keyboard and mouse control, and recording.

Docker and Compose

Build and run containers inside a VM.

CLI reference

All VM commands and creation options.

Usage and billing

VM CPU and memory have their own rates on the pricing page. Stopped and paused VMs release compute; keeping a VM running continues to accrue usage. The dashboard Usage page groups VM usage under Virtual machines, separately from Sandboxes, and provides VM cost details and CSV export. Compute and credit allocation are finalized daily at 00:00 UTC. The current billing period can include an estimate for today. See pricing and billing for credits, invoices, and storage pricing.

Start Here

Sandboxes

Virtual machines

Inference

Building Blocks

Container Images

Data and Storage

Scaling

Operations

Run in Your Cloud

Advanced Topics

Resources

Security

Create your first VM

Files survive stop and start

Use the Python SDK

VMs and sandboxes

Explore the VM guides

Configuration

Lifecycle

Storage and snapshots

Commands and SSH

Networking

Desktop

Docker and Compose

CLI reference

Usage and billing

​Create your first VM

​Files survive stop and start

​Use the Python SDK

​VMs and sandboxes

​Explore the VM guides

Configuration

Lifecycle

Storage and snapshots

Commands and SSH

Networking

Desktop

Docker and Compose

CLI reference

​Usage and billing

Create your first VM

Files survive stop and start

Use the Python SDK

VMs and sandboxes

Explore the VM guides

Usage and billing