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

# Repo fork

# 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

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

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

## Options

| Option        | Description                                                      |
| ------------- | ---------------------------------------------------------------- |
| `--repo-name` | Name for the repo in your org. Defaults to the source repo name. |
| `--tag-name`  | Name for the tag. Defaults to the source tag name.               |

## Examples

### Fork a supported image

```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…
```

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

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

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

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

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

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

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
vers repo tag delete pi-agent latest
vers repo fork vers/pi-agent:latest
```

### Invalid reference format

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

* [Forking a supported image](/examples/fork-supported-image) - full walkthrough
* [`vers connect`](/cli-reference/connect) - SSH into the forked VM
* [Repositories and Tags](/repositories) - the fork model in detail