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

> ## Agent Instructions
> Install the Beam CLI, sign in, and connect coding agents to the Beam MCP server with `curl -fsSL https://www.beam.cloud/install | sh`. To also create a VM, run `curl -fsSL https://www.beam.cloud/install | sh -s -- --vm`.
> VMs are persistent Linux machines without GPUs. Defaults: 4 CPUs, 8 GiB of RAM, a 50 GiB disk, Ubuntu 24.04, and a browser desktop. A running VM accrues usage until you stop, pause, or remove it, or until an idle timeout puts it to sleep.
> Stopping a VM keeps its disk and discards RAM and processes. Pausing keeps both, and resuming restores them. To pause after 5 idle minutes and wake on access, run `beam vm update NAME --ttl 300 --idle-action pause --auto-resume`.
> Core VM commands: `beam vm new NAME`, `beam vm ssh NAME`, `beam vm sync NAME ./dir`, `beam vm exec NAME -- CMD`, `beam vm expose NAME PORT --protected`, `beam vm fork NAME NEW_NAME`, `beam vm pause NAME`, `beam vm stop NAME`, `beam vm rm NAME`.
> For GPUs, use a sandbox or a deployed endpoint. Sandboxes are disposable environments that boot in seconds and fork from snapshots.
> Current rates are at https://www.beam.cloud/pricing.

# 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; 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](https://docs.beam.cloud/v2/vm/configuration.md) 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](https://docs.beam.cloud/v2/environment/secrets.md#brokered-secrets-for-vms-and-sandboxes) 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](https://docs.beam.cloud/v2/vm/processes.md) 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](https://docs.beam.cloud/v2/vm/networking.md) and [desktop](https://docs.beam.cloud/v2/vm/desktop.md) 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](https://docs.beam.cloud/v2/vm/storage.md) 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`.

## SDK reference

See the [VM SDK guide](https://docs.beam.cloud/v2/vm/sdk.md) for Python and JavaScript examples and the complete API.


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