Agent Bootstrap

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:

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

Step 1: Install the CLI

Check if Vers is already installed:

vers --version

If not installed:

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

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

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

Verify:

vers --version
# Should show a version like v0.10.0

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

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

Step 2: Authenticate

First, check if the CLI already has valid credentials:

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:

vers login --git

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

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

Poll for verification:

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

vers login --token <api-key>

Option C: Interactive Prompt

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

vers login

If No Account Exists

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

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:

vers signup --email user@example.com

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

Verify

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:

Human handoff required: org creation. Prompt the user:“You need a Vers organization to create VMs. Please visit https://vers.sh/orgs/new to create one, then come back here.”

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.

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

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

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:

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

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

Verify what’s configured:

vers env list

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.

Step 6: Initialize a Project

Create a project directory and initialize it:

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:

[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

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:

vers run-commit <commit-id-or-repo:tag> -N test-vm

Check status:

vers status

Connect and verify:

vers connect

Inside the VM, confirm your environment variables are injected:

echo $ANTHROPIC_API_KEY  # Should show your key
cat /etc/os-release      # Ubuntu base

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

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

vers connect

Inside the VM:

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

vers connect

Inside the VM:

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:

vers branch -n safe-checkpoint

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

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:

// Node.js
app.listen(3000, '::')

# Python
uvicorn.run("main:app", host="::", port=8000)

See Accessing your instance for full networking details.

What’s Next

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

Interactive development: Coding agent (SSH) walks through building with an agent over SSH
Remote agent swarms: Remote subagents covers spawning agents on VMs and driving them programmatically
Custom environments: 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:

export PATH="/usr/local/bin:$PATH"

“Authentication failed” or empty status

Re-authenticate:

vers logout
vers login --git

Environment variables missing inside VM

Verify they’re set:

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:

echo 'nameserver 8.8.8.8' > /etc/resolv.conf

Introduction

Get Running

Agent Bootstrap

What You’re Setting Up

Step 1: Install the CLI

Step 2: Authenticate

Option A: Git Email + SSH Key (Recommended)

Option B: Existing API Token

Option C: Interactive Prompt

If No Account Exists

Verify

Step 3: Verify Org Access

Step 4: Install GitHub App (Optional)

Step 5: Configure Environment Variables

Step 6: Initialize a Project

Configure VM Resources

Step 7: Launch and Test a VM

Option A: Fresh VM from vers.toml

Option B: VM from a Golden Image

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

Claude Code

pi

Step 9: Branch Before Experiments

Networking Quick Reference

What’s Next

Troubleshooting

”Command not found: vers”

“Authentication failed” or empty status

Environment variables missing inside VM

VM won’t start

No internet inside VM

​What You’re Setting Up

​Step 1: Install the CLI

​Step 2: Authenticate

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

​Option B: Existing API Token

​Option C: Interactive Prompt

​If No Account Exists

​Verify

​Step 3: Verify Org Access

​Step 4: Install GitHub App (Optional)

​Step 5: Configure Environment Variables

​Step 6: Initialize a Project

​Configure VM Resources

​Step 7: Launch and Test a VM

​Option A: Fresh VM from vers.toml

​Option B: VM from a Golden Image

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

​Claude Code

​pi

​Step 9: Branch Before Experiments

​Networking Quick Reference

​What’s Next

​Troubleshooting

​”Command not found: vers”

​“Authentication failed” or empty status

​Environment variables missing inside VM

​VM won’t start

​No internet inside VM

What You’re Setting Up

Step 1: Install the CLI

Step 2: Authenticate

Option A: Git Email + SSH Key (Recommended)

Option B: Existing API Token

Option C: Interactive Prompt

If No Account Exists

Verify

Step 3: Verify Org Access

Step 4: Install GitHub App (Optional)

Step 5: Configure Environment Variables

Step 6: Initialize a Project

Configure VM Resources

Step 7: Launch and Test a VM

Option A: Fresh VM from vers.toml

Option B: VM from a Golden Image

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

Claude Code

pi

Step 9: Branch Before Experiments

Networking Quick Reference

What’s Next

Troubleshooting

”Command not found: vers”

“Authentication failed” or empty status

Environment variables missing inside VM

VM won’t start

No internet inside VM