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

# Agent Bootstrap

> The one page your AI agent needs to set up Vers from scratch

This page is written for AI coding agents (Claude Code, pi, Codex, etc.) setting up Vers on behalf of a human user. Follow these steps in sequence. Human handoffs are marked clearly.

## What You're Setting Up

Vers provides branching virtual machines that capture filesystem and memory state. You're going to:

1. Install the Vers CLI
2. Authenticate your user (email + SSH key verification)
3. Verify org access
4. Install the GitHub App (for repo integration)
5. Configure environment variables for API keys
6. Launch a VM and verify it works
7. (Optional) Install an agent on the VM

## Step 1: Install the CLI

Check if Vers is already installed:

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

If not installed:

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

This installs the binary to `/usr/local/bin/vers`. You may need `sudo`:

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

Verify:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
vers --version
# Should show a version like v0.10.0
```

<Info>
  On Linux VMs (including Vers VMs themselves), you can also download the binary directly:

  ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
  wget https://github.com/hdresearch/vers-cli/releases/latest/download/vers-linux-amd64
  chmod +x vers-linux-amd64
  mv vers-linux-amd64 /usr/local/bin/vers
  ```
</Info>

## Step 2: Authenticate

First, check if the CLI already has valid credentials:

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

If this returns without error, skip to Step 3. If it fails, proceed with authentication.

### Option A: Git Email + SSH Key (Recommended)

This uses the email from `git config user.email` and your local SSH public key to create an API key automatically:

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

The CLI sends your email and public key to the Vers auth service, which sends a verification email.

<Warning>
  **Human handoff required: email verification.** The user must click a link in their email. Prompt them:

  "A verification email has been sent to your git email address. Please click the link in that email to verify your identity. I'll wait here and check every few seconds."
</Warning>

Poll for verification:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
TIMEOUT=300
ELAPSED=0
while [ $ELAPSED -lt $TIMEOUT ]; do
  sleep 8
  ELAPSED=$((ELAPSED + 8))
  if vers status >/dev/null 2>&1; then
    echo "Authentication successful!"
    break
  fi
  if [ $((ELAPSED % 30)) -eq 0 ]; then
    echo "Still waiting for email verification... (${ELAPSED}s elapsed)"
  fi
done
```

### Option B: Existing API Token

If the user already has an API key (from vers.sh):

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
vers login --token <api-key>
```

### Option C: Interactive Prompt

Plain `vers login` (no flags) prompts for an API key:

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

### If No Account Exists

If `vers login --git` fails because the user has no account, use signup:

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

This uses git email + SSH key by default (same as `vers login --git`), creates an account, and sends the same email verification flow. An organization with initial credits is auto-provisioned on signup.

To use a specific email instead of git config:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
vers signup --email user@example.com
```

<Info>
  Credentials are stored at `~/.vers/credentials.json` (for git/SSH auth) or `~/.versrc` (for token auth). You only need to authenticate once per machine.
</Info>

### Verify

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

A successful response confirms authentication.

## Step 3: Verify Org Access

After authentication, verify the user has an organization. The `vers status` output includes org info if available.

For users who signed up via `vers signup`, an org is auto-provisioned (named after the email prefix, with \$50 in initial credits). This step is usually a no-op.

If the user needs to create an org manually:

<Warning>
  **Human handoff required: org creation.** Prompt the user:

  "You need a Vers organization to create VMs. Please visit [https://vers.sh/orgs/new](https://vers.sh/orgs/new) to create one, then come back here."
</Warning>

## Step 4: Install GitHub App (Optional)

If the user wants Vers to access their GitHub repositories (for CI/CD, deployments, or repo-aware workflows), the Vers GitHub App must be installed on their GitHub account or organization.

<Warning>
  **Human handoff required: GitHub App installation.** GitHub requires browser interaction for App installations. Prompt the user:

  "To connect your GitHub repositories to Vers, please visit the GitHub App installation page (available at vers.sh under your org settings), select the repositories you want Vers to access, and authorize the app. Come back here when done."
</Warning>

<Info>
  🚧 **CLI gap:** There is no `vers github status` or `vers github install` command yet. GitHub App installation is currently done through the Vers web UI. Check the Vers API at `GET /api/github/repositories?orgId=<org-id>` to verify installation status programmatically.
</Info>

If GitHub integration isn't needed for the current workflow, skip this step. You can always install the App later.

## Step 5: Configure Environment Variables

Vers injects environment variables into every VM at startup via `vers env set`. This is how API keys reach agents running inside VMs.

Set the keys your workflow needs:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
# For Anthropic-based agents (Claude Code, pi with Claude)
vers env set ANTHROPIC_API_KEY sk-ant-...

# For OpenAI-based agents
vers env set OPENAI_API_KEY sk-...

# For Vers API access from inside VMs
vers env set VERS_API_KEY ...
```

