Skip to content

Recommendation

Historical

Written before building. Option C shipped as described in Content-addressed repos; the irepo commands below became iroh-forge new, iroh-forge serve and plain git push / git clone.

Build Option C (pkarr root + HashSeq of packs + Mainline discovery) for the agent hand-off case. Keep Option B's iroh-docs layout in reserve if several agents must write to the same repo at once. The helper, CLI and pinner below apply to both; for Option C read "doc entries" as "root HashSeq + pkarr publish" and "ticket" as "repo key".

irepo init                 # in an existing git repo: create the repo key, import refs + one pack
irepo share [--read]       # print write (default) or read-only id
irepo serve                # long-running node: keeps store, syncs, serves blobs
git clone iroh://<id> myrepo
git push / git fetch       # via git-remote-iroh helper, talks to local `irepo serve`

Hand-off between agents = pass the id string. Done.

How the helper works (remote-helper fetch/push capabilities)

  • list: read refs/* + HEAD from the repo, print <sha> <ref>.
  • fetch <sha> <ref>: for every pack not already indexed locally, download the blob and run git index-pack --stdin into .git/objects/pack/. (Prototype: fetch all packs. Later: per-pack ref tips to skip unneeded ones.)
  • push <src>:<dst>: compute git pack-objects --revs --stdout with <new tip> and ^<every remote ref sha> (non-thin), add as blob, then check fast-forward against the current remote ref (unless +force) and publish the new refs.
  • The helper does not embed a node; it talks to the local irepo serve over iroh's local RPC so data outlives the git process and keeps being served.

Write access hand-off (pick per phase)

  1. Shared write key (prototype). Write = holding the repo secret. Hand off by passing it. Cannot revoke; fine between cooperating agents.
  2. Baton (cheap convention). A writer entry names the EndpointId of the current writer; helpers refuse to push unless it's them; irepo pass <endpoint-id> moves it. Cooperative, not enforced.
  3. Reader-enforced ACL (v2). The owner signs an ACL of writer keys; readers ignore ref updates not signed by a listed writer. Hand off write = owner adds the recipient agent's key; revoke = remove it. Readers enforce it, so no trusted server is needed. Each agent's writer key can be its endpoint key, so "grant to agent X" uses the id you already pass around.

Availability

A repo is only reachable while at least one node holding it is online. For agents in short-lived containers, run one cheap always-on irepo serve (a VPS, a Modal/Fly box, V's machine) that pins every repo, keeps announcing its blobs and republishes its signed record. Clones succeed even when the original agent is gone.