Skip to main content
Understanding these key concepts will help you work effectively with Vers.

​
Projects

A project is your working directory containing:
  • vers.toml - Configuration file defining VM specifications
  • .vers/ - Directory storing branch references and metadata (similar to .git/)
Create a new project with: 
vers init my-project

​
Environments

An environment is your virtual machine setup. When you run vers run, Vers creates an environment based on your vers.toml configuration, including:
  • Root filesystem (rootfs)
  • Memory allocation
  • CPU configuration
  • Network setup
vers run  # Creates environment + root VM

​
Virtual Machines (VMs)

VMs are the actual running environments where your work happens. Each VM has:
  • Unique ID: Auto-generated identifier (e.g., vm-abc123)
  • State: Running, Paused, or Stopped
  • SSH Access: Connect via vers connect

​
Aliases

Aliases are human-readable names for VMs, stored locally on your machine.

​
Setting Aliases

Create aliases when starting or branching VMs: 
vers run --vm-alias my-dev-env
vers branch --alias feature-test
vers run-commit c123456 --vm-alias restored

​
Using Aliases

Use aliases anywhere you’d use a VM ID: 
vers connect my-dev-env    # Instead of: vers connect vm-abc123
vers checkout feature-test # Instead of: vers checkout vm-def456
vers execute my-dev-env "ls -la"

​
Viewing Aliases

vers alias              # List all aliases
vers alias my-dev-env   # Show VM ID for specific alias

​
Storage

Aliases are stored locally at ~/.vers/aliases.json: 
{
  "my-dev-env": "vm-abc123",
  "feature-test": "vm-def456"
}
Aliases are local only - they don’t sync between machines. They’re a convenience feature to avoid typing long VM IDs.
HEAD is a reference (pointer) to a VM. It represents your current working context.
HEAD is just a pointer - it does not mean you’re currently connected/SSH’d into that VM. You can have HEAD pointing to one VM while being SSH’d into a completely different VM.

​
Checking HEAD

vers checkout
# Shows: Current HEAD: my-vm (State: Running)

​
Moving HEAD

Use vers checkout to move HEAD to a different VM: 
vers checkout vm-abc123      # Move HEAD to specific VM
vers checkout my-alias       # Move HEAD using alias

​
Why HEAD Matters

Many commands operate on HEAD by default when you don’t specify a VM ID:
CommandWith HEADWithout HEAD
vers connectConnects to HEAD VMMust specify VM ID
vers killDeletes HEAD VMMust specify VM ID
vers branchBranches from HEADMust specify VM ID
vers commitCommits HEAD VMMust specify VM ID
vers pausePauses HEAD VMMust specify VM ID
vers resumeResumes HEAD VMMust specify VM ID
vers executeRuns on HEAD VMMust specify VM ID
vers copyCopies to/from HEADMust specify VM ID
This means you can work efficiently by setting HEAD once and running multiple commands: 
vers checkout my-dev-vm
vers connect          # SSH into my-dev-vm
# ... do work ...
exit
vers commit           # Commit my-dev-vm
vers branch --alias feature-test  # Branch from my-dev-vm

​
Branching VMs

Create a new VM from an existing VM’s state or from a commit: 
vers branch --alias feature-test       # Branch from HEAD
vers branch vm-abc123 --alias test     # Branch from specific VM
vers branch c123456 --alias restored   # Branch from a commit ID
vers branch --alias new-vm --checkout  # Branch and switch HEAD to it
When you branch from a VM:
  1. Parent pauses: The parent VM is briefly paused to create a consistent snapshot
  2. Commit created: A snapshot of the parent VM’s state is saved
  3. Child VM spawned: A new VM is created from that commit
  4. Parent resumes: The parent VM automatically resumes
  5. Both run simultaneously: Both parent and child VMs end up running
  6. Running processes continue exactly where they left off in the child VM
When you branch from a commit, the new VM is created directly from that saved state.

​
Commits and Snapshots

​
Creating a Commit

vers commit creates a snapshot of a VM’s current state: 
vers commit              # Commit HEAD VM
vers commit vm-abc123    # Commit specific VM
When you commit, the VM is paused automatically. If you want to keep working with it, run vers resume afterward.

​
Restoring from a Commit

Use vers run-commit to create a new VM from a commit: 
vers run-commit c123456789abcdef
This spins up a fresh VM with the exact state from when the commit was created. You can do this at any point in the future as long as you have the commit ID.

​
Commit Workflow Example

# Set up your environment
vers run
vers connect
# ... install dependencies, configure things ...
exit

# Save this state
vers commit
# Output: Commit ID: c123456789abcdef
# Note: VM is now paused

# Keep working? Resume it
vers resume

# Later, restore this exact state
vers run-commit c123456789abcdef

​
Branch Relationships

Vers maintains parent-child relationships between VMs:
  • Parents can have multiple children (branch multiple times from one VM)
  • Each child has exactly one parent (linear inheritance)
  • Deleting requires handling children first (use vers kill -r for recursive delete)

​
Working with Multiple VMs

You can work in multiple VMs simultaneously using different terminal sessions: 
# Terminal 1
vers connect vm-frontend
root@frontend:~# npm run dev

# Terminal 2
vers connect vm-backend
root@backend:~# python app.py

# Terminal 3
vers connect vm-database
root@database:~# psql
All VMs run in parallel, enabling true concurrent development and testing.

​
Configuration

​
vers.toml

Your project configuration: 
[machine]
mem_size_mib = 512        # Memory in MiB
vcpu_count = 1            # Virtual CPUs
fs_size_vm_mib = 512      # VM filesystem size in MiB

[rootfs]
name = "default"          # Base image name

[kernel]
name = "default.bin"      # Kernel image

​
.vers Directory

.vers/
├── HEAD      # Current VM reference
└── logs/     # Log storage

​
API Key Storage

Your API key is stored at ~/.versrc. View it with: 
cat ~/.versrc

​
Next Steps

Now that you understand the core concepts: