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.

This page describes how Vers works under the hood. You don’t need any of this to use Vers — core concepts is enough. But if you’re evaluating, integrating, or debugging, the mental model helps.

​
The shape: a tree of live machines

A Vers project is a tree. The root is a VM you booted. Every call to vers branch adds a child. Every call to vers commit places an immutable marker on a node. 
  root            vm-abc123   [base image: ubuntu-24.04]
    │
    ├── branch    vm-9f2e77   ← agent_1  (exploring path A)
    │     │
    │     ├── commit  c1a2b3  tag:stable
    │     └── branch  vm-1e04 ← agent_1.1
    │
    ├── branch    vm-55dd01   ← agent_2  (exploring path B)
    │     └── commit  d7f09a
    │
    └── branch    vm-ff22c8   ← ci/preview-#482
          └── restored from   c1a2b3      (bad deploy rollback)
Two things make this more than a diagram of VM IDs:
  1. Children inherit live state from their parent at the moment of branching — memory, running processes, open file descriptors, sockets. The child is a running machine, not a fresh boot.
  2. Commits are content-addressable. The same state gets the same commit ID, and commits dedup across your whole project. Restoring c1a2b3 ten years from now gives you the same VM, bit-for-bit.

​
What vers branch actually does

A branch is a copy-on-write fork of a running VM. The steps, in order:
1

Pause

The parent VM is briefly paused so the hypervisor has a consistent view of memory and register state. This pause is in the microsecond range — end to end latency is p50 258.3µs / p99 329.2µs for a typical workload.
2

Snapshot

A commit is materialized for the parent’s exact state: memory pages, CPU state, and filesystem head pointer are captured. The commit is content-addressable, so if you branch from the same state twice you get the same underlying snapshot.
3

Child spawn

A new VM is created with its memory mapped copy-on-write from the parent’s snapshot, and its filesystem layered copy-on-write on top of the parent’s rootfs. The child has a new VM ID, its own kernel scheduling, its own vCPUs.
4

Parent resume

The parent resumes. Both parent and child are now running simultaneously, sharing memory pages that haven’t been written to in either. Pages diverge (physically copy) only on write.
Because the parent doesn’t wait on the child, you can branch into a thousand children nearly as fast as branching into one — forks happen off the critical path.
Copy-on-write is not copy-on-read. A freshly-branched child reading a memory page just reads the parent’s page directly. Only writes cause a physical page copy. This is why branching is so cheap — no bulk data movement at branch time.

​
What vers commit actually is

A commit is an immutable, content-addressable snapshot of a VM’s full state:
  • Memory — the VM’s full memory image at the moment of commit.
  • Filesystem head — a reference into the overlay filesystem’s layer stack.
  • Metadata — parent commit (if any), timestamp, tags, project association.
Commits live at the project/org level, not on a VM. A commit outlives the VM that produced it. You can vers run-commit <id> five seconds later or five months later, and you’ll boot a fresh VM that is byte-identical to the state when you committed. Because commits are content-addressable:
  • Dedup across VMs. If two VMs reach the same state (same golden image, same provisioning), committing both produces one underlying artifact with two references.
  • Immutable. A commit ID always maps to the same bytes. Restoring never depends on what happened after the commit was taken.
  • Tree-like history. Branch from a commit, branch from the result, commit again — you’re walking a DAG that looks a lot like git’s object store, just with memory pages and filesystem layers instead of blobs and trees.

​
Isolation model

Every Vers VM runs with hardware-level isolation:
  • Own kernel. Each VM boots its own kernel. There is no kernel sharing between sibling branches, parents, or unrelated VMs on the same host.
  • Own memory. Physical memory pages are remapped per VM by the hypervisor’s memory manager. Copy-on-write sharing is invisible to the guest — the child cannot read memory the parent writes after branching, and vice versa.
  • Own devices. Virtio devices (network, block, console) are per-VM. No shared mount namespaces, no shared PID namespaces — those are container concepts.
  • API keys scope to orgs, projects, commits. An API key for project A can’t touch project B’s VMs or commits.
The branching primitive does not weaken isolation. A child VM shares memory pages with its parent only as a performance optimization — both VMs see independent virtual memory and diverge at the first write. There is no shared-kernel path between them, even when they’re siblings on the same host.
The underlying hypervisor is a deliberate implementation detail. Vers has been built to keep the branching primitive portable across hypervisors, and may run on different ones in different regions or for different customers. Write your integrations against the Vers API, not against the hypervisor.

​
Storage: overlay filesystem + content addressing

Each VM’s disk is an overlay filesystem. A branch doesn’t copy disk blocks — it gets a new top layer that begins empty and diverges on write, stacked on top of the parent’s existing layers. 
vm-9f2e77 (child)     [layer: child-writes-go-here, empty]
                        │
                        ↓ reads fall through
vm-abc123 (parent)    [layer: post-provisioning changes]
                        │
                        ↓ reads fall through
base image            [ubuntu-24.04, read-only, shared]
A commit captures a pointer into this layer stack plus the VM’s memory. Restoring a commit re-creates a fresh top layer on top of the same committed stack — you get the same starting state as the committer, and new writes go into your new top layer. This is why commits dedup and why branching doesn’t linearly scale disk usage with branch count. A thousand branches of a 10GB VM don’t use 10TB — they use 10GB plus whatever diverges.

​
Where Vers sits in the stack

Vers is a branching primitive for live machines — the missing counterpart to every single-timeline tool you already use. Concretely:
  • Vers sits on top of a microVM hypervisor. The hypervisor is a deliberate implementation detail — what matters is the tree semantics, the commits, and the API.
  • Vers sits alongside container runtimes. Containers borrow the host kernel and share state through volumes and registries. Vers VMs boot their own kernel and share state through the branch tree. Different primitives, different shapes of problem.
  • Vers is upstream of CI and build systems. CI tools use Vers (branch per PR, commit golden states); Vers gives them a state model they can’t implement from scratch at this latency.
  • Vers is orthogonal to schedulers. Kubernetes spreads stateless load across nodes. Vers branches state across a tree. They compose — a Vers VM is a stateful worker a scheduler can run.

​
Keep reading

Core concepts

Projects, VMs, HEAD, branches, commits — from a user’s perspective.

Why Vers?

How Vers compares to sandboxes, hypervisors, and container schedulers.

CLI reference

Every flag on every command.

API reference

Programmatic VM management via REST.