> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vers.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> From install to your first branched VM in under 10 minutes.

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:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
curl -sSL https://vers.sh/api/install | bash
```

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

Verify the install:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
vers --version
```

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

## Step 2: Authentication

### Log In to Vers

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
vers login
```

Paste in the API Key you created by following [get your api key](https://docs.vers.sh/get-api-key)

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

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
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

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
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

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
mkdir my-first-vers-project
cd my-first-vers-project
```

### Initialize the Project

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
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:

```toml theme={"theme":{"light":"min-light","dark":"min-dark"}}
[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

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
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

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
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

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
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:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
# 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

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
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

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
# See your VMs
vers status

# Switch to the new VM
vers checkout experiment

# Connect to the experiment VM
vers connect
```

Inside the experiment VM:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
# 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

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
# Switch back to main
vers checkout main
vers connect
```

Inside the main VM:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
# 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

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
# 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:**

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
# 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:**

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
# 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"

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
# Try logging in again
vers logout
vers login
```

### "No VMs found"

You haven't created any VMs yet:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
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

<CardGroup cols={2}>
  <Card title="Agent swarms" icon="robot" href="/tutorials/agent-swarms">
    Fork one golden VM into parallel agents. Full-stack app in \~60 seconds.
  </Card>

  <Card title="Parallel web testing" icon="code-branch" href="/tutorials/parallel-web-testing">
    Navigate to a form once, branch to test every input path in parallel.
  </Card>

  <Card title="Database state testing" icon="database" href="/tutorials/database-state-testing">
    Snapshot a seeded DB, branch per migration, compare outcomes.
  </Card>

  <Card title="Architecture" icon="sitemap" href="/architecture">
    How branching and commits work under the hood.
  </Card>
</CardGroup>

## Support

* **Email** — [support@vers.sh](mailto:support@vers.sh) for technical issues
* **GitHub** — [github.com/hdresearch](https://github.com/hdresearch) for issues and source