Configuration

JavaScript examples use @beamcloud/beam-js 1.1.0 or later. Configure the SDK before running them.

CPU, memory, and root disk

beam vm new devbox --cpu 4 --memory 8192 --disk-size 100Gi

Python
JavaScript

from beam import VM

vm = VM(
    "python-devbox",
    cpu=4,
    memory=8192,
    disk_size="100Gi",
).create()

const vm = await VM.create({
  name: "js-devbox",
  cpu: 4,
  memory: "8Gi",
  diskSize: "100Gi",
});

Setting	CLI	Python	JavaScript	Default
CPU cores	`--cpu 4`	`cpu=4`	`cpu: 4`	4; minimum 0.1
Memory in MiB	`--memory 8192`	`memory=8192`	`memory: "8Gi"`	8192; minimum 256
Writable root capacity	`--disk-size 50Gi`	`disk_size="50Gi"`	`diskSize: "50Gi"`	50 GiB; minimum 1 GiB, maximum 100 GiB
Browser desktop	`--desktop`	`desktop=True`	`desktop: true`	CLI: enabled for fresh images; SDKs: disabled. At least 1024 MiB RAM.
Docker daemon	`--docker-enabled`	`docker_enabled=True`	`dockerEnabled: true`	Disabled
SSH	Omit `--no-ssh`	`ssh=True`	`ssh: true`	Enabled for a new VM
Idle TTL in seconds	`--ttl 300`	`ttl=300`	`idleTimeout: 300`	Disabled
Automatic resume	`--auto-resume`	`auto_resume=True`	`autoResume: true`	Disabled

VMs are CPU-only. Resource availability depends on the microVM serverless pool. You normally do not need --pool; use it to select a CPU microVM pool you have access to. Choose CPU, memory, root disk size, and image when creating the VM. beam vm update changes idle behavior and metadata, not the machine’s allocation or root disk capacity. See storage for what df -h / reports.

Names and IDs

Names are unique within a workspace. A name must begin with a lowercase letter and contain at most 24 lowercase letters, digits, or hyphens. Omit the name for a generated name such as calm-fox-5959d8. The VM also has an immutable ID such as vm-0123456789abcdef. Use its name or ID with beam vm get, start, stop, and other commands. A VM’s current container ID may change when it restarts; use the VM identity when reconnecting.

Base images

VM images require Debian or Ubuntu. The default is Ubuntu 24.04 (Noble). Existing VMs, snapshots, templates, and prebuilt images keep their OS and packages; create a new VM to use the new default. Ubuntu 24.04 provides Python 3.12 through apt. For project packages, install python3-venv and use a virtual environment instead of modifying the system Python environment.

beam vm new debian-dev --image debian:bookworm --no-desktop

The browser desktop supports Ubuntu 24.04 (noble) and Ubuntu 22.04 (jammy). Use the default image for desktop VMs. Alpine and other distributions without the supported apt/systemd setup are not supported VM bases.

Build a custom image

Create a Dockerfile with the tools you need:

Dockerfile

