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.

Vers publishes a small set of supported images: curated VM snapshots that the Vers team maintains and rebakes on a regular cadence. This guide walks through discovering them, forking one, and using the result.

​
The currently supported set

Under the vers org, rebaked regularly so :latest stays current:
ReferenceContents
vers/node:latestNode.js LTS + npm + git + curl + nginx + iproute2
vers/python:latestPython 3 + pip + venv + git + curl + nginx + iproute2
vers/rust:latestRust stable + cargo + git + curl + nginx + iproute2
vers/go:latestGo 1.22 + git + curl + nginx + iproute2
vers/pi-agent:latestpi coding agent with tmux/FIFO scaffold, ready for remote driving
vers/cc-agent:latestClaude Code pre-installed and configured
Other public repos may exist from other organizations. The list above is specifically the ones we actively maintain for outside use.
Supported images are rebaked on a monthly cadence (or sooner when toolchains bump). <name>:latest always points at the current build. If you need to pin a specific build forever, capture the commit ID at fork time and use that commit ID directly later.

​
Prerequisites

​
Step 1: Discover what’s available

The supported images listed above are the ones you’ll reach for 95% of the time. For the broader public catalog (anything any org has made public), hit the public endpoint: 
curl -H "Authorization: Bearer $VERS_TOKEN" \
  https://api.vers.sh/api/v1/public/repositories | jq
Response shape: 
{
  "repositories": [
    {
      "repo_id": "…",
      "org_name": "vers",
      "name": "pi-agent",
      "full_name": "vers/pi-agent",
      "description": "pi coding agent, tmux/FIFO scaffold, ready to be driven remotely",
      "created_at": "2026-04-01T00:00:00Z"
    }
  ]
}
To see what tags a particular repo exposes: 
curl -H "Authorization: Bearer $VERS_TOKEN" \
  https://api.vers.sh/api/v1/public/repositories/vers/pi-agent/tags | jq

​
Step 2: Fork the one you want

vers repo fork vers/pi-agent:latest
# ✓ Forked → pi-agent:latest
#   VM:     vm-7a1c…
#   Commit: c9e4…
What just happened in your org:
  1. A VM (vm-7a1c…) was branched from the upstream commit and is running now
  2. A new commit (c9e4…) was created from that VM, owned by you
  3. A repository named pi-agent was created
  4. A tag latest was added to the repo, pointing at your new commit
You can see them: 
vers repo get pi-agent
vers repo tag list pi-agent
vers status   # shows vm-7a1c… as running

​
Naming it differently

If you already have a pi-agent repo, or just prefer different names: 
vers repo fork vers/pi-agent:latest \
    --repo-name agent-base \
    --tag-name v0
# ✓ Forked → agent-base:v0

​
Step 3: Use the VM

The fork handed you a running VM. SSH in and start working: 
vers connect vm-7a1c…
# or, if you're comfortable picking it up by VM ID via HEAD:
vers checkout vm-7a1c…
vers connect
Inside: 
# vers/pi-agent images have the agent runtime pre-installed
pi --version
node --version
python3 --version

​
Step 4: Branch or re-commit as you iterate

Your forked commit is a clean starting point. As you customize the VM (adding project code, installing extra libraries, configuring dotfiles) you’ll want to save that work as a new commit and probably update or add tags. 
# After configuring things
vers commit
# ✓ Commit a8b3… created

# Save it under a meaningful tag
vers repo tag create agent-base v0-configured a8b3… \
    -d "My personal customizations on top of v0"

# Or advance latest
vers repo tag update agent-base latest --commit a8b3…
Now anyone on your team with access to your org can vers run-commit a8b3… or use the ref form via the API to spin up that exact state.

​
Step 5: Pulling upstream updates later

Forks are copies, not references. When the upstream vers/pi-agent:latest moves forward (say, Vers rebakes with a new pi release), your fork doesn’t auto-update. Pull the new version when you want it: 
# Delete the stale tag in your repo
vers repo tag delete agent-base latest

# Fork again
vers repo fork vers/pi-agent:latest --repo-name agent-base --tag-name latest
Or keep historical versions side by side: 
vers repo fork vers/pi-agent:latest \
    --repo-name agent-base \
    --tag-name "$(date -u +%Y-%m-%d)"
# → agent-base:2026-04-20

​
Cleanup

# Stop using the VM but keep the fork around for later
vers kill vm-7a1c…
# The commit and tag in your repo remain; you can `run-commit` from them anytime.

# Or nuke everything (keeps commits)
vers repo delete agent-base

​
Why forks are fast

The branch step of vers repo fork uses a copy-on-write clone. The source commit’s blocks aren’t re-read or re-copied; your new VM just starts pointing at the same underlying storage, with writes diverging lazily. So even for multi-gigabyte images, the fork call returns in seconds. The only real time cost is the post-branch commit (same cost as any vers commit) and network round-trips.

​
See Also