Notes on radicle

2026-02-08 @equalsraf

radicle has been on my TODO list for a long time now, so this weekend I decided to give it a try. Here are some notes in no particular order.

• radicle 1.6.1 here

Identity

Radicle uses ssh keys as identity mechanism - these are under $RAD_HOME/keys/. They are regular ed25519 keys.

These seem to be bound to the node. I found this part of the docs a bit confusing, probably because I assumed a NID and DID were two different things, but AFAIT they are the same thing i.e. your public ssh key hash.

There is also a Repository Identifier (RID) which is the hash of the initial repository metadata document. This is used as repo identifier (e.g. rad:z41HxAqq8z4HPwEFbd88oSVdpWJ35).

On a side note the RIP documents are easy to read, I actually find them easier than the protocol guide.

A lot of mentions to multi device support online, but it is probably saner to do one key/delegate per device and move on.

Storage

I should note I started my journey by doing (rad init) on all my existing repos. I did not bother to check what this would do, other than advertising my public repos in the network. Everything worked fine and I can find my repos on some of the web interfaces:

• https://app.radicle.xyz/nodes/iris.radicle.xyz/users/z6MkhckjUFXZp3M1R5ri9axHCX4cNLLdKxG2ZHXHhkED9KBB
• https://search.radicle.xyz/

There were some consequences that I should have read on before doing it though:

• the current implementation stored a "copy" of my repo under $RAD_HOME/storage/RID
• this repo copy is a bare git repository
• the radicle metadata (delegates, etc) is stored in this repo under refs namespacs (see git refs list)
• the default (rad init) behaviour only copied my main branch, not my tags, or my other branches

Tags/branches initialization aside. I found this duplication of storage a bit surprising. RIP 0003 explains this "working copy" is connected to the node storage copy via a rad remote i.e. the git remote for pushing is this adddress

rad://z41HxAqq8z4HPwEFbd88oSVdpWJ35/z6MkhckjUFXZp3M1R5ri9axHCX4cNLLdKxG2ZHXHhkED9KBB

which essentially means push to repo with RID z41HxAqq8z4HPwEFbd88oSVdpWJ35, under the namespace z6MkhckjUFXZp3M1R5ri9axHCX4cNLLdKxG2ZHXHhkED9KBB (my NID). This starts making sense once you realize the rad storage holds one set of references in the repository per each node.

My knee-jerk reaction was to think this working copy could be a simple worktree over the bare repo. But I assume the git-remote-rad helper may be doing something more complicated.

I spotted some similar discussions in the radicle zulip but it seems it would require some deep changes to the storage layout:

Canonical

One aspect I completely missed about radicle was the notion of Canonical references. Radicle metadata includes rules to decide which references are to be considered authoritative for a repositoryy based on data from multiple users. This is dynamic and based on e.g. a minimum threshold of maintainers/delegates saying it is canonical.

This is an aspect that the user guide only mentions with a very specific example. While the protocol guide explains it better it does not explain how to use it.

The guide also hints that only the default branch is used for this. So my current predicament is how to make my release tags for existing repos canonical.

My questions were partially answered by this blog post with an example for (rad id).

I ended up editing the document by hand. Not sure if there is a CLI for this.

Personally I find this both exciting and terrifying. Exciting because it is essentially dynamic access control for Git which is really useful. Terrifying because it is another ACL language inside JSON :).

Network connections

It looks like not much work took place inside radicle to support more complicated networking setups:

• listen/external address options to setup a listening socket - but no upnp support to punch through a firewall
• there is socks5 proxy which people use to access ToR or I2P nodes
• I did not dig deep into the code but the listen field seems to be an ip socket addr, so no easy support for UNIX sockets (very useful for ToR or other tunnels)
• it would be nice to have a general mechanism to support other transport protocols (like git remote helper for git) that would allow plugging RIDs to other discovery/network protocols

Concerning that last point I spotted some people doing interesting things online. Personally I would favor something like a tunnel setting for (rad node connect) e.g. rad connect over ssh, unix sockets, pipes from processes.

Funny bit

rad checkout rad://z41HxAqq8z4HPwEFbd88oSVdpWJ35 is invalid (remove rad:// prefix) but git clone rad://z41HxAqq8z4HPwEFbd88oSVdpWJ35 actually works :D

Summary

I have a soft spot for decentralized architectures so of course this is cool. I specially like the storage layout allowing all data for all nodes to live in the repo.