CLI Reference

Complete command and option reference for beam vm

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; default ubuntu:22.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	Install and enable the browser desktop; requires Ubuntu 22.04.
--docker-enabled	Enable the guest Docker daemon.
--env KEY=VALUE	Runtime environment variable; repeatable.
--secret NAME	Runtime workspace secret; repeatable.
--port PORT	Publish an application port; repeatable.
--protected-port PORT	Publish a token-protected port; 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 guest traffic.
--allow-network CIDR	Allow outbound guest traffic only to these CIDRs; repeatable.
--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.

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 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	List stable port URLs; --json.
beam vm expose NAME PORT	--protected or --public; returns the published URL.
beam vm unexpose NAME PORT	Remove the published route.
beam vm access-token NAME	Print the VM traffic token; --rotate revokes previous token and sessions.
beam vm network NAME	--block / --open, repeatable --allow 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 browser terminal; --url / --url-only 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.

See networking and desktop for 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.

Python API equivalents

from beam import VM

Operation	SDK
Create / prepare	VM(name, **options).create(wait=True); prepare() builds the launch request without starting compute.
Resolve / connect / list	VM.get(name), VM.connect(name), VM.list(all=False, metadata=None, status=None). Pass context="CONTEXT" when needed.
Refresh / readiness	vm.refresh(), vm.wait(timeout=180, services=False).
Lifecycle	vm.start(wait=True, cold=False), vm.resume(), vm.stop(no_snapshot=False), vm.pause(), vm.remove().
Idle policy / metadata	vm.update(ttl=..., idle_action=..., auto_resume=..., metadata=...).
Activity / metrics	with vm.keep_alive(): ...; vm.metrics().
Processes / files / Docker	vm.process, vm.fs, vm.docker; async counterparts through vm.aio.
Snapshot / fork	vm.snapshot(name=None), vm.snapshots(), vm.remove_snapshot(name), vm.fork(name=None, wait=True). Restore with VM(snapshot=ID).create().
Template	vm.create_template(name=None, description=""); launch with VM(template=NAME_OR_ID).create().
Ports	vm.expose(port, protected=None), vm.unexpose(port), vm.bind(port), vm.get_url(port).
Access	vm.traffic_access_token, vm.rotate_access_token(), vm.access_url(port, ttl=600).
Egress	vm.update_network_permissions(block_network=False, allow_list=None).
Desktop	vm.desktop controls; vm.desktop_url, vm.terminal_url.
Client cleanup	vm.close() or a with block; does not stop the VM.

Use the VM lifecycle and port methods for the persistent resource. Its async process/filesystem/Docker interface reuses sandbox transports; sandbox termination and sandbox preview-URL methods are not replacements for VM lifecycle and stable URLs.