CLI Reference

Use beam vm --help or beam vm COMMAND --help for the installed CLI’s help. Select another workspace context before the command:

beam --context development vm list

Create

beam vm new [NAME] [OPTIONS]

Option	Meaning
`--cpu CORES`	CPU allocation; default 4.
`--memory MiB`	Memory allocation; default 8192.
`--disk-size SIZE`	Writable root capacity over the base image; default `50Gi`, maximum `100Gi`.
`--image URI`	Debian/Ubuntu registry base; defaults to Ubuntu 24.04.
`--image-id ID`	An existing image already prepared with VM services.
`--dockerfile PATH`	Build a custom VM image from a Dockerfile.
`--build-context DIRECTORY`	Build context; requires `--dockerfile`.
`--build-secret NAME`	Image-build secret; repeatable.
`--template NAME_OR_ID`	Create from a private VM template.
`--desktop` / `--no-desktop`	Include or skip the browser desktop; enabled for fresh images. Requires at least 1024 MiB RAM. Supports Ubuntu 24.04 and 22.04; templates and prebuilt images retain their settings.
`--docker-enabled`	Enable the guest Docker daemon.
`--env KEY=VALUE`	Runtime environment variable; repeatable.
`--secret NAME`	Brokered runtime workspace secret with approved hosts; repeatable.
`--port PORT`	Publish an application port; repeatable.
`--protected-port PORT`	Publish a token-protected port; repeatable.
`--public-port PORT`	Publish a public port, including a terminal/desktop opt-out; repeatable.
`--no-ssh`	Disable SSH. SSH is enabled otherwise.
`--sync DIRECTORY`	Upload directory contents to `/workspace` after creation; requires SSH.
`--ttl SECONDS`	Idle sleep timeout; unset or `0` keeps running.
`--idle-action stop\|pause`	Save the root and stop (default), or save RAM and pause.
`--auto-resume` / `--no-auto-resume`	Enable or disable wake-on-access.
`--pool NAME`	Select a CPU microVM worker pool.
`--metadata KEY=VALUE`	Resource metadata; repeatable.
`--block-network`	Block outbound traffic except approved hosts of bound brokered secrets.
`--allow-network HOST_OR_CIDR`	Allow only these hostnames, wildcard domains, IPs or CIDRs; up to 64 entries.
`--request-id UUID`	Reuse the UUID and identical options to retry creation safely.
`--disk NAME:/mount[:SIZE]`	Additional durable disk; repeatable. Omitted size defaults to `10Gi`.
`--volume NAME:/mount`	Shared workspace volume; repeatable.
`--json`	Return the VM record as JSON.

Choose only one of --image, --image-id, --dockerfile, and --template. Omitted settings inherit the saved specification when creating from a template. See configuration for supported images and resource bounds. Terminal 7681 and enabled desktop 8080 are protected by default on new VMs. Runtime secrets receive placeholders; see brokered secrets for host rules, rotation, and client compatibility.

Inspect and manage

Command	Options and behavior
`beam vm list`	`--status STATUS`, repeatable `--metadata KEY=VALUE`, `--all`, `--json`. Includes size, disk, and current-boot uptime. `--all` includes deleted records.
`beam vm get NAME`	`--json`; identity, state, specification, and URLs.
`beam vm ip NAME`	Print the persistent public IPv6 address; fails if none is allocated.
`beam vm update NAME`	`--ttl SECONDS`, `--idle-action stop\|pause`, `--auto-resume` / `--no-auto-resume`, repeatable `--metadata KEY=VALUE`, `--clear-metadata`, `--json`. Metadata replaces the map.
`beam vm start NAME`	`--cold` to discard paused RAM; `--json`.
`beam vm resume NAME`	Alias of `start`, with the same options.
`beam vm pause NAME`	Save RAM and paired disks, then release compute; `--json`.
`beam vm stop NAME`	Save the root and release compute; `--no-snapshot` skips the named artifact, `--json`.
`beam vm rm NAME`	Delete the VM and its root disk.
`beam vm metrics NAME`	JSON sample of guest CPU, memory, and root disk usage.

Commands, processes, and files

