Quickstart

Get up and running with Vers in under 10 minutes. This guide takes you from install 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: Install the CLI

Install the latest version of the Vers CLI with a single command:

curl -sSL https://vers.sh/api/install | bash

The installer detects your platform and places the binary at /usr/local/bin/vers. You may be prompted for admin privileges.

Verify the install:

vers --version

You should see the Vers version number. For alternate install methods (source build, manual binary), see Installation.

Step 2: Authentication

Log In to Vers

vers login

Paste in the API Key you created by following get your api key

Alternatively, if you want to create a vers account with your github email from CLI:

vers login --git

This opens your browser to authenticate with your Vers account. It pulls the email from your git config (git config user.email) and your SSH public key from ~/.ssh/, then:

Sends a verification email to that address
You click the link in the email (10 min verification window)
You pick an org if you belong to multiple
CLI auto-creates an API key labeled vers-cli-<hostname> and saves it in ~/.versrc

Once complete, you’re all set.

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_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:

Creates a new environment
Launches the root VM with the specified configuration
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

Command	Purpose
`vers init`	Initialize a new project
`vers run`	Start a development environment
`vers connect`	SSH into current VM
`vers branch --alias <name>`	Create a new VM branch
`vers checkout <vm>`	Switch to a different VM
`vers status`	Show VM status
`vers kill`	Delete 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.

What’s next

Agent swarms

Fork one golden VM into parallel agents. Full-stack app in ~60 seconds.

Parallel web testing

Navigate to a form once, branch to test every input path in parallel.

Database state testing

Snapshot a seeded DB, branch per migration, compare outcomes.

Architecture

How branching and commits work under the hood.

Support

Email — support@vers.sh for technical issues
GitHub — github.com/hdresearch for issues and source

Introduction

Get Running

What You’ll Accomplish

Step 1: Install the CLI

Step 2: Authentication

Log In to Vers

Alternatively, if you want to create a vers account with your github email from CLI:

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?

Common Patterns

Key Commands Reference

Troubleshooting

”Command not found: vers”

”Authentication failed"

"No VMs found”

VM won’t start

What’s next

Agent swarms

Parallel web testing

Database state testing

Architecture

Support

​What You’ll Accomplish

​Step 1: Install the CLI

​Step 2: Authentication

​Log In to Vers

​Alternatively, if you want to create a vers account with your github email from CLI:

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

​Common Patterns

​Key Commands Reference

​Troubleshooting

​”Command not found: vers”

​”Authentication failed"

​"No VMs found”

​VM won’t start

​What’s next

Agent swarms

Parallel web testing

Database state testing

Architecture

​Support

What You’ll Accomplish

Step 1: Install the CLI

Step 2: Authentication

Log In to Vers

Alternatively, if you want to create a vers account with your github email from CLI:

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?

Common Patterns

Key Commands Reference

Troubleshooting

”Command not found: vers”

”Authentication failed"

"No VMs found”

VM won’t start

What’s next

Support