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.

Four small concepts explain everything else in Vers. Start here if the CLI reference feels like a list of unrelated commands — after these four pages it won’t.

VMs

The unit of compute. Branchable, forkable, states and resources.

Commits

Immutable snapshots. Content-addressable, restorable anywhere.

HEAD and aliases

How commands know which VM you mean when you don’t say.

Dockerfile support

How vers build turns a Dockerfile into a commit.

Repositories and Tags

Named scopes for commits — versioning, publishing, and forking.

​
The shape of Vers in one page

Vers gives you three primitives and one rule.
PrimitiveWhat it is
VMA running Firecracker microVM. Has an ID, a state (Running, Paused…), and a parent.
CommitAn immutable snapshot of a VM’s filesystem + memory. Content-addressable by id.
BranchA new VM made from a parent VM (or a commit). It inherits the exact state, including running processes.
The rule: every VM is either rooted (vers run) or branched from another VM or a commit. That’s the tree. The CLI’s job is to let you move around it — create nodes (run, branch), freeze nodes (commit), navigate between them (checkout), throw nodes away (kill). Everything else — tags, repos, aliases, env vars, Dockerfile builds — is ergonomics layered on top.

​
What’s the difference between a commit and a branch?

Easy to conflate, worth pinning down.
  • A commit is a frozen state with an id. It doesn’t run. It exists forever (until you delete it). You can create N VMs from the same commit and they’ll all start identical.
  • A branch is a new running VM. It was created from either a live VM (pausing it briefly to capture state) or a commit. Once it’s running, it’s independent of its parent — no shared memory, no linked disk, changes on either side don’t touch the other.
Analogy: a commit is a git commit, a branch is a running clone of your working tree. Except here the “working tree” is a full Linux VM including in-memory state.

​
Next steps

  • If you’re new: jump to What is Vers? for the narrative intro.
  • If you know Vers and want to look something up: the CLI reference is exhaustive.
  • If you’re building a specific thing: the Examples show end-to-end flows.