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

# VMs

> The unit of compute. States, resources, the branching tree, and how they compose.

A **VM** in Vers is a full Firecracker microVM with its own kernel, filesystem, memory, and network. It's not a container, not a sandbox wrapper — it's a Linux machine you can SSH into.

Every interaction with Vers ultimately comes down to operating on VMs: you create them, branch them, freeze them as commits, and eventually delete them.

## What a VM has

| Thing          | Description                                                                         |
| -------------- | ----------------------------------------------------------------------------------- |
| **ID**         | Auto-generated (`vm-abc123`). The canonical handle.                                 |
| **State**      | `Running`, `Paused`, `Stopped`. Transitions via `pause` / `resume` / `kill`.        |
| **Resources**  | Memory (MiB), vCPUs, disk (MiB). Set at creation. Disk can grow with `vers resize`. |
| **Networking** | Internal IP; public hostname at `{vm-id}.vm.vers.sh`.                               |
| **Parent**     | The VM or commit this one was created from (empty for root VMs).                    |
| **Alias**      | Optional local human-readable name.                                                 |

Use [`vers info`](/cli-reference/info) to see all of these for a given VM.

## States

<CardGroup cols={3}>
  <Card title="Running" icon="play">
    CPU active, memory hot, reachable.
  </Card>

  <Card title="Paused" icon="pause">
    Memory preserved, CPU frozen. Resume with `vers resume`.
  </Card>

  <Card title="Stopped" icon="power-off">
    Memory lost. Next start boots from disk.
  </Card>
</CardGroup>

`vers pause` / `vers resume` are fast and cheap — paused VMs keep their memory so you resume right where you left off. Use them aggressively to save cost when you step away.

## The branching tree

This is the part that makes Vers different.

**Every VM belongs to a tree.** The root is whatever you created with `vers run` or `vers run-commit`; every other node is a branch.

```
vers run
   └─ vers branch → child-1
         ├─ vers branch → grandchild-a
         └─ vers branch → grandchild-b
   └─ vers branch → child-2
```

When you `vers branch <vm>`:

<Steps>
  <Step title="Parent pauses briefly">
    A few tens of milliseconds — short enough that interactive sessions barely notice.
  </Step>

  <Step title="Commit is created">
    The parent's state (filesystem + memory) is frozen as a commit.
  </Step>

  <Step title="Child VM spawned">
    A new VM boots from that commit.
  </Step>

  <Step title="Parent resumes">
    Back to Running. The child runs in parallel, independent from now on.
  </Step>

  <Step title="Running processes continue">
    In the child, every process that was running on the parent keeps running — no boot, no re-init. This is what makes the branching feel instant.
  </Step>
</Steps>

You can also branch from a commit directly (`vers branch <commit-id>`) — no parent VM required, just a materialized snapshot.

### Why this matters

* **Parallel scenarios**: Fork the same starting state N times to test N different paths.
* **Cheap experimentation**: Try risky things on a branch; throw it away if it goes wrong, parent untouched.
* **Agent swarms**: Give N agents identical copies of a golden environment in one second.

See the [agent swarms tutorial](/tutorials/agent-swarms) and [parallel web testing tutorial](/tutorials/parallel-web-testing) for concrete uses.

## Parent / child relationships

* A parent can have **many** children. Fan-out is the common case.
* A child has exactly **one** parent (linear inheritance).
* Once a child exists, its parent can't be deleted without `--recursive`. Otherwise the child would be "orphaned" (still runnable, but with a dangling lineage).

Use [`vers info <vm>`](/cli-reference/info) to see a VM's parent; use `vers kill -r <vm>` to delete a VM and everything downstream.

## Multiple VMs at the same time

There's no limit to how many VMs you run in parallel. Each terminal session can attach to a different one — just pass the alias or id:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
# Terminal 1
vers connect frontend
```

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
# Terminal 2
vers connect backend
```

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
# Terminal 3
vers connect db
```

For scripts, iterate over `vers status -q`:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
for vm in $(vers status -q); do
  vers execute "$vm" -- uptime
done
```

## Sizing

Defaults (from `vers.toml`):

| Option           | Default |
| ---------------- | ------- |
| `mem_size_mib`   | 512     |
| `vcpu_count`     | 1       |
| `fs_size_vm_mib` | 1024    |

Override per-run with flags:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
vers run --mem-size 4096 --vcpu-count 4 --fs-size-vm 8192
```

Disks can grow (never shrink) with [`vers resize`](/cli-reference/resize).

## See also

* [Commits](/concepts/commits) — how VM state is frozen and restored
* [HEAD and aliases](/concepts/head-and-aliases) — how commands pick a default VM
* [vers run](/cli-reference/run), [vers branch](/cli-reference/branch), [vers kill](/cli-reference/kill)
* [Networking](/networking) — the public hostname story