Quickstart Guide

Get up and running with Vers in under 10 minutes. This guide takes you from download to your first branched virtual machine.

What You’ll Accomplish

Install the Vers CLI
Set up authentication
Create your first project
Launch a virtual machine
Experience the power of VM branching

Step 1: Download and Install

Download Vers

Visit the beta download page and download the appropriate binary for your platform.

Install the CLI

macOS/Linux:

# Make the binary executable
chmod +x vers-*

# Move to your PATH (requires admin password)
sudo mv vers-* /usr/local/bin/vers

# Verify installation
vers --version

Windows:

# Rename the downloaded file to vers.exe
# Add the directory containing vers.exe to your PATH
# Or place vers.exe in an existing PATH directory

# Verify installation
vers --version

You should see output showing the Vers version number.

Step 2: Authentication

Log In to Vers

vers login

This opens your browser to authenticate with your Vers account. Once complete, you’re ready to create projects.

Verify Authentication

vers status

If authentication was successful, you’ll see cluster information (likely empty for new accounts).

Step 3: Your First Project

Create a Project Directory

mkdir my-first-vers-project
cd my-first-vers-project

Initialize the Project

vers init

This creates:

vers.toml - Configuration file specifying VM resources and environment
.vers/ - Local repository for managing VM states and branches

Understanding vers.toml

The generated configuration looks like this:

[machine]
mem_size_mib = 512
vcpu_count = 1
fs_size_cluster_mib = 1024
fs_size_vm_mib = 512

[rootfs]
name = "default"

[kernel]
name = "default.bin"

[builder]
name = "none"
dockerfile = "Dockerfile"

This creates a basic Ubuntu environment. For real projects, you’ll often customize these settings.

Step 4: Launch Your First VM

Start the Environment

vers up

This command:

Creates a new cluster (your VM environment)
Launches the root VM with the specified configuration
Sets up the initial branch (main)

You’ll see output like:

=== Starting development environment ===
Cluster (ID: abc123) started successfully with root vm 'vm-xyz789'.
HEAD is now pointing to the new VM

Check the Status

vers tree

You should see something like:

Cluster: abc123 (Total VMs: 1)
└──  [R] vm-xyz789 (192.168.0.100) <- HEAD

This shows one running VM ([R]) that your HEAD points to.

Step 5: Connect to Your VM

SSH Into the VM

vers connect

This automatically:

Manages SSH keys
Connects you to the running VM
Drops you into a terminal session

You’re now inside a fresh Ubuntu environment! Try some commands:

# Check the OS
cat /etc/os-release

# See what's installed
which python3 node

# Create a file
echo "Hello from Vers!" > test.txt
cat test.txt

# Exit when ready
exit

Step 6: Experience VM Branching

This is where Vers gets powerful. Instead of starting over, you can branch your VM state.

Create a Branch

vers branch --name experiment

This creates a complete copy of your VM, including:

All installed software
Your files (test.txt is still there)
Running processes
Memory state

Switch Between Branches

# See your branches
vers tree

# Switch to the new branch
vers checkout experiment

# Connect to the experiment VM
vers connect

Inside the experiment VM:

# Your file is still here!
cat test.txt

# Make changes specific to this branch
echo "This is an experiment" >> test.txt
apt-get update && apt-get install -y curl

# Exit
exit

Compare States

# Switch back to main
vers checkout main
vers connect

Inside the main VM:

# Original file unchanged
cat test.txt

# curl not installed
which curl

This is the power of Vers: multiple VM states that diverged from the same starting point, without rebuilding from scratch.

Step 7: Clean Up (Optional)

Stop Your Environment

# Exit any VM connections first
exit

# Stop all VMs in the cluster
vers kill --cluster

This removes the cluster and all associated VMs.

What’s Next?

Now that you understand the basics, you’re ready for real projects:

Advanced Tutorials

Database Development:

Database State Testing with PostgreSQL - Learn to branch database states for parallel testing

Web Testing:

Parallel Web Testing with Puppeteer - Eliminate repetitive test setup through VM branching

Common Patterns

Development Workflow:

# Start a new feature
vers init
vers up
vers connect
# ... develop your feature ...
exit

# Create a branch for experiments
vers branch --name feature-experiment
vers checkout feature-experiment
vers connect
# ... try risky changes ...
exit

# Return to stable state
vers checkout main

Testing Workflow:

# Set up test environment once
vers init
vers up
vers connect
# ... install dependencies, load data ...
exit

# Test different scenarios in parallel
vers branch --name test-scenario-a
vers branch --name test-scenario-b

# Run tests simultaneously (different terminals)
vers checkout test-scenario-a
vers execute "npm test -- --scenario=a"

vers checkout test-scenario-b  
vers execute "npm test -- --scenario=b"

Key Commands Reference

Command	Purpose
`vers init`	Initialize a new project
`vers up`	Start VMs and clusters
`vers connect`	SSH into current VM
`vers branch --name <name>`	Create a new branch
`vers checkout <branch>`	Switch to a branch
`vers tree`	View VM hierarchy
`vers status`	Show cluster status
`vers kill`	Delete VMs/clusters

Troubleshooting

”Command not found: vers”

The binary isn’t in your PATH. Either:

Move it to /usr/local/bin/ (macOS/Linux)
Add its location to your PATH environment variable
Run it with the full path: ./vers-macos-arm64 --version

”Authentication failed"

# Try logging in again
vers logout
vers login

"No clusters found”

You haven’t created any VMs yet:

vers init
vers up

VM won’t start

Check your configuration in vers.toml. The default settings work for most systems, but you might need to adjust memory allocation on resource-constrained machines.

Support

Documentation: Explore more tutorials and CLI reference
Discord: Join our community for real-time help
Email: [email protected] for technical issues

You’re now ready to explore the full power of Vers! Try the PostgreSQL or Puppeteer tutorials to see how VM branching transforms development workflows.

Getting Started

​Quickstart Guide

​What You’ll Accomplish

​Step 1: Download and Install

​Download Vers

​Install the CLI

​Step 2: Authentication

​Log In to Vers

​Verify Authentication

​Step 3: Your First Project

​Create a Project Directory

​Initialize the Project

​Understanding vers.toml

​Step 4: Launch Your First VM

​Start the Environment

​Check the Status

​Step 5: Connect to Your VM

​SSH Into the VM

​Step 6: Experience VM Branching

​Create a Branch

​Switch Between Branches

​Compare States

​Step 7: Clean Up (Optional)

​Stop Your Environment

​What’s Next?

​Advanced Tutorials

​Common Patterns

​Key Commands Reference

​Troubleshooting

​”Command not found: vers”

​”Authentication failed"

​"No clusters found”

​VM won’t start

​Support