Connect a Git repository

Connecting a Git repository makes CAVS the backend for its large files. Your source, history and pull requests stay exactly where they are.

What “connected” means

Four things get wired up:

#	What	Why
1	lfs.url points at …/repositories/{id}/lfs	Git LFS talks to CAVS instead of your Git host’s LFS
2	cavs-lfs-agent registered as a standalone transfer agent	chunk-level dedup on push and pull
3	A pre-push hook	uploads the Git index so the dashboard can show files, commits and branches
4	cavs.repo-id / cavs.api-base in git config	so cav knows which repository this working tree belongs to

The one-command path

1. Have the tools. cav, cavs-lfs-agent and git-lfs:

   curl -fsSL https://raw.githubusercontent.com/orelvis15/cavs-hub-cli/main/install.sh | sh
   git lfs version   # install git-lfs separately if this fails

   The installer places both cav and cavs-lfs-agent in /usr/local/bin (or ~/.local/bin when that isn’t writable).

2. Sign in, pointing the CLI at production:

   cav config set api https://cavsnode.com
   cav login

3. Connect, from inside the Git working tree:

   cav repo connect acme-ai/vision-models

   Output tells you what it configured, and the initial index backfill runs at the end.

4. Verify:

   cav doctor
   git config --get lfs.url
   git config --get lfs.standalonetransferagent   # → cavs

Useful flags:

cav repo connect acme-ai/vision-models --skip-lfs    # only set lfs.url, don't wire the agent
cav repo connect acme-ai/vision-models --skip-index  # no pre-push hook, no initial backfill
cav repo connect acme-ai/vision-models --agent-path /opt/cavs/cavs-lfs-agent

Track your large files

Connecting doesn’t decide which files go to CAVS — Git LFS does, through .gitattributes:

git lfs track "*.safetensors"
git lfs track "*.ckpt"
git lfs track "*.parquet"
git lfs track "assets/**/*.pck"
git add .gitattributes
git commit -m "Track large files with LFS"

Caution

git lfs track only affects files committed after it. Files already in history stay as regular Git blobs. To convert existing history, use git lfs migrate import --include="*.safetensors" — it rewrites commits, so coordinate with everyone who has a clone.

The manual path

If you’d rather not run the CLI, or you’re scripting a fleet, the four config lines are all there is. Get them from the API:

curl -sS "https://cavsnode.com/api/v1/repositories/$REPO/connect" \
  -H "Authorization: Bearer $CAVS_TOKEN" | jq

Response (abridged)

{
  "repository_ref": "acme-ai/vision-models",
  "endpoint": "https://cavsnode.com/api/v1/repositories/0f8c…",
  "lfs_url": "https://cavsnode.com/api/v1/repositories/0f8c…/lfs",
  "git_config": [
    "git config lfs.standalonetransferagent cavs",
    "git config lfs.customtransfer.cavs.path cavs-lfs-agent",
    "git config lfs.customtransfer.cavs.concurrent false",
    "git config lfs.url https://cavsnode.com/api/v1/repositories/0f8c…/lfs"
  ]
}

With the CAVS agent

git lfs install --local
git config lfs.url                          "$LFS_URL"
git config lfs.standalonetransferagent      cavs
git config lfs.customtransfer.cavs.path     cavs-lfs-agent
git config lfs.customtransfer.cavs.concurrent false

Chunk-level dedup, range-resumed pulls, per-object physical stats, benchmarks.

Standard git-lfs only

git lfs install --local
git config lfs.url "$LFS_URL"

That’s it — no extra binary. Whole-file transfers via the basic adapter and presigned URLs. Identical files are still stored once. See Git LFS.

Authenticating git-lfs

Git LFS needs a credential for lfs.url. Easiest is the Git credential helper:

git config credential.helper store
# On the first transfer, enter any username and your CAVS token as the password.

Or set it non-interactively — useful in CI:

git config http.extraHeader "Authorization: Bearer $CAVS_TOKEN"

Caution

http.extraHeader applies to every HTTP request from that repository, including to your Git host. Scope it to the CAVS origin instead:

git config --add http.https://cavsnode.com/.extraHeader "Authorization: Bearer $CAVS_TOKEN"

Cloning on a second machine

With the CLI

cav clone [email protected]:acme/vision.git --connect acme-ai/vision-models

Clones, then runs the connect flow inside the new working tree.

By hand

GIT_LFS_SKIP_SMUDGE=1 git clone [email protected]:acme/vision.git
cd vision
cav repo connect acme-ai/vision-models
git lfs pull

GIT_LFS_SKIP_SMUDGE=1 stops LFS from trying to fetch objects from the wrong endpoint before CAVS is configured. Once connected, git lfs pull fetches them through CAVS — only the chunks the local cache lacks.

Starting from scratch

cav init my-project
cd my-project
# create the repository in the dashboard, then:
cav repo connect acme-ai/my-project
git lfs track "*.bin"
git add . && git commit -m "Initial commit"
git remote add origin [email protected]:acme/my-project.git
git push -u origin main

Indexing

The pre-push hook keeps the index current, but you can drive it directly:

cav repo index --full                 # backfill all branches and tags
cav repo index                        # incremental, since the Hub's known heads
cav repo index --ref main --ref dev   # specific refs only
cav repo index --dry-run              # show what would be uploaded

Run --full after a history rewrite, after enabling indexing on an old repository, or when the dashboard’s Files tab looks stale. The hook is best-effort by design — it never blocks or fails a push.

Disconnecting

git config --unset lfs.url
git config --unset lfs.standalonetransferagent
git config --unset lfs.customtransfer.cavs.path
git config --unset lfs.customtransfer.cavs.concurrent
git config --unset cavs.repo-id
git config --unset cavs.api-base
rm -f .git/hooks/pre-push          # or edit out the `cav hook pre-push` line

Objects already stored stay in CAVS; nothing is deleted. Delete the repository if you want the bytes gone.

Next

• Pushing & pulling large files — the daily loop.
• CAVS LFS agent — configuration and tuning.
• Troubleshooting — when a transfer misbehaves.