Skip to main content

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.

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