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 repo fork

Fork a tag from another org’s public repo into your own org. Produces a running VM, a fresh commit, and a repo/tag pointing at that commit, all owned by you.

​
Synopsis

vers repo fork <org>/<repo>:<tag>
vers repo fork <org>/<repo>:<tag> --repo-name <name> --tag-name <name>

​
Description

fork is a one-shot action that:
  1. Resolves the source public reference (org/repo:tag)
  2. Branches a new VM from the source commit (copy-on-write, fast)
  3. Commits the VM, creating a new commit owned by your org
  4. Creates a repo in your org (or reuses an existing same-named one)
  5. Creates a tag in that repo pointing at the new commit
Unlike git fork, there’s no tracked upstream relationship. Once the fork completes, your copy is fully independent. To pull fresh upstream changes later, run vers repo fork again.
The branch step uses a Ceph CoW clone so it’s fast: seconds even for large images. The commit step takes real time relative to the VM’s dirty state, but this is no slower than any other vers commit.

​
Options

OptionDescription
--repo-nameName for the repo in your org. Defaults to the source repo name.
--tag-nameName for the tag. Defaults to the source tag name.

​
Examples

​
Fork a supported image

vers repo fork vers/pi-agent:latest
# ✓ Forked → pi-agent:latest
#   VM:     vm-7a1c…
#   Commit: c9e4…
You now have:
  • A running VM (vm-7a1c…) ready to SSH into
  • A commit c9e4… owned by your org
  • A repo pi-agent in your org with tag latest pointing at that commit

​
Fork with renaming

vers repo fork vers/python:latest --repo-name py-base --tag-name v0
# ✓ Forked → py-base:v0
Useful when:
  • The source repo name collides with one you already have (and you don’t want the tags to mix)
  • You want a versioned tag from the start (v0, baseline, initial, etc.)
  • The upstream tag name is ugly

​
Fork into an existing repo

vers repo fork vers/python:latest --tag-name python-latest
vers repo fork vers/node:latest --repo-name py-and-node --tag-name node-latest
# Collect multiple supported images under a single local repo if you want to.
When the target repo already exists in your org, fork adds a tag to it instead of erroring.

​
Fork, then use immediately

vers repo fork vers/pi-agent:latest --repo-name agent-base
vers connect vm-7a1c…          # SSH into the VM the fork created

​
Error Cases

​
Source not found

vers repo fork vers/nonexistent:latest
# Error: Source repository or tag not found (must be public)
The source org must exist, the repo must be marked public, and the tag must exist in it.

​
Target tag already exists

Forking with default names twice in a row will succeed the first time and fail the second: 
vers repo fork vers/pi-agent:latest
# ✓ Forked → pi-agent:latest

vers repo fork vers/pi-agent:latest
# Error: ... tag already exists
Solution: pass --tag-name to pick a different name, or delete the existing tag first: 
vers repo tag delete pi-agent latest
vers repo fork vers/pi-agent:latest

​
Invalid reference format

vers repo fork vers-pi-agent
# Error: invalid reference 'vers-pi-agent': expected format org/repo:tag
All three parts are required: org, repo, tag. No :latest shorthand.

​
See Also