Command	Options and behavior
`beam vm exec [OPTIONS] NAME -- COMMAND...`	`--cwd PATH` (default `/workspace`), `--timeout SECONDS` (default `0`), `--detach`, `--json`. Put options before NAME. `--detach` cannot be combined with `--timeout`.
`beam vm ps NAME`	List managed PIDs and exit status; `--json`.
`beam vm kill NAME PID`	Optional `--container-id ID` rejects a PID from an earlier runtime.
`beam vm logs NAME`	Choose `--pid PID`, `--unit UNIT`, or `--session SESSION`; `-f`. With no selector, read the journal.
`beam vm ssh NAME [-- COMMAND...]`	Interactive root SSH or a remote command.
`beam vm scp SOURCE DESTINATION`	Exactly one `NAME:/path`; `-r` for directories.
`beam vm sync NAME [DIRECTORY]`	Upload contents to `/workspace`; default directory `.`, `--watch` watches local edits.
`beam vm prompt NAME PROMPT`	`--agent claude\|codex` (default `claude`), `--cwd PATH`, `--background` / `--detach`. Requires agent credentials.

See commands and SSH for quoting, stdin, exit codes, logs, systemd, and activity leases.

URLs and networking

Command	Options and behavior
`beam vm ports NAME`	Show access modes, usable browser links, and SSH/tunnel commands; `--json` returns the stable port-to-URL map.
`beam vm expose NAME PORT`	`--protected` or `--public`; publishes application ports or toggles terminal/desktop protection. `--url` prints a usable link; `--json` returns VM metadata.
`beam vm open NAME PORT`	Open any published HTTP port with automatic browser authentication; `--url` prints the link without opening it.
`beam vm unexpose NAME PORT`	Remove an application route; system ports cannot be removed.
`beam vm access-token NAME`	Print the VM traffic token; `--rotate` revokes previous token and sessions.
`beam vm access-url NAME PORT`	Print a signed browser link; `--ttl SECONDS` accepts 1–3600, default 600. Requires a published protected HTTP port and VM subdomain.
`beam vm network NAME`	`--block` / `--open`, repeatable `--allow HOST_OR_CIDR`, `--json`. Controls outbound traffic.
`beam vm port-forward NAME PORT_OR_LOCAL:REMOTE`	Alternative `--local-port PORT`; authenticated localhost TCP forwarding.
`beam vm tunnel NAME PORT`	Low-level authenticated stdin/stdout tunnel.
`beam vm terminal NAME`	Open the authenticated browser terminal; `--url` prints its entry URL, `--no-open` also prevents opening.
`beam vm desktop NAME`	Open the enabled desktop; same URL/open options as `terminal`.
`beam vm screenshot NAME PATH`	Save a desktop PNG on the local machine.

Human-readable VM output includes authenticated links for protected ports, valid for 10 minutes. JSON output preserves stable URLs without temporary credentials; use open --url or access-url to obtain a browser link. Anyone holding a signed link can access that port until expiry. See networking and desktop for IPv6, protection, and browser sessions.

Snapshots and forks

Command	Options and behavior
`beam vm snapshot create VM_NAME`	`--name LABEL` / `--label LABEL`, `--json`; root filesystem restore point.
`beam vm snapshot list [VM_NAME]`	List all workspace snapshots, or those for one VM; `--json`.
`beam vm snapshot rm SNAPSHOT_ID_OR_NAME`	Remove a restore point.
`beam vm fork VM_NAME_OR_SNAPSHOT_ID [NAME]`	Independent root and identity; `--json`. Use the artifact ID when forking a snapshot.
`beam vm template create VM_NAME [NAME]`	`-d` / `--description TEXT`, `--json`; save a private reusable root.
`beam vm template list`	List private templates; `--json`.
`beam vm template show NAME_OR_ID`	Show a template; `--json`.
`beam vm template rm NAME_OR_ID`	Remove a template.

template create --public is reserved and returns an error; complete VM roots remain private. See storage and snapshots for RAM and mounted-storage boundaries.

Image building

beam vm image build [BUILD_CONTEXT] [OPTIONS]

The build context defaults to .. -f / --file PATH selects the Dockerfile; otherwise it uses BUILD_CONTEXT/Dockerfile. Use repeatable --secret NAME / --build-secret NAME, --desktop, and --json. The result contains an image_id usable with beam vm new --image-id.

SDK reference

See the VM SDK guide for Python and JavaScript examples and the complete API.

Start Here

Virtual Machines

Sandboxes

Inference

Building Blocks

Container Images

Data and Storage

Scaling

Operations

Run in Your Cloud

Advanced Topics

Resources

Security

CLI Reference

Create

Inspect and manage

Commands, processes, and files

URLs and networking

Snapshots and forks

Image building

SDK reference

​Create

​Inspect and manage

​Commands, processes, and files

​URLs and networking

​Snapshots and forks

​Image building

​SDK reference

Create

Inspect and manage

Commands, processes, and files

URLs and networking

Snapshots and forks

Image building

SDK reference