FROM ubuntu:24.04
RUN apt-get update && apt-get install -y --no-install-recommends \
    build-essential git jq python3-venv \
    && rm -rf /var/lib/apt/lists/*
WORKDIR /workspace

Create a VM directly from the Dockerfile:

beam vm new buildbox --dockerfile Dockerfile --build-context .

Or build a reusable VM image first:

beam vm image build . --file Dockerfile --json
# Use the image_id in the result:
beam vm new buildbox --image-id IMAGE_ID

Use beam vm image build --desktop when the image will provide a desktop. An --image-id must already include the VM services; Beam cannot append packages to an existing immutable image ID, including an arbitrary sandbox image ID. Both SDKs accept an Image:

Python
JavaScript

from beam import Image, VM

image = Image.from_dockerfile("Dockerfile", context_dir=".")
vm = VM("python-buildbox", image=image).create()

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

const image = await Image.fromDockerfile("Dockerfile", ".");
const vm = await VM.create({
  name: "js-buildbox",
  image,
});

// Build a reusable VM image without launching a machine:
const prepared = await VM.prepareImage(image, { desktop: true });
const built = await prepared.build();

Use systemd units to start services at boot. VMs boot systemd and do not run the Dockerfile’s CMD as an application service.

Environment variables and secrets

Pass ordinary configuration with repeatable --env flags. Runtime secrets require approved credential hosts; bind them by name:

beam secret create OPENAI_API_KEY "$REAL_OPENAI_API_KEY" --host api.openai.com
beam vm new agentbox --env APP_ENV=development --env LOG_LEVEL=info \
  --secret OPENAI_API_KEY

Python
JavaScript

from beam import VM

vm = VM(
    "python-agentbox",
    env={"APP_ENV": "development", "LOG_LEVEL": "info"},
    secrets=["OPENAI_API_KEY"],
).create()

const vm = await VM.create({
  name: "js-agentbox",
  env: { APP_ENV: "development", LOG_LEVEL: "info" },
  secrets: ["OPENAI_API_KEY"],
});

The guest receives a placeholder instead of the secret value. The worker replaces it with the value only in HTTPS headers sent to approved hosts. Value updates take effect on the next request after the worker’s 15-second cache expires, without restarting the VM. An explicit network allowlist must cover every credential host; with --block-network, only bound credential hosts are reachable. See VM secrets for guest requests, network rules, rotation, and client compatibility. Beam does not inject a workspace token into the guest. Bind BETA9_TOKEN or BEAM_TOKEN explicitly as a secret to run Beam tools inside the VM; these opt-ins expose the token in plaintext. Other names beginning with BEAM_VM_ or BETA9_ are reserved. Use --build-secret NAME for image-build secrets, which expose plaintext values during the build and are separate from runtime bindings.

Additional storage

Attach a named disk or shared workspace volume for data that should persist independently of the VM’s root disk:

beam vm new databox --disk project-data:/data:20Gi \
  --volume shared-datasets:/datasets

Python
JavaScript

from beam import DurableDisk, VM, Volume

vm = VM(
    "python-databox",
    disks=[DurableDisk(name="project-data", mount_path="/data", size="20Gi")],
    volumes=[Volume(name="shared-datasets", mount_path="/datasets")],
).create()

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

const vm = await VM.create({
  name: "js-databox",
  disks: [{ name: "project-data", mountPath: "/data", size: "20Gi" }],
  volumes: [new Volume("shared-datasets", "/datasets")],
});

Additional VM disks use the qcow driver and ext4. Disk names cannot begin with vm-, which is reserved for VM roots. Mount paths must be unique absolute paths, must not overlap, and cannot replace /, /dev, /proc, /sys, /run, or /.beam. These mounts are separate from the root snapshot. Read snapshot and fork boundaries before using them in a reusable environment.

Metadata and creation retries

Use metadata to label environments and filter the VM list:

beam vm new devbox --metadata project=demo --metadata owner=engineering
beam vm list --metadata project=demo
beam vm update devbox --metadata project=demo --metadata owner=platform
beam vm update devbox --clear-metadata

An update replaces the complete metadata map. Metadata is visible in management responses; keep credentials in secrets. For creation retries, pass the same UUID as --request-id, request_id in Python, or requestId in JavaScript, with the same creation options. Reusing that request ID with a changed request is rejected. Reusing the same prepared Python VM object retains its request ID and prepared image, so a lost response can be retried without creating another VM. When creating from a template or snapshot, omitted configuration inherits the saved specification. Explicit settings override it. Choose one image source: registry image, image ID, Dockerfile, or template.

Start Here

Virtual Machines

Sandboxes

Inference

Building Blocks

Container Images

Data and Storage

Scaling

Operations

Run in Your Cloud

Advanced Topics

Resources

Security

Configuration

CPU, memory, and root disk

Names and IDs

Base images

Build a custom image

Environment variables and secrets

Additional storage

Metadata and creation retries

​CPU, memory, and root disk

​Names and IDs

​Base images

​Build a custom image

​Environment variables and secrets

​Additional storage

​Metadata and creation retries

CPU, memory, and root disk

Names and IDs

Base images

Build a custom image

Environment variables and secrets

Additional storage

Metadata and creation retries