Repositories and Tags

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.

​

Why Repos Exist

​

1. Sharing images across accounts

​

2. Organizing your own commits

vers repo create my-app
vers repo tag create my-app latest c7e4a2f1…
vers repo tag create my-app known-good c7e4a2f1…
vers repo tag create my-app pre-migration 9b8d3c10…

​

The Object Model

Organization (your account)
│
├── Repository "my-app"              (private or public)
│   ├── Tag "latest"      → commit c7e4…
│   ├── Tag "v1.0"        → commit 1a2b…
│   └── Tag "staging"     → commit 88ff…
│
├── Repository "internal-tools"      (private)
│   └── Tag "latest"      → commit 4d5e…
│
└── Repository "public-demo"         (public, forkable by others)
    └── Tag "latest"      → commit 9b8d…

• Tags are movable. Moving a tag is a cheap pointer update; the commit it used to point to still exists as long as some VM or other tag still references it.
• Deleting a repo or tag does not delete commits. Commit garbage collection is a separate concern; removing the label doesn’t destroy the artifact.
• Repo names are per-org. Two different orgs can both have a my-app repo; they’re disambiguated by org namespace (acme/my-app vs globex/my-app) for public lookups.
• Names are validated. Repo names: 1-64 characters, alphanumeric plus hyphens, underscores, and dots. Tag names: 1-128 characters, same character set.
• Tagging requires org ownership of the commit. You can only tag commits your org owns. To tag a commit from somebody else’s public repo, fork it first, forking is what actually copies the commit into your org.

​

References: repo:tag and org/repo:tag

​

Where refs are accepted

vers run-commit my-app:latest --ref --vm-alias dev

// Before
{ "commit_id": "c7e4a2f1-…" }

// After
{ "ref": "my-app:latest" }

​

Visibility and Publishing

vers repo visibility my-app --public          # publish
vers repo visibility my-app --public=false    # unpublish

• Any authenticated Vers user can discover it via GET /api/v1/public/repositories
• Any user can read its tags and fork it into their own org
• Your org name becomes part of its public identity: your-org/my-app:latest

​

Forking

1. A new running VM, branched from the source commit (via a copy-on-write clone, so this is fast; it does not boot and re-image a fresh VM)
2. A new commit, captured from that VM, owned by your org
3. A repository (either a new one, or an existing same-named one; see below)
4. A tag pointing at the new commit

vers repo fork vers/pi-agent:latest
# ✓ Forked → pi-agent:latest
#   VM:     vm-7a1c…
#   Commit: c9e4…

vers repo fork vers/pi-agent:latest --repo-name my-agent-base --tag-name v0

​

Fork and existing repos

​

Typical Workflows

​

Personal organization (just tag your commits)

vers run --vm-alias dev
vers connect
# … set up a project, install deps …
exit

vers commit
# → commit c7e4…

vers repo create my-app
vers repo tag create my-app latest c7e4…

# Weeks later, on any machine:
vers run-commit my-app:latest --ref --vm-alias dev

​

Team CI: always-current dev environment

1. Developer creates my-app repo once, makes it public if it should be forkable by contractors, private otherwise.
2. CI action on every merge to main:
   • Forks the previous my-app:latest into a scratch VM (or branches from it)
   • Runs git pull, reinstalls deps, runs migrations, warms caches
   • Commits the VM
   • Points my-app:latest at the new commit with vers repo tag update my-app latest --commit <id>
3. Team members pull the current build with vers run-commit my-app:latest --ref (or the equivalent API call) and land on a pre-baked dev VM matching trunk.

​

Consuming a supported image

# Fork gives you a running VM, a commit, and a tagged repo in your org
vers repo fork vers/python:latest --repo-name py-base --tag-name latest
# ✓ Forked → py-base:latest
#   VM:     vm-2b4a…
#   Commit: f1a7…

# Connect to the VM the fork created
vers connect vm-2b4a…

# Or spin up a fresh VM from the fork's commit later
vers run-commit f1a7… --vm-alias my-py-env

​

Release tagging

# After a successful release build
vers repo tag create my-app v1.4.2 c9e4…
vers repo tag update my-app latest --commit c9e4…

# Roll back latest in a pinch
vers repo tag update my-app latest --commit <previous-commit>

​

CLI Cheat Sheet

​

API Surface

​

Your org’s repositories

​

Tags inside a repo

​

Public discovery (readable by any authenticated user)

​

Using references when restoring VMs

// 1. By commit ID (original form, always supported)
{ "commit_id": "c7e4a2f1-…-…" }

// 2. By legacy org-scoped tag (pre-repos commit_tags)
{ "tag_name": "my-old-tag" }

// 3. By repo:tag reference (new, recommended path for repos)
{ "ref": "my-app:latest" }

​

Behavior Notes and Gotchas

• Deleting a repo keeps its commits. The repo row and its tags are removed (tags cascade via FK). Commits remain reachable through any surviving tag, legacy commit_tags entry, or VM that still references them.
• Deleting a tag keeps the commit. Same reason.
• Tag moves are atomic pointer updates. No VMs are touched by moving my-app:latest from one commit to another; it’s a metadata-only change.
• Fork creates a running VM and a commit. The branching step uses a Ceph CoW clone so it’s fast (seconds, not minutes), even for large images. The step that takes real time is the post-branch commit.
• Fork is a copy, not a reference. No upstream relationship is tracked after completion. If the source repo updates, you won’t see it unless you fork again.
• Fork into existing repo reuses it. Same-name target repo? The fork adds tags to it rather than erroring. A pre-existing tag with the same target tag name will fail the tag insert. Use --tag-name or delete the existing tag first.
• Repo names are unique per-org, not globally. Public references always include the org name (acme/my-app).
• Refs are case-sensitive and exact-match. No @latest parsing, no partial matches.
• Tagging requires org ownership of the commit. You cannot create a tag in your repo that points to a commit another org owns, even if it’s visible via a public repo. The way you “import” someone else’s commit is vers repo fork; the fork re-commits the VM under your org.

​

Related

• Concepts - VMs, HEAD, commits, branching
• vers run-commit - create a VM from a commit ID or repo:tag ref (--ref)
• Forking a supported image - bootstrap an env from a Vers-maintained repo
• CI: maintaining a latest image - team workflow for always-current dev VMs
• API Introduction - broader API walkthrough