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

# Overview

> Persistent Linux machines with a durable root disk, SSH, and stable URLs

Beam virtual machines are named, persistent Linux environments. Each VM runs in a CPU microVM with its own kernel, systemd, a durable root filesystem, and stable service URLs. Use a VM for development environments, coding agents, browser automation, or services that need to keep their installed software and files between sessions.

Manage VMs with `beam vm`, the Python `VM` class, or **Virtual machines** in the [dashboard](https://platform.beam.cloud/vms).

## Create your first VM

Install or upgrade the CLI, then sign in:

```bash theme={null}
uv tool install beam-client
# If already installed: uv tool upgrade beam-client
beam login
beam whoami
```

Create a VM and connect over SSH:

```bash theme={null}
beam vm new devbox --protected-port 7681
beam vm ssh devbox
```

The default VM has **4 CPUs**, **8 GiB RAM**, Ubuntu 22.04, and **50 GiB of writable root storage over the base image**. SSH is enabled. Creation waits until commands can run; SSH also waits for its service to be ready. The first image build takes longer than creating another VM from an already built image.

The protected port in this example secures the built-in browser terminal. SSH uses your workspace credentials and a local SSH key.

## Files survive stop and start

```bash theme={null}
beam vm exec devbox -- sh -c 'echo hello > /root/hello.txt'
beam vm stop devbox
beam vm start devbox
beam vm exec devbox -- cat /root/hello.txt
```

Stopping saves the filesystem and releases compute. Starting boots the same root disk, so files, apt packages, Python environments, and systemd units remain. Use [pause and resume](/v2/vm/lifecycle#pause-and-resume) to preserve running processes and RAM too.

<Note>
  VMs keep running until you stop or pause them, remove them, or configure an idle TTL. Closing your terminal or Python client does not stop a VM. Running VMs incur compute usage even when no command is executing.
</Note>

## Use the Python SDK

Install `beam-client` in your Python environment as well as your CLI environment:

```bash theme={null}
python -m pip install --upgrade beam-client
```

```python theme={null}
from beam import VM

vm = VM("python-devbox", protected_ports=[7681]).create()
try:
    vm.fs.write_text("/workspace/hello.txt", "Hello from Beam\n")
    process = vm.process.exec("cat", "/workspace/hello.txt")
    print(process.wait())
    print(process.stdout.read())
    print(vm.id)
    vm.stop()
finally:
    vm.close()
```

Use `VM.get("python-devbox")` to resolve an existing VM, or `VM.connect("python-devbox")` to resolve it and start it when necessary. `VM.list()` returns VM records. Names and IDs work for management operations; IDs start with `vm-`.

## VMs and sandboxes

| | Virtual machines | Sandboxes |
| - | - | - |
| Lifecycle | Named resource; stop/start and pause/resume | Temporary environment with a sandbox lifetime |
| Root filesystem | Persistent across stop/start | Use snapshots or mounted storage to retain data |
| Runtime | CPU microVM with its own kernel | Container runtime, or microVM with `use_vm=True` |
| GPUs | Unsupported | Supported by GPU-capable sandbox runtimes |
| Services | systemd, SSH, browser terminal, optional desktop | Process and networking APIs |
| URLs | Stay with the VM across lifecycle operations | Belong to the sandbox instance |

`Sandbox(use_vm=True)` selects a microVM runtime for a sandbox. It does not turn the sandbox into a persistent, named `VM`. Use `VM` when you need this section's lifecycle and durable root behavior.

## Explore the VM guides

<CardGroup cols={2}>
  <Card title="Configuration" icon="sliders" href="/v2/vm/configuration">Resources, images, environment variables, secrets, and metadata.</Card>
  <Card title="Lifecycle" icon="power-off" href="/v2/vm/lifecycle">Stop/start, pause/resume, idle TTLs, and automatic resume.</Card>
  <Card title="Storage and snapshots" icon="database" href="/v2/vm/storage">Durable files, restore points, forks, and private templates.</Card>
  <Card title="Commands and SSH" icon="terminal" href="/v2/vm/processes">Execution, stdin, logs, systemd, file transfers, and coding agents.</Card>
  <Card title="Networking" icon="network-wired" href="/v2/vm/networking">Stable subdomains, protected URLs, private tunnels, and egress controls.</Card>
  <Card title="Desktop" icon="desktop" href="/v2/vm/desktop">Browser access, screenshots, keyboard and mouse control, and recording.</Card>
  <Card title="Docker and Compose" icon="docker" href="/v2/vm/docker">Build and run containers inside a VM.</Card>
  <Card title="CLI reference" icon="code" href="/v2/vm/cli">All VM commands and creation options.</Card>
</CardGroup>

## Usage and billing

VM CPU and memory have their own rates on the [pricing page](https://www.beam.cloud/pricing). Stopped and paused VMs release compute; keeping a VM running continues to accrue usage. The dashboard [Usage page](https://platform.beam.cloud/usage) groups VM usage under **Virtual machines**, separately from Sandboxes, and provides VM cost details and CSV export.

Compute and credit allocation are finalized daily at 00:00 UTC. The current billing period can include an estimate for today. See [pricing and billing](/v2/resources/pricing-and-billing) for credits, invoices, and storage pricing.


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