git-remote-iroh 0.2.1

Git remote protocol support for https://www.iroh.computer
Documentation

git-remote-iroh

What

Serve and access Git repositories over iroh.

git-remote-iroh is a Git protocol helper that connects repositories over iroh p2p network endpoints.

Why

Git is supposed to be a distributed version control system, right?

How

Install

$ cargo install git-remote-iroh

Clone from iroh

This repository is mirrored at iroh://92fbc10667b6ae60b2b7c158ec3c996ebdeac0f07d6648b87243fe49498bd378.

Make sure git-remote-iroh is in your $PATH.

$ git clone iroh://92fbc10667b6ae60b2b7c158ec3c996ebdeac0f07d6648b87243fe49498bd378 git-remote-iroh
Cloning into 'git-clone-iroh'...
remote: Enumerating objects: 70, done.
remote: Counting objects: 100% (70/70), done.
remote: Compressing objects: 100% (27/27), done.
remote: Total 70 (delta 35), reused 70 (delta 35), pack-reused 0 (from 0)
Receiving objects: 100% (70/70), done.
Resolving deltas: 100% (35/35), done.

Serve a repository

On one machine (physical, virtual, or container):

$ git-remote-iroh --git-dir=/path/to/repo.git
git-remote-iroh-1  | 2026-07-13T02:16:08.493049Z  INFO git_remote_iroh::server: server started addr="iroh://92fbc10667b6ae60b2b7c158ec3c996ebdeac0f07d6648b87243fe49498bd378"

The iroh:// address will log to stderr.

Container quickstart

Install just.

The following recipes build an OCI image, set up volumes with a bare clone of this repository with access granted to the current user on the host, and then serves the repository over iroh.

$ just compose-build
$ just compose-setup
$ just compose-run

The default compose runtime is podman. To use docker: just compose-build docker, etc.

Set up authorization: gathering developer identities

In order to allow remote write access, developers' public key peer identities need to be added to the repository server.

Gather each developer's public key, which they can each obtain with git-remote-iroh whoami:

alice$ git-remote-iroh whoami
ft5g4b13ituz99s69denhjwgx3qhmmzy4so3jj6ie1md5dwyrr1o /var/home/alice/.config/git-remote-iroh/keys/default

bob$ git-remote-iroh whoami
sdazih54na3m6pzwkogcyxbdtfkx1k4nez65rg9yaocwbbfhraao /var/home/bob/.config/git-remote-iroh/keys/default

carol$ git-remote-iroh whoami
qzbemfskctk4e4zmrjbhjg7ufx5rqj4kcej5ehq4dtb3coppj3ay /var/home/carol/.config/git-remote-iroh/keys/default

Set up authorization: granting access on the repository server

On the repository server, add each developer's peer key:

$ git-remote-iroh peer add alice ft5g4b13ituz99s69denhjwgx3qhmmzy4so3jj6ie1md5dwyrr1o
$ git-remote-iroh peer add bob sdazih54na3m6pzwkogcyxbdtfkx1k4nez65rg9yaocwbbfhraao
$ git-remote-iroh peer add carol qzbemfskctk4e4zmrjbhjg7ufx5rqj4kcej5ehq4dtb3coppj3ay

List the server's authorized peers.

$ git-remote-iroh peer
alice ft5g4b13ituz99s69denhjwgx3qhmmzy4so3jj6ie1md5dwyrr1o
bob sdazih54na3m6pzwkogcyxbdtfkx1k4nez65rg9yaocwbbfhraao
carol qzbemfskctk4e4zmrjbhjg7ufx5rqj4kcej5ehq4dtb3coppj3ay

Usage

git-remote-iroh uses GIT_DIR to locate the repository, whether in client or server mode.

Client mode

When performing client operations, git invokes git-remote-iroh to handle iroh:// remote URLs automatically.

Server mode

When serving a repository, git-remote-iroh supports the --config-dir and --git-dir options. These can also be set with environment variables. The included Dockerfile builds an OCI image that uses /config and /repo for these, respectively.

Iroh can't connect to the same public key address that's being served on the same host. The repository server will need to use a distinct public key identity from the one you use to connect to the repository. This can be arranged by setting a different --config-dir, or by running the server in a container.

Serve a bare git clone for best results. Git will refuse receive-pack on a git clone with a working tree, unless specifically configured to allow this (not recommended).

User mode

git-remote-iroh can also be invoked with subcommands to display the user's public key identity or administer a repository server.

See git-remote-iroh --help for details.

Troubleshooting

Set RUST_LOG=git_remote_iroh=debug to see more detailed debug logs. You can also set RUST_LOG=debug which will also add iroh debug messages.

Internals

git-remote-iroh uses iroh-rings to manage authorization. Rings are collections of named peers which can be granted permission to access various resources.

The peer add command does several things:

  • Adds the named peer to a default ring
  • Grants the default ring write access to the push:<repo> resource, read access to the fetch:<repo> resource

The push and fetch operations need to be permissioned separately; iroh-rings does not pass the granted permission to the Transfer implementation. The grant must be bound to the actual operation being performed.

Caveats

Protocol is unstable. No guarantees of compatibility from minor revision 0.x releases. This is still very experimental.

Secret keys are not encrypted at rest.

Access policy is minimal, just enough to enable open source collaboration without total chaos.

Multiple repositories, branch protection, and other typical SCM features are missing.

More ideas

Beyond the above limitations:

  • Leverage SSH public key identities. Bootstrap iroh authentication from SSH keys, or offer iroh+ssh?
  • Leverage DNS records to define access control rings.
  • Local-first SCM built around this. No hubs just spokes.
  • Investigate iroh blobs as an alternative to git protocol.

Credits

Inspired by https://tangled.org/notplants.bsky.social/git-remote-iroh. Originally tried using that project, but it wasn't quite functional and ended up rewriting. I claimed the crate name in crates.io. Hope that's ok.