> ## Documentation Index
> Fetch the complete documentation index at: https://docs.beam.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

```bash theme={null}
beam --context development vm list
```

## Create

```bash theme={null}
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](/v2/vm/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](/v2/vm/processes) 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](/v2/vm/networking) and [desktop](/v2/vm/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](/v2/vm/storage) for RAM and mounted-storage boundaries.

## Image building

```bash theme={null}
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

```python theme={null}
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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.