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 commit is an immutable snapshot of a VM’s full state — filesystem, memory, CPU registers — captured at the moment you ran vers commit. Commits have a content-addressable id (e.g. c123456789abcdef) that uniquely identifies that exact state. Commits are the currency of sharing, reuse, and reproducibility in Vers. Everything that “starts from somewhere” starts from a commit.

​
What a commit captures

CapturedNot captured
Full root filesystemExternal connections (TCP sessions survive memory but won’t recover if the network peer is gone)
Memory (every running process)IP address (new VMs get new IPs)
CPU registersSSH keys that weren’t on disk at commit time
Environment variables in running processesAccount-level vers env settings (those are injected at boot, not baked in)
In practice: if your work is in memory or on disk, it’s in the commit. If it depends on the outside world, you’ll need to re-establish that.

​
Creating a commit

vers commit              # Commit HEAD
vers commit my-vm        # Commit a specific VM
Committing pauses the VM. Run vers resume afterward if you want to keep working with it.
The output is a commit id. You can pipe it straight into other commands: 
COMMIT=$(vers commit --format json | jq -r .commit_id)
vers tag create stable "$COMMIT"

​
Restoring from a commit

vers run-commit <commit-id>
This boots a fresh VM from the saved state. It doesn’t “resume” the original VM — it creates a new one, identical to the moment of the commit, with its own id and IP. You can restore the same commit any number of times. Each call produces an independent VM. 
# Three independent VMs, all starting from the same commit
vers run-commit "$COMMIT" --vm-alias a
vers run-commit "$COMMIT" --vm-alias b
vers run-commit "$COMMIT" --vm-alias c

​
Commits vs branches vs forks

These words get muddled — a quick disambiguation:
OperationInputOutput
vers commitA running VMA new commit id
vers branch <vm>A running VMA new VM (plus a fresh commit, created internally)
vers branch <commit>A commitA new VM
vers run-commit <commit>A commitA new VM (conceptually identical to vers branch <commit>)
Branches always produce a running VM. Commits always produce a frozen state. Restores always produce a running VM from a frozen state.

​
Lifetime and deletion

Commits persist until you explicitly delete them with vers commit delete. They survive:
  • The deletion of the VM that produced them
  • The deletion of the child VMs they created
  • Your CLI logging out and back in
This makes commits the right place to stash “I might need this later” state. A VM is ephemeral; a commit is durable.

​
Tagging commits

Commit ids are long and unmemorable. Tags fix that: 
vers tag create production <commit-id>
vers tag create v1.2 <commit-id> -d "release candidate"
Tags are mutable — you can move them with vers tag update — and cheap. Deleting a tag doesn’t touch the commit it pointed at. Anywhere a commit id is accepted (vers run-commit, vers branch, vers build’s FROM), you can pass a tag name instead.

​
Repositories

For structured naming, tags can live inside repositories: my-app:latest, my-app:v1.2, etc. A repo is a namespace for a related group of commits. Repos can be public (other orgs can fork them) or private. See vers repo for the full workflow; most users can get away with plain tags until they need the structure.

​
A typical workflow

1

Prepare

Boot a VM, install dependencies, configure things.
vers run --vm-alias prep
vers connect prep
# apt install ... ; configure ... ; exit
2

Freeze

COMMIT=$(vers commit prep --format json | jq -r .commit_id)
vers tag create base "$COMMIT"
3

Fan out

Every future VM starts from this known-good base.
vers run-commit base --vm-alias worker-1
vers run-commit base --vm-alias worker-2

​
See also