Skip to main content

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.

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

ThingDescription
IDAuto-generated (vm-abc123). The canonical handle.
StateRunning, Paused, Stopped. Transitions via pause / resume / kill.
ResourcesMemory (MiB), vCPUs, disk (MiB). Set at creation. Disk can grow with vers resize.
NetworkingInternal IP; public hostname at {vm-id}.vm.vers.sh.
ParentThe VM or commit this one was created from (empty for root VMs).
AliasOptional local human-readable name.
Use vers info to see all of these for a given VM.

​
States

Running

CPU active, memory hot, reachable.

Paused

Memory preserved, CPU frozen. Resume with vers resume.

Stopped

Memory lost. Next start boots from disk.
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>:
1

Parent pauses briefly

A few tens of milliseconds — short enough that interactive sessions barely notice.
2

Commit is created

The parent’s state (filesystem + memory) is frozen as a commit.
3

Child VM spawned

A new VM boots from that commit.
4

Parent resumes

Back to Running. The child runs in parallel, independent from now on.
5

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.
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 and parallel web testing tutorial 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> 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: 
# Terminal 1
vers connect frontend

# Terminal 2
vers connect backend

# Terminal 3
vers connect db
For scripts, iterate over vers status -q: 
for vm in $(vers status -q); do
  vers execute "$vm" -- uptime
done

​
Sizing

Defaults (from vers.toml):
OptionDefault
mem_size_mib512
vcpu_count1
fs_size_vm_mib1024
Override per-run with flags: 
vers run --mem-size 4096 --vcpu-count 4 --fs-size-vm 8192
Disks can grow (never shrink) with vers resize.

​
See also