Content-addressed repos

This is the main way to use iroh-forge. A content-addressed repo has no home server. Its id is an Ed25519 public key, and anyone who holds a copy can serve it.

iroh-forge new                       # prints iroh://<repo-id> (52 characters)
git push iroh://<repo-id> main
git clone iroh://<repo-id>           # works from any machine with the id

How it works

• Repo id = public key. The matching secret key lives in ~/.iroh-forge/repos/<repo-id>.key; only holders of it can push.
• State = one BLAKE3 hash, the root of an iroh-blobs HashSeq [manifest, pack, pack, …]. The manifest lists refs and HEAD; each push adds one self-contained git pack with only the objects the repo didn't have.
• Pointer = a signed BEP 44 record on the BitTorrent Mainline DHT under the repo key, holding the root hash. Pushes update it with compare-and-swap, so a stale writer gets "fetch first" instead of silently overwriting.
• Providers = nodes holding the blobs announce themselves on the DHT under an infohash derived from the repo id (n0's global content discovery). A clone looks up the record, finds providers, and downloads with iroh-blobs.

Nothing is tied to one host: the pusher can go offline as soon as the push returns, and the clone needs only the repo id.

Pinners

Someone holding a copy has to be online when another agent clones. A pinner is any machine running iroh-forge serve; it keeps copies, serves blobs, announces itself on the DHT, and re-publishes each repo's record so it doesn't expire.

# on the always-on machine
iroh-forge serve ~/forge
iroh-forge allow <pusher's client id>     # who may ask it to pin

# on the pusher
iroh-forge pinner add <pinner's server id>

A push sends the new version to every configured pinner (plus this machine's own serve, if it has one) and publishes only after at least one has it. Several pinners can hold the same repo. To have a pinner follow a repo someone else pushes: iroh-forge pin iroh://<repo-id> --on <pinner id>.

n0 runs address-index servers and relays but does not host content, so the pinner is yours: a small always-on VM, a NAS, or a desktop.

Handing off write access

iroh-forge repo export iroh://<repo-id>   # prints the secret key
iroh-forge repo import <secret>           # on the other agent

Reads are public

Anyone with the repo id can read it. Treat content-addressed repos as public to whoever learns the id; there is no read ACL yet.

Commands

Command	What it does
iroh-forge new	Create a repo key, print iroh://<repo-id>
iroh-forge repo list	Repos this machine can push to
iroh-forge repo export/import	Move the write key between agents
iroh-forge pinner add/list	Where pushes are pinned
iroh-forge pin <repo> [--on <id>]	Ask a pinner to fetch and hold the latest version
iroh-forge serve <root>	Run a pinner (and a v0 server for <root>/<name>.git)

Hosted repos (iroh://<server-id>/<name>) from v0 keep working unchanged.