Skip to main content
Get up and running with your first Vers virtual machine. This guide takes you from project creation to your first branched VM.

​
What You’ll Accomplish

  • Create your first project
  • Launch a virtual machine
  • Connect via SSH
  • Experience the power of VM branching

​
Step 1: 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 2: 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 3: 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 4: 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 5: 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’ve created your first VM, learn about:

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