radicle-lfs-transfer

A Git LFS custom transfer agent that backs large file storage with IPFS, for use with Radicle repositories.

This is the companion binary for the rad lfs support added in radicle-heartwood-lfs (a fork of Radicle's core node/CLI, heartwood). Most people want to start there, not here — that repo has the full zero-to-usable setup guide. This repo is what you're reading if you want to build/understand the transfer agent on its own, or you're following a link back from there.

rad-lfs-transfer is not meant to be invoked directly — git lfs spawns it automatically, once a repository has been set up with rad lfs init (from the fork above).

How it works

Instead of a shared, seed-hosted LFS server, every peer uses their own local IPFS node:

• On git add/git commit, a pre-commit hook (installed by rad lfs init) adds each staged LFS-tracked file to your local IPFS daemon, pins it, and records the resulting CID as a git note (refs/notes/rad-lfs) attached to the LFS pointer file's own git blob hash. That notes ref travels with the repository via Radicle's normal replication, alongside everything else.
• rad-lfs-transfer implements the other half: when git lfs push/pull runs, it's invoked per-object over stdin/stdout JSON (the standard Git LFS custom-transfer-agent protocol) and:
  • upload: confirms the object is already pinned in IPFS (it should be, from the pre-commit hook) or adds it if the hook was bypassed.
  • download: reconstructs the expected pointer blob hash from the requested oid/size, looks up its cid= note, and fetches the content from your local IPFS daemon (which will pull it from the wider IPFS network if it isn't local yet).

There is no central server anywhere in this design — see radicle-heartwood-lfs's LFS-IPFS.md for the full rationale and how rad seed/rad unseed tie IPFS pinning to Radicle's existing seeding lifecycle.

Dependencies

On Arch Linux:

# To build and install
sudo pacman -S --needed rust git

# To actually use it (not needed to build/install — see "Requirements" below)
sudo pacman -S --needed kubo

On other distributions, install a Rust toolchain (e.g. via rustup), Git, and — only when you want to use LFS, not to build this — Kubo.

Requirements

• Only needed at runtime, not to build or install this binary: a local IPFS (Kubo) daemon reachable at http://127.0.0.1:5001 (or wherever KUBO_API_URL points). If it's not running when git lfs push/pull tries to use it, you'll get a clear error telling you to start one (ipfs daemon) — nothing fails silently, and nothing about building or installing this binary requires IPFS to be present at all.
• Git LFS installed (git-lfs on your PATH) — git-lfs package on Arch (sudo pacman -S --needed git-lfs).

Build & install

git clone ssh://git@git.hswro.org:9022/mab122/radicle-lfs-transfer.git
cd radicle-lfs-transfer
cargo install --path .

This installs the rad-lfs-transfer binary to ~/.cargo/bin by default — make sure that's on your PATH. If you're installing it alongside radicle-heartwood-lfs (the usual case), install it to that project's shared root instead so everything ends up in one place:

cargo install --path . --force --locked --root ~/.radicle

(You normally don't need to clone this repo separately at all for that — radicle-heartwood-lfs includes it as a git submodule and its own setup instructions cover installing both together.)

Configuration

Environment variable	Default	Purpose
KUBO_API_URL	http://127.0.0.1:5001	Base URL of your local Kubo HTTP RPC API

You normally don't need to set this yourself — rad lfs init wires up everything else (the transfer-agent config, the pre-commit hook, and the notes-ref refspecs) automatically.

License

Licensed under either of Apache License, Version 2.0 or MIT license at your option.