Overview

Beam virtual machines are named Linux environments that keep installed software and files between sessions. Each VM runs in a CPU microVM with its own kernel, systemd, a durable root filesystem, and stable service URLs. Use them for development, coding agents, browser automation, or persistent services. Manage VMs with beam vm, the Python or JavaScript 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
beam vm ssh devbox

The default VM has 4 CPUs, 8 GiB RAM, Ubuntu 24.04, and 50 GiB of writable root storage over the base image. SSH is enabled. beam vm new includes a desktop when building a fresh image; use --no-desktop to skip it. Python and JavaScript SDKs enable the desktop only when requested. Templates and prebuilt images retain their settings. The built-in browser terminal is protected by default; beam vm terminal devbox opens it with an authenticated link. Use beam vm open devbox PORT for any published HTTP application. CLI SSH uses your workspace credentials and a local SSH key through an authenticated tunnel. A persistent IPv6 address, when allocated, also supports direct SSH and published TCP ports.

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 SDKs

Install the package for your language. JavaScript examples use Node.js with ES modules:

Python
JavaScript

python -m pip install --upgrade beam-client

npm install @beamcloud/beam-js
export BEAM_TOKEN=YOUR_BEAM_TOKEN

Python
JavaScript

from beam import VM

vm = VM("python-devbox").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()

import { beamOpts, VM } from "@beamcloud/beam-js";

beamOpts.token = process.env.BEAM_TOKEN || "";
const vm = await VM.create({
  name: "js-devbox",
});
try {
  await vm.fs.writeText("/workspace/hello.txt", "Hello from Beam\n");
  const command = await vm.exec(["cat", "/workspace/hello.txt"]);
  console.log(await command.wait());
  console.log(await command.stdout.read());
  console.log(vm.id);
  await vm.stop();
} finally {
  await vm.close();
}

Use VM.get("python-devbox") to read an existing VM’s state, or VM.connect("python-devbox") to start or resume it and wait until commands can run. VM.list() returns VM records. Names and IDs work for management operations; IDs start with vm-. In JavaScript, VM.create(), VM.get(), VM.connect(), and new VM(config).create() all return a VM object. See the SDK guide for the complete API.

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 with stop/start and a durable root.

VM guides

Configuration

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

Secrets

Bind credentials, scope approved hosts, and rotate values without restarting.

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.

SDK

Python and JavaScript APIs for lifecycle, snapshots, desktop, and networking.

Usage and billing

See the pricing page for VM CPU and memory rates. Stopped and paused VMs release compute; running VMs accrue usage. The dashboard Usage page shows VM costs and CSV export under Virtual machines, separately from Sandboxes. 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

Virtual Machines

Sandboxes

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 SDKs

VMs and sandboxes

VM guides

Configuration

Secrets

Lifecycle

Storage and snapshots

Commands and SSH

Networking

Desktop

Docker and Compose

CLI reference

SDK

Usage and billing

​Create your first VM

​Files survive stop and start

​Use the SDKs

​VMs and sandboxes

​VM guides

Configuration

Secrets

Lifecycle

Storage and snapshots

Commands and SSH

Networking

Desktop

Docker and Compose

CLI reference

SDK

​Usage and billing

Create your first VM

Files survive stop and start

Use the SDKs

VMs and sandboxes

VM guides

Usage and billing