> ## 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 swarms > Fork one golden VM into parallel coding agents. Build a full-stack app (server + client + landing) in ~60 seconds by running three agents simultaneously. 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 ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} mkdir agent-swarm && cd agent-swarm vers init ``` Edit `vers.toml` for enough resources: ```toml theme={"theme":{"light":"min-light","dark":"min-dark"}} [machine] mem_size_mib = 4096 vcpu_count = 2 fs_size_mib = 8192 [rootfs] name = "default" [kernel] name = "default.bin" ``` ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} vers run --vm-alias golden vers connect ``` ### Install Your Agent Runtime Inside the VM, install whatever agent framework you use: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} 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 ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} 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: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} vers run-commit --vm-alias worker-server vers run-commit --vm-alias worker-client vers run-commit --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. ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} 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: ```markdown theme={"theme":{"light":"min-light","dark":"min-dark"}} # 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 ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} # 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:** ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} vers checkout worker-server vers connect cd /root/workspace export ANTHROPIC_API_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:** ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} vers checkout worker-client vers connect cd /root/workspace export ANTHROPIC_API_KEY= # "Read SPEC.md. Build public/game.html, public/game.js, public/style.css per the Client section." ``` **Terminal 3 — Landing worker:** ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} vers checkout worker-landing vers connect cd /root/workspace export ANTHROPIC_API_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: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} # Execute a command on a VM without interactive SSH vers execute worker-server "cd /root/workspace && ANTHROPIC_API_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= 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= 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: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} 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: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} vers copy output/ worker-server:/root/workspace/ --recursive ``` ### Verify ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} 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.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: ```javascript theme={"theme":{"light":"min-light","dark":"min-dark"}} server.listen(3000, "::"); ``` See [Networking](/networking) for the full details. ## Step 7: Clean Up ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} vers kill worker-server vers kill worker-client vers kill worker-landing ``` Or kill the golden image recursively to remove everything: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} 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](https://github.com/badlogic/pi-mono), the [pi-v extensions](https://github.com/hdresearch/pi-v) 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](/tutorials/pi-extensions) 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 Wire Vers into your agent framework so swarms spawn with a single tool call. Every flag on the branch primitive. Orchestrate swarms programmatically from your own code. How copy-on-write and content-addressable commits actually work.