Forking a supported image

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:

Reference	Contents
`vers/node:latest`	Node.js LTS + npm + git + curl + nginx + iproute2
`vers/python:latest`	Python 3 + pip + venv + git + curl + nginx + iproute2
`vers/rust:latest`	Rust stable + cargo + git + curl + nginx + iproute2
`vers/go:latest`	Go 1.22 + git + curl + nginx + iproute2
`vers/pi-agent:latest`	pi coding agent with tmux/FIFO scaffold, ready for remote driving
`vers/cc-agent:latest`	Claude 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

Vers CLI installed and authenticated
Network access to api.vers.sh

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:

A VM (vm-7a1c…) was branched from the upstream commit and is running now
A new commit (c9e4…) was created from that VM, owned by you
A repository named pi-agent was created
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.

Tutorials

Examples

Agent Guides

Forking a supported image

The currently supported set

Prerequisites

Step 1: Discover what’s available

Step 2: Fork the one you want

Naming it differently

Step 3: Use the VM

Step 4: Branch or re-commit as you iterate

Step 5: Pulling upstream updates later

Cleanup

Why forks are fast

See Also

​The currently supported set

​Prerequisites

​Step 1: Discover what’s available

​Step 2: Fork the one you want

​Naming it differently

​Step 3: Use the VM

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

​Step 5: Pulling upstream updates later

​Cleanup

​Why forks are fast

​See Also

The currently supported set

Prerequisites

Step 1: Discover what’s available

Step 2: Fork the one you want

Naming it differently

Step 3: Use the VM

Step 4: Branch or re-commit as you iterate

Step 5: Pulling upstream updates later

Cleanup

Why forks are fast

See Also