Skip to main content

​
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_vm_mib = 512

[rootfs]
name = "default"

[kernel]
name = "default.bin"
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 run
This command:
  1. Creates a new environment
  2. Launches the root VM with the specified configuration
  3. Sets your HEAD to the new VM
You’ll see output like: 
Sending request to start environment...
Environment started successfully with root vm 'vm-xyz789'.
HEAD now points to: vm-xyz789

​
Check the Status

vers status
You should see something like: 
HEAD status: vm-xyz789 (State: Running)

Fetching list of VMs...
Available VMs:

VM: vm-xyz789
State: Running
This shows your running VM that 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 --alias 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 VMs
vers status

# Switch to the new VM
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

# Delete your VMs
vers kill
This removes your VMs.

​
What’s Next?

Now that you understand the basics, explore these resources:

​
Common Patterns

Development Workflow: 
# Start a new feature
vers init
vers run
vers connect
# ... develop your feature ...
exit

# Create a branch for experiments
vers branch --alias 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 run
vers connect
# ... install dependencies, load data ...
exit

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

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

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

​
Key Commands Reference

CommandPurpose
vers initInitialize a new project
vers runStart a development environment
vers connectSSH into current VM
vers branch --alias <name>Create a new VM branch
vers checkout <vm>Switch to a different VM
vers statusShow VM status
vers killDelete VMs

​
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 VMs found”

You haven’t created any VMs yet: 
vers init
vers run

​
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.