Agent swarms

Fork one golden VM into N parallel coding agents. Each agent gets an isolated environment in seconds; together they build something that would take you half an hour alone.

What you’ll build

A multiplayer snake game with server, client, and landing page — built by three agents in parallel
A reusable golden VM commit you can fork into any future swarm
Time: ~25 minutes end-to-end (agent wall time is ~60 seconds)

Prerequisites

Vers CLI installed and authenticated
An API key for your LLM provider (Anthropic, OpenAI, etc.)
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 to one agent. But the components are independent. If three agents build them simultaneously, it takes ~60 seconds. The bottleneck isn’t the LLM — it’s the environment. Each agent needs an isolated filesystem, and provisioning a fresh VM from scratch takes minutes. Vers solves that with branching: snapshot a fully provisioned VM once, fork it per agent in 258µs. Every branch is a copy-on-write environment that looks identical at branch time and diverges only on write.

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_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

TLS is handled by the Vers proxy — your VM serves plain HTTP and browsers see HTTPS. Any port in the routed range (1024–10000) works. The one gotcha: bind dual-stack, not IPv4-only:

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

See Networking for the full details.

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.

The pattern

Provision once, branch per task. The cost you pay to install tooling and reach a useful state is fixed — you pay it during vers commit. Every agent after that starts from the same golden snapshot in microseconds. This pattern generalizes beyond coding agents to any workload where:

Setup is expensive (installing a runtime, seeding a database, booting an application)
Tasks are independent (each agent/worker doesn’t need to read the others’ state)
You want many of them (N simultaneous workers instead of N sequential ones)

Keep the golden commit ID in your toolchain. Every future swarm branches from it.

What’s next

Build a pi extension

Wire Vers into your agent framework so swarms spawn with a single tool call.

vers branch

Every flag on the branch primitive.

API reference

Orchestrate swarms programmatically from your own code.

Architecture

How copy-on-write and content-addressable commits actually work.

Documentation Index

​What you’ll build

​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

​The pattern

​What’s next

Build a pi extension

vers branch

API reference

Architecture

What you’ll build

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

The pattern

What’s next