Agent swarms - Vers - Documentation

This tutorial demonstrates how to run parallel coding agents across branched Vers VMs. We’ll create a golden VM image with your tools pre-installed, branch it to spawn multiple agents simultaneously, and have them build a full-stack app in parallel — all coordinated through the Vers API.

What You’ll Learn

Creating a golden VM image for instant agent provisioning
Branching VMs to spawn parallel, isolated environments in seconds
Running agents (any framework) inside Vers VMs via SSH
Coordinating results across multiple VMs

Prerequisites

Vers CLI installed and authenticated
An API key for your LLM provider (e.g., Anthropic, OpenAI)
Basic familiarity with SSH and REST APIs

The Idea

Coding agents are serial — one agent writes one file at a time. A full-stack app with server, client, and landing page takes 10-15 minutes. But the components are independent. If three agents build them simultaneously, it takes ~60 seconds. The problem: each agent needs an isolated environment (its own filesystem), but provisioning VMs from scratch takes minutes. Vers solves this with branching — snapshot a fully provisioned VM once, branch it in seconds. Each branch gets an identical copy-on-write environment.

Step 1: Create the Golden Image

The golden image is a VM with your agent runtime and tools pre-installed. You create it once.

Initialize and Launch

mkdir agent-swarm && cd agent-swarm
vers init

Edit vers.toml for enough resources:

[machine]
mem_size_mib = 4096
vcpu_count = 2
fs_size_vm_mib = 8192

[rootfs]
name = "default"

[kernel]
name = "default.bin"

vers run --vm-alias golden
vers connect

Install Your Agent Runtime

Inside the VM, install whatever agent framework you use:

export DEBIAN_FRONTEND=noninteractive
apt-get update -qq
apt-get install -y -qq git curl wget build-essential jq tree python3 ca-certificates gnupg

# Install Node.js (needed by most agent frameworks)
curl -fsSL https://deb.nodesource.com/setup_22.x | bash -
apt-get install -y -qq nodejs

# Install your agent — pick one:
# npm install -g @mariozechner/pi-coding-agent    # pi
# npm install -g @anthropic-ai/claude-code         # claude code
# pip install aider-chat                            # aider

# Set up workspace
mkdir -p /root/workspace
exit

Snapshot It

vers commit

Save the returned commit ID. This is your golden image — every agent VM branches from it.

The VM is paused after commit. Run vers resume if you want to keep using it, or leave it paused to save resources.

Step 2: Branch Worker VMs

Create one VM per agent by restoring from the golden image:

vers run-commit <commit_id> --vm-alias worker-server
vers run-commit <commit_id> --vm-alias worker-client
vers run-commit <commit_id> --vm-alias worker-landing

Each VM boots with the exact state from the golden image — all tools installed, workspace ready. This takes seconds, not minutes.

vers status

You should see three running VMs.

Step 3: Write the Spec

Before tasking agents, write a spec that defines the contract between components. This is the only information workers share — they can’t read each other’s filesystems. Create a SPEC.md locally:

# Multiplayer Snake Game Spec

## Server (server.js)
- WebSocket server on port 3000
- 20x20 grid, 100ms tick rate
- Message types:
  - Server → Client: `{ type: "state", snakes: [{ id, segments: [[x,y]], direction, score }], food: { x, y } }`
  - Client → Server: `{ type: "direction", direction: "up"|"down"|"left"|"right" }`
- Collision detection: walls, self, other snakes
- Serve static files from ./public/

## Client (public/game.html + public/game.js)
- HTML5 Canvas rendering
- Arrow key controls
- Scoreboard showing all players
- Death screen with reason, click to respawn

## Landing Page (public/index.html)
- Game title and instructions
- Play button linking to /game.html
- Responsive design

Step 4: Task Each Agent

Copy the spec to each worker and start the agent. The exact command depends on your agent framework:

Using the Vers CLI

# Copy spec to each worker
vers copy SPEC.md worker-server:/root/workspace/SPEC.md
vers copy SPEC.md worker-client:/root/workspace/SPEC.md
vers copy SPEC.md worker-landing:/root/workspace/SPEC.md

Start agents on each VM. Open three terminals: Terminal 1 — Server worker:

vers checkout worker-server
vers connect
cd /root/workspace
export ANTHROPIC_API_KEY=<your_key>

# Start your agent with the task:
# pi: pi -p "Read SPEC.md. Build server.js and package.json per the Server section."
# aider: aider --message "Read SPEC.md. Build server.js and package.json per the Server section."
# Or any agent that takes a prompt

Terminal 2 — Client worker:

