> ## 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.

# Forking a supported image

> Bootstrap a VM from a Vers-maintained image in seconds

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.

<Info>
  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.
</Info>

## Prerequisites

* Vers CLI [installed and authenticated](/installation)
* 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:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
curl -H "Authorization: Bearer $VERS_TOKEN" \
  https://api.vers.sh/api/v1/public/repositories | jq
```

Response shape:

```json theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  "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:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
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

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
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:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
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:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
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:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
vers connect vm-7a1c…
# or, if you're comfortable picking it up by VM ID via HEAD:
vers checkout vm-7a1c…
vers connect
```

Inside:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
# 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.

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
# 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:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
# 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:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
vers repo fork vers/pi-agent:latest \
    --repo-name agent-base \
    --tag-name "$(date -u +%Y-%m-%d)"
# → agent-base:2026-04-20
```

## Cleanup

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
# 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

* [Repositories and Tags](/repositories) - the full model
* [`vers repo fork`](/cli-reference/repo-fork) - CLI reference
* [CI: maintaining a `latest` image](/examples/ci-latest-image) - the flip side, publishing your own always-current image
* [Agent swarms](/tutorials/agent-swarms) - parallel agents starting from a shared golden image