<Warning>
  **Human handoff required.** Ask your user for each API key. Don't guess or generate placeholder values. Prompt:

  "Which AI provider API keys should I configure? I can set up Anthropic, OpenAI, or both."
</Warning>

Verify what's configured:

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

<Info>
  Environment variables set with `vers env` are injected into every VM you create, including branches. You only need to set them once. Inside VMs, they appear in `/etc/environment` and are available to all processes.
</Info>

## Step 6: Initialize a Project

Create a project directory and initialize it:

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

This creates `vers.toml` (VM configuration) and `.vers/` (local state).

### Configure VM Resources

Edit `vers.toml` for your workload:

```toml theme={"theme":{"light":"min-light","dark":"min-dark"}}
[machine]
mem_size_mib = 4096      # 4 GB RAM (good default for agent work)
vcpu_count = 2           # 2 CPUs
fs_size_vm_mib = 10240   # 10 GB disk

[rootfs]
name = "default"

[kernel]
name = "default.bin"
```

For agent workloads, 4 GB RAM and 10 GB disk is a reasonable starting point. Heavy builds (Haskell, Rust, large Node projects) may need more.

## Step 7: Launch and Test a VM

### Option A: Fresh VM from vers.toml

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
vers run -N test-vm
```

### Option B: VM from a Golden Image

If your team has pre-built golden images (with tools pre-installed), use:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
vers run-commit <commit-id-or-repo:tag> -N test-vm
```

Check status:

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

Connect and verify:

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

Inside the VM, confirm your environment variables are injected:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
echo $ANTHROPIC_API_KEY  # Should show your key
cat /etc/os-release      # Ubuntu base
```

Set up DNS for outbound internet (needed on fresh VMs):

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
echo 'nameserver 8.8.8.8' > /etc/resolv.conf
```

Exit with `exit` or `Ctrl+D`.

## Step 8: Install an Agent on the VM (Optional)

If you're setting up the VM for interactive agent use, connect and install your agent:

### Claude Code

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

Inside the VM:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
echo 'nameserver 8.8.8.8' > /etc/resolv.conf
apt-get update && apt-get install -y ca-certificates curl gnupg
curl -fsSL https://deb.nodesource.com/setup_22.x | bash -
apt-get install -y nodejs
npm install -g @anthropic-ai/claude-code
```

### pi

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

Inside the VM:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
echo 'nameserver 8.8.8.8' > /etc/resolv.conf
apt-get update && apt-get install -y ca-certificates curl gnupg
curl -fsSL https://deb.nodesource.com/setup_22.x | bash -
apt-get install -y nodejs
npm install -g @mariozechner/pi-coding-agent
```

## Step 9: Branch Before Experiments

Before making risky changes, create a branch:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
vers branch -n safe-checkpoint
```

This creates a full copy of the VM (files, memory, running processes). If something goes wrong:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
vers checkout safe-checkpoint
vers connect
```

Your original state is preserved.

## Networking Quick Reference

Your VM is publicly accessible at:

```
https://<vm-id>.vm.vers.sh:<port>
```

**Routed ports:** 80, 443, 3000, 3210, 3306, 3724, 5173, 8000, 8080, 9000, 9999, 1337

**Critical:** Services must bind to `::` (IPv6 dual-stack), not `0.0.0.0`:

```javascript theme={"theme":{"light":"min-light","dark":"min-dark"}}
// Node.js
app.listen(3000, '::')
```

```python theme={"theme":{"light":"min-light","dark":"min-dark"}}
# Python
uvicorn.run("main:app", host="::", port=8000)
```

See [Accessing your instance](/vm-access) for full networking details.

## What's Next

You now have a working Vers setup. Depending on your use case:

* **Interactive development**: [Coding agent (SSH)](/examples/coding-agent-ssh) walks through building with an agent over SSH
* **Remote agent swarms**: [Remote subagents](/agents/remote-subagents) covers spawning agents on VMs and driving them programmatically
* **Custom environments**: [Custom golden images](/agents/custom-golden-images) explains when and how to bake project-specific VM images

## Troubleshooting

### "Command not found: vers"

Ensure `/usr/local/bin` is in your `$PATH`:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
export PATH="/usr/local/bin:$PATH"
```

### "Authentication failed" or empty status

Re-authenticate:

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

### Environment variables missing inside VM

Verify they're set:

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

If variables show but aren't visible inside the VM, they were set after the VM was created. Environment variables are injected at VM startup. Create a new VM or branch to pick them up.

### VM won't start

Check `vers.toml` settings. Common issues:

* `fs_size_vm_mib` too small (try 10240 for agent workloads)
* `mem_size_mib` too small (try 4096)

### No internet inside VM

Set DNS:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
echo 'nameserver 8.8.8.8' > /etc/resolv.conf
```