vers checkout worker-client
vers connect
cd /root/workspace
export ANTHROPIC_API_KEY=<your_key>

# "Read SPEC.md. Build public/game.html, public/game.js, public/style.css per the Client section."

Terminal 3 — Landing worker:

vers checkout worker-landing
vers connect
cd /root/workspace
export ANTHROPIC_API_KEY=<your_key>

# "Read SPEC.md. Build public/index.html per the Landing Page section."

All three agents build simultaneously in isolated environments.

Using the API

For programmatic control, use the Vers API directly:

# Execute a command on a VM without interactive SSH
vers execute worker-server "cd /root/workspace && ANTHROPIC_API_KEY=<key> pi -p 'Read SPEC.md. Build server.js and package.json per the Server section.'"
vers execute worker-client "cd /root/workspace && ANTHROPIC_API_KEY=<key> pi -p 'Read SPEC.md. Build public/game.html, game.js, style.css per the Client section.'"
vers execute worker-landing "cd /root/workspace && ANTHROPIC_API_KEY=<key> pi -p 'Read SPEC.md. Build public/index.html per the Landing Page section.'"

Step 5: Collect and Assemble

Once agents finish, pull files from each worker VM:

mkdir -p output/public

vers copy worker-server:/root/workspace/server.js output/server.js
vers copy worker-server:/root/workspace/package.json output/package.json
vers copy worker-client:/root/workspace/public/ output/public/
vers copy worker-landing:/root/workspace/public/index.html output/public/index.html

Fix Integration Mismatches

Workers will drift from the spec. Common issues:

Server sends segments, client reads snake
CSS uses .card, HTML uses .landing-card
Server sends [x, y] arrays, client expects {x, y} objects

Review the files, fix mismatches, and copy the assembled project to one VM:

vers copy output/ worker-server:/root/workspace/ --recursive

Verify

vers checkout worker-server
vers connect
cd /root/workspace
npm install
node server.js &
curl -s http://localhost:3000 | head -5

If you see HTML, the server is running.

Step 6: Serve It

Your app is accessible at:

https://<vm-id>.vm.vers.sh:3000

Vers terminates TLS at the proxy — your VM serves plain HTTP, browsers see HTTPS. No cert setup needed.

If your server binds 0.0.0.0 (IPv4 only), bind dual-stack instead:

server.listen(3000, "::");

Vers routes these ports: 80, 443, 3000, 3210, 3306, 3724, 5173, 8000, 8080, 9000, 9999, 1337.

Step 7: Clean Up

vers kill worker-server
vers kill worker-client
vers kill worker-landing

Or kill the golden image recursively to remove everything:

vers kill golden -r

The Time Savings

Step	Traditional	With Vers
Provision 3 environments	15 min (3 × 5 min)	15 sec (branch)
Agent builds	12 min (sequential)	~60 sec (parallel)
Integration fixes	2 min	2 min
Total	~29 min	~3 min

The savings compound with more workers. The golden image cost is paid once — every future swarm branches from it instantly.

Automating with Pi Extensions

If you’re using pi, the pi-v extensions automate the entire workflow above into tool calls:

vers_swarm_spawn — branches VMs and starts pi agents in one call
vers_swarm_task — sends prompts to agents
vers_swarm_wait — blocks until all agents finish
vers_swarm_teardown — cleans up all VMs

See the Pi Extensions tutorial for how to build Vers integrations into any agent framework.

Next Steps

Keep your golden image commit ID — reuse it for any future swarm
Try different decompositions: API + worker + dashboard, CLI + library + tests
Explore the API Reference for programmatic VM management
Learn about branching and commits in depth

Tutorials

​What You’ll Learn

​Prerequisites

​The Idea

​Step 1: Create the Golden Image

​Initialize and Launch

​Install Your Agent Runtime

​Snapshot It

​Step 2: Branch Worker VMs

​Step 3: Write the Spec

​Step 4: Task Each Agent

​Using the Vers CLI

​Using the API

​Step 5: Collect and Assemble

​Fix Integration Mismatches

​Verify

​Step 6: Serve It

​Step 7: Clean Up

​The Time Savings

​Automating with Pi Extensions

​Next Steps

What You’ll Learn

Prerequisites

The Idea

Step 1: Create the Golden Image

Initialize and Launch

Install Your Agent Runtime

Snapshot It

Step 2: Branch Worker VMs

Step 3: Write the Spec

Step 4: Task Each Agent

Using the Vers CLI

Using the API

Step 5: Collect and Assemble

Fix Integration Mismatches

Verify

Step 6: Serve It

Step 7: Clean Up

The Time Savings

Automating with Pi Extensions

Next Steps