Skip to main content
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:
  1. Sends a verification email to that address
  2. You click the link in the email (10 min verification window)
  3. You pick an org if you belong to multiple
  4. 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:
  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.

​
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