--- title: Radicle User Guide subtitle: A fantastic journey through the Radicle universe banner: 16.medium.png layout: guide --- Software is *the* fundamental way in which we interface with data that comprises our current reality, and code is the language of software. Most software systems were created through a collaborative process involving multiple people. If we accept that software is important and collaborative by nature, then a shared system for communicating about code and collaborating is needed. This system shouldn't be owned by one company, as code is too important to be monopolized. Furthermore, our world is increasingly polarized, and this reality is finding its way into software companies and therefore into software products. Users are banned from using a platform because of their geographic location or the ideas they stand for. This is not tenable. This is why weโve created Radicle, an open protocol that enables users like you to collaborate on your code within a sovereign network. It's a neutral environment where you have full ownership of your data and you have the autonomy to set the rules of your code universe as you see fit. You can work on software projects (and ultimately more) even when offline, while also being connected to a broader network, through which you'll eventually be able to find contributors. We've created this Radicle Guide to initiate you as a settler of our network through teaching you how to use the software we've developedโthe Radicle CLI, which is both a node and command line interface tool for interacting with the protocol. This guide is split into multiple chapters and we recommend starting with the first chapter for a higher level introduction that takes you on a tour through Radicle's core functions. Subsequent chapters will provide deeper dives into specific use cases, but they are still in progress. > ๐พ > > Greetings, I'm your guide! Whenever you see ๐พ, it's because I've got > some spicy tips on how to use Radicle. You'll also see ๐ฅท for privacy > tips, ๐ป for things you should be wary of, and ๐ง for opportunities to learn > more. > > If you ever get stuck and want additional guidance, join us in our > [chatroom][zulip] on Zulip and ask your questions in the `#support` channel. > > Also, this guide teaches you how to use Radicle in a narrative fashion. If > you're looking for more straightforward usage docs, check out the Radicle > manual or the [Protocol Guide][proto] for more information on Radicle's > fundamental building blocks and motivations. ## 1. Getting Started One of the important facts to understand about Radicle is that it is a peer-to-peer protocol, which is uncommon when it comes to software you typically rely on. Most collaboration technologies are hinged upon a client-server model, where you're entrusting your data and social interactions to a single entity that is managing a bunch of servers or data centers. This paradigm is transformed in a peer-to-peer protocol, where every user of the protocol is a *peer*, participating equally. Peers on the Radicle network are also referred to as **nodes**, and it doesn't matter what you are doing -- whether you're publishing repositories or discussing issues -- you have to run a node. Within a few paragraphs, you'll be operating a Radicle Node via the command line by installing the Radicle software stack. It's a pretty easy process that can be completed in under 5 minutes, but there are a few requirements that are important to run through before you proceed: 1. You need a Linux or Unix based operating system like macOS or Ubuntu and a basic understanding of how to use your terminal. 2. Radicle is built on top of Git, so a recent version of Git (2.34.0 or later) is recommended. We also assume you have *some* experience using Git. 3. OpenSSH (version 9.1 or later) with ssh-agent has to also be installed and running. This is a helper program that is used to secure the secret key related to your Radicle identity. > ๐พ > > You can check your Git and SSH installations by running `git > --version` or `ssh -V` in your terminal. > > If you haven't used Git before, you're going to be in a world of pain and > should read through the [Pro Git][pro-git] book first. [pro-git]: https://git-scm.com/book/en/v2 ### Installation The easiest way to install Radicle is by firing up your terminal and running the following command: $ curl -sSf https://radicle.xyz/install | sh This command runs an installer script that automates the setup process, by: * Identifying your OS, and installing Radicle binaries suitable for your system, including `rad`, `git-remote-rad`, `radicle-node`, and `radicle-httpd`, all placed in `~/.radicle/bin` by default. This is a non-standard location, so the script also updates your `PATH` variable to include the path to these binaries. * Installing `man` pages into `~/.radicle/man`, which enables you to access the Radicle CLI user manual through `man rad` or `rad help`. > ๐พ > > If you want the above to be installed in a different location than > `~/.radicle`, you can pass `--prefix` to the installation script, eg. > `--prefix=/usr/local`. > > Note that if you don't want to use the installer script, you can also always > compile from the [source code][heartwood] or get the [binaries][] if you > prefer. [heartwood]: https://app.radicle.xyz/seeds/seed.radicle.xyz/rad:z3gqcJUoA1n9HaHKufZs5FCSGazv5 [binaries]: https://radicle.xyz/download Once you've installed Radicle, you can make sure that it was successful by running: $ rad --version ### Come into being from the *elliptic aether* When using Radicle for the first time, you have to create a new Radicle identity, which is simply a cryptographic key pair, using the `rad-auth` command. The public key is what uniquely identifies you across the network, while the private key is used to authenticate your node, as well as sign code and other artifacts you publish on the network. $ rad auth That's how you'll cryptographically forge your new Radicle identity. Follow the instructions by entering an **alias**, a non-unique name that makes it easier to identify your node, in addition to a **passphrase** to protect your key pair. Note that your alias can always be changed at a later time. $ rad auth Initializing your radicle ๐พ identity โ Enter your alias: paxel โ Enter a passphrase: ******** โ Creating your Ed25519 keypair... โ Adding your radicle key to ssh-agent... โ Your Radicle DID is did:key:z6Mkhp7VUnuufpvuQ3PdysShAjL86VDRUpPpkesqiysDBGs9. This identifies your device. Run `rad self` to show it at all times. โ You're all set. ... When you've completed the steps, your new Radicle DID (Decentralized Identifier) will be generated and displayed. If `ssh-agent` is running, your private key will also be added to it for future use. While similar to your Node ID (NID), the Radicle DID is formatted as a [Decentralized Identifier][did], whereas the NID is simply the encoded public key. The Radicle DID is your own [self-sovereign][ssi] identity. Share it freely with collaborators! [ssi]: https://en.wikipedia.org/wiki/Self-sovereign_identity If you run `rad auth` again you can verify that your key was added to `ssh-agent`. $ rad auth โ Radicle key already in ssh-agent > ๐ป > > If you plan on using multiple devices, it is very important that you do not try > to share your Radicle identity across those devices. > > At the moment, each device is required to be identified by its own DID, > meaning you have to go through the `rad auth` process on each device you plan > on using. > > We understand the desire and need to link devices to make collaboration smoother. > We are in the process of designing and implementing this functionality. If you forget your DID or NID, you can query your full identity by running `rad self` or alternatively you can grab your DID with `rad self --did` and your NID with `rad self --nid`. ``` $ rad self Alias paxel DID did:key:z6Mkhp7VUnuufpvuQ3PdysShAjL86VDRUpPpkesqiysDBGs9 โโดNode ID (NID) z6Mkhp7VUnuufpvuQ3PdysShAjL86VDRUpPpkesqiysDBGs9 SSH running (3817) โโดKey (hash) SHA256:YCmRe6BkDOp45lYg0m5DeYxgRcPKftQZb4RmQD1nkjQ โโดKey (full) ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIO9xo9DHlsZJeZWnZaaawsnKFjcQxN4LQโฆ Home /home/paxel/.radicle โโดConfig /home/paxel/.radicle/config.json โโดStorage /home/paxel/.radicle/storage โโดKeys /home/paxel/.radicle/keys โโดNode /home/paxel/.radicle/node ``` This displays your alias, DID, Node ID, SSH agent status, SSH keys, and the locations of important files or directories. > ๐พ > > Many of the other items you see in the `rad self` output can be viewed > individually. Wondering about your alias? A quick `rad self --alias` has you > covered. Need to pinpoint your Radicle home folder? `rad self --home` is your > friend. And for your config file location, just hit up `rad self --config`. > > If you're ever feeling lost, `rad self --help` will lay out all your options. ### Operate nodes, smoothly Now that your node has an identity (or 'public key'), you have what it takes to connect to the Radicle Network. That's right -- we don't need your email address or any other personal identifying information. Your alias can be your cat's name for all we care. The first command to embed deep within your consciousness is the one for checking your node's status: $ rad node status If the node is not running, you can start it as a background daemon with: $ rad node start After your node starts, it will attempt to connect to peers on the network. But let's take a step back and ponder some fundamental questions: *What exactly happens when these nodes interact? And how does Git fit into this picture?* At its core, Radicle marries Git with peer-to-peer networking. Your node isn't just another cog in the machine; it's a conduit for collaboration. It's there *to host and synchronize repositories you're interested in*. Radicle's peer-to-peer architecture draws inspiration from [Secure Scuttlebutt's][ssb] gossip protocol where data transmission relies on a publish/subscribe system, allowing peers to host and sync only the data they care about. Similar to [BitTorrent][bt], we use the terminology "seeding" to describe distributing and sharing a repository across the network. With Radicle's gossip protocol, peers exchange messages about the network that facilitate the discovery and replication of repositories. The replication process kicks off when a node establishes a secure connection with another node, the initiating node conducts a *fetch* operation via the Git protocol to pull the pertinent objects into the node's storage, thereby availing them to the local user and other interested nodes. > If you're curious about how Radicle works under the hood, read our > [Protocol Guide][proto]. ### Git going with repositories Now, time to return to your terminal. The next thing we'll do is publish a repository to the Radicle network. Once we've done this, anyone with a node will be able to fetch and seed your repository, increasing its replica count on the network. Pick a repository you maintain and navigate to a local copy. It can be any Git repository, but it should have at least one commit. $ pwd /home/paxel/src/dark-star $ git status On branch master Your branch is up to date with 'origin/master'. nothing to commit, working tree clean To publish it to the Radicle network, run the `rad init` command. $ rad init Initializing radicle ๐พ project in . โ Name: dark-star โ Description: Decoding data from the dark star to establish a model of the universe โ Default branch: main โ Visibility: public โ Project dark-star created. Your project's Repository ID (RID) is rad:z31hE1wco9132nedN3mm5qJjyotna. You can show it any time by running `rad .` from this directory. โ Project successfully announced to the network. Your project has been announced to the network and is now discoverable by peers. You can check for any nodes that have replicated your project by running `rad sync status`. To push changes, run `git push`. Don't be afraid to do this on one of your existing public repositories! Because even if you aren't ready to use Radicle for code collaboration, it works great for distribution. Radicle's network of seed nodes help propagate and host code, forming a decentralized, censorship resistant, and ungovernable distribution system. What `rad init` does is gather the essential details from you which are needed to initialize the repository into Radicle: the repository name, description, default branch (typically `main` or `master`), and whether it is public or private. Similar to how `git init` is used to initialize a Git repository, we use nomenclature you're familiar with so you don't go crazy. That'd be so cruel if you had to do `rad new`, instead, wouldn't it? > ๐ป > > It's important to only publish repositories you own or are a maintainer of, > and to communicate with the other maintainers so that they don't initialize > redundant repository identities. After entering your repository details, you're presented with a Repository Identifier (RID) that is a globally unique URN that you can share with your collaborators or friends so that they can clone or seed your repository. Besides generating the RID, `rad init` creates a special Git remote in your working copy named `rad` and publishes the repository to the network (assuming it's public). We'll talk more about private repositories in another chapter. When you initialize a repository you are the sole maintainer or *delegate*, the term used in Radicle. Delegates can represent a group, person or even a bot. In your case, I'm assuming you're a person. Delegates can be added or removed from a repository, by existing delegates. We'll talk about this more in one of the next chapters. > ๐พ > > A few spicy commands you might want to know about, that can be run within a > repository you've initialized: > > * It's difficult to memorize RIDs. Use `rad .` to display the current > repository's RID. > * To display the repository's identity payload, which contains its name, > description and default branch, run `rad inspect --payload`. > * To be able to push changes to a repository from all of your devices, simply > add each device's DID as a repository delegate, using `rad id update`. > * For more details on managing the repository's identity, including adding > delegates, or making updates to its name, description, and visibility, refer > to `rad id --help`. > > By the way since your Radicle key is a valid SSH key, it can be used to sign > Git commits since version Git `2.34.0`. This is an alternative to the more > common GPG signing method. If you'd like to setup your repository to use your > Radicle key for signing commits, enter these commands from its working > directory: > > git config user.signingKey "$(rad self --ssh-key)" > git config gpg.format ssh > git config gpg.ssh.program ssh-keygen > git config gpg.ssh.allowedSignersFile .gitsigners > git config commit.gpgsign true > > You can also set this up globally by passing the `--global` option to `git > config`. > > Commit signing is a purely optional step; Radicle internally signs everything > you publish anyway, so don't worry if you don't set this up! Note that your new repository will only be replicated by nodes that you are connected to and either have an open seeding policy, or follow you. Seeding involves both hosting the repository and synchronizing changes with other nodes. In the early stages of the Radicle network, all public repositories are automatically seeded by `seed.radicle.garden` which is a *public seed node* run by the core team. You don't *have* to trust or rely on our public seed node. You can run your own. As more people run them, Radicle becomes more resilient and reliable for code collaboration. > We are always looking to attract more people > that want to operate public seed nodes: if that's you, check out our > [Seeder's Guide][seeder] for more details. ### Publishing *ch-ch-ch-ch-changes*
$ rad issue
โญโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฎ
โ โ ID Title Author โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโค
โ โ 80464b3 Categorize initial dataset paxel (you) โ
โ โ e4255cc Establish data standards for IUI Dark Star Data group paxel (you) โ
โ โ 3e2f653 Add anomalous data from ship 897AF calyx z6MkgomโฆunurCap โ
โ โ badda04 Recruit Neboriens to join IUI and share dark star data calyx z6MkgomโฆunurCap โ
โฐโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฏ
Let's display an issue that looks interesting, using `rad issue show`:
$ rad issue show 3e2f65
โญโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฎ
โ Title Add anomalous data from ship 897AF โ
โ Issue 3e2f653383f0d2fe21ef4e859a25925c364c740a โ
โ Author calyx โ
โ Status open โ
โ โ
โ Before we onboard new IUI members like the Neborians, it is โ
โ important we upload the data from ship 897AF. I just โ
โ reviewed the database and it seems this is missing. โ
โฐโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฏ
The issue, originally opened by Calyx, the repository's delegate, outlines a
task that aligns perfectly with our knowledge area.
> ๐พ
>
> *Full identifiers do not need to be used in most commands!*
>
> Notice that the full identifier is displayed under the `Issue` field. When
> working with COBs, it's always possible to use the first few characters of a
> COB's ID instead of the full hash, as we did above with `rad issue show`.
>
Let's compose a comment, with `rad issue comment`, expressing our interest in
tackling the issue.
$ rad issue comment 3e2f65 --message "I can help."
โญโโโโโโโโโโโโโโโโโโโโโโโโโโฎ
โ paxel (you) now 74faf0e โ
โ I can help. โ
โฐโโโโโโโโโโโโโโโโโโโโโโโโโโฏ
This time, we used the command-line `--message` option to provide a comment,
but if you don't specify any option, you will be prompted to enter a message
via your editor, just like with `rad issue open`.
> ๐ง
>
> Since Radicle's COB types are extensible by users, globally-unique *Type
> IDs*, such as `xyz.radicle.issue` and `xyz.radicle.patch` are used to
> identify them, preventing naming collisions. This reverse domain name
> notation not only houses Radicle's predefined COBs but also accommodates
> user-defined ones.
>
> For example, if a user or organization were to define a new COB type under
> their domain, it might look something like `com.acme.task`, for some
> hypothetical "task" COB under the `acme.com` domain. This extensibility
> allows for an unlimited set of new collaboration primitives to be defined by
> users.
>
> If you're interested in creating a custom COB, pop into our [chatroom][zulip]
> and we can get you started.
### Assigning issues
Now, let's enter Calyx's point of view for a second. Calyx is the maintainer of
the repository and is starting his day, gazing into a fresh terminal window,
where he enters `rad inbox`.
$ rad inbox
โญโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฎ
โ dark-star โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโค
โ 004 โ 3e2f653 Add anomalous data from ship 897AF issue open calyx 1 hour ago โ
โฐโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฏ
The Radicle inbox is like a notifications center, displaying issues and patches
that are newly created or have unread comments or new activity.
> ๐พ
>
> If you run `rad inbox` from a Radicle repository, only notifications
> belonging to this repository will be shown. You can override this by using
> `--all` to show notifications from all repositories. If the command is run
> outside a Radicle repository, all repositories will be displayed.
Calyx decides to display the notification in his inbox with `rad inbox show`,
using the notification number.
$ rad inbox show 4
โญโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฎ
โ Title Add anomalous data from ship 897AF โ
โ Issue 3e2f653383f0d2fe21ef4e859a25925c364c740a โ
โ Author calyx โ
โ Status open โ
โ โ
โ Before we onboard new IUI members like the Neborians, it is โ
โ important we upload the data from ship 897AF. I just โ
โ reviewed the database and it seems this is missing. โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโค
โ paxel z6MkvZwโฆ7aCGq3C 1 hour ago 74faf0e โ
โ I can help. โ
โฐโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฏ
He sees that we (Paxel) left a comment and we're interested in helping with
the issue, and decides to assign it to us with `rad issue assign`.
$ rad issue assign 3e2f653 --add did:key:z6MkvZwzK64f3GuDcAs6dEcje89ddfHkBjS1v9Dkh7aCGq3C
He adds a comment to the issue as well.
$ rad issue comment 3e2f653 --message "Great, I've assigned it to you."
> ๐พ
>
> The `assign` sub-command can be used to add (`--add`) or remove (`--delete`)
> assignees.
As a delegate of `dark-star`, Calyx has the rights to assign this issue. Calyx
can then use `rad issue show`, to confirm that the issue was correctly
assigned:
$ rad issue show 3e2f65
โญโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฎ
โ Title Add anomalous data from ship 897AF โ
โ Issue 3e2f653383f0d2fe21ef4e859a25925c364c740a โ
โ Author calyx โ
โ Assignees paxel z6MkvZwโฆ7aCGq3C โ
โ Status open โ
โ โ
โ Before we onboard new IUI members like the Neborians, it is โ
โ important we upload the data from ship 897AF. I just โ
โ reviewed the database and it seems this is missing. โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโค
โ paxel z6MkvZwโฆ7aCGq3C 6 hours ago 39134b6 โ
โ I can help. โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโค
โ calyx 2 minutes ago 922fac7 โ
โ Great, I've assigned it to you. โ
โฐโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฏ
> ๐พ
>
> There's a lot more that you can do with issues, such as:
>
> * Editing with `rad issue edit`
> * Labeling with `rad issue label`
> * Closing with `rad issue state --closed`
>
> We don't want to overwhelm you though! Check out `rad issue --help` for more
> details.
### Working with *patches*
The collaboration voyage doesn't stop at issues though! In the realm of code,
issues typically lead to *patches*.
Since Calyx has assigned the above issue to us, we'll start working on it by
making the changes in a new branch, and once we're done, we'll open a patch.
Let's dive into it step-by-step.
First, we need to make sure we're in our working copy of the `dark-star`
repository. You can always check the current Radicle repository using the `rad
.` invocation.
$ rad .
rad:z3cyotNHuasWowQ2h4yF9c3tFFdvc
Now, let's create a new branch where we'll add the missing data from ship
897AF, as mentioned in the issue. We happen to have this data right on our
system!
$ git checkout -b anomalous-data-897af
$ cp /var/run/897af.log data/897af.log
$ git add data/
Finally, we commit our changes to the branch.
$ git commit -m "Add anomalous data from ship 897AF"
Now that our changes are committed, we're ready to open a patch. To do so, we
simply push our branch to `refs/patches`, on `rad` remote.
$ git push rad HEAD:refs/patches
Radicle will then open your editor, where the patch title can be edited and a
description can be added. Just like for issues, the first line of text is the
patch title, while the subsequent lines make up the description.
> ๐พ
>
> In the above command, `HEAD:refs/patches` is a *refspec*, where `HEAD` is a
> reference to the last commit in the currently checked-out branch, and
> `refs/patches` is a (magic) reference on the remote side. But you don't have
> to use `HEAD`; any local branch will do. Even an arbitrary commit hash can be
> used to open a patch!
Once we've entered the details describing the patch, we save and exit our
editor. This pushes our commit to the `rad` remote, opening the patch.
โ Patch e5f0a5a5adaa33c3b931235967e4930ece9bb617 opened โ Synced with 8 node(s) To rad://z3cyotNHuasWowQ2h4yF9c3tFFdvc/z6MkvZwzK64f3GuDcAs6dEcje89ddfHkBjS1v9Dkh7aCGq3C * [new reference] HEAD -> refs/patchesIn the above Git output, we see our patch's identifier displayed: e5f0a5a5adaa33c3b931235967e4930ece9bb617 Patches are a type of COB ๐ฝ, just like issues, and this is the SHA-1 hash that uniquely identifies this patch. > ๐พ > > If you want to avoid remembering the `git push rad HEAD:refs/patches` > command, you can add an alias to your local (or global) Git configuration: > > $ git config alias.patch 'push rad HEAD:refs/patches' > > This allows you to create a patch by simply running `git patch`. Use the > `--global` option with `git config` to add the alias to your global Git > config. > ๐ง > > Radicle's patch workflow is implemented using the `git-remote-rad` helper > program developed for Radicle. This program is called by Git when it detects > a push to any `rad://` URL, such as the one under our `rad` remote. In addition to opening a patch, the above `push` command creates a new remote tracking branch and makes it the upstream of our `anomalous-data-897af` branch. Any subsequent push from this original branch will now update the patch, synchronizing our local changes with the network. > ๐ง > > The name of the remote patch branch is always `rad/patches/` followed by the > patch identifier. For example: > > rad/patches/e5f0a5a5adaa33c3b931235967e4930ece9bb617 > We can take a look at remote tracking branches using `git branch --remotes` to understand this better. $ git branch --remotes calyx@z6Mkgom1bTxdh9fMFxFNXFMw3SbXnma6NARdsfcFuunurCap/main rad/main rad/patches/e5f0a5a5adaa33c3b931235967e4930ece9bb617 Here we see three branches: the `main` branch of Calyx (`calyx@z6Mk..`), our own main branch (`rad/main`), and the branch associated with our recent patch (`rad/patches/e5f0a..`). We can also check the commit hashes associated with the `rad` remote references: $ git ls-remote rad e81db74197f48cc5198d9c03cceaec955af82abf refs/heads/main 80b8d420658834afc444a13c03f0c3ff6875a71c refs/heads/patches/e5f0a5a5adaa33c3b931235967e4930ece9bb617 Since the `rad` remote is associated with our published copy of the repository, these are the branch heads that are publicly accessible on the network. ### Updating patches So let's say we'd like to update the patch we just submitted. We found some formatting issues with the log file we included and we'd like to correct it and update the patch. First, let's dive into our editor and fix the formatting: $ vi data/897af.log Then, we commit the changes and push. $ git commit --amend $ git push --force To update the patch, we simply use `git push`. Since we amended the original commit, we have to use the `--force` option when pushing. This is common practice when a patch has been reworked. As with opening a patch, this opens an editor to enter a reason for updating the patch. Leave it blank if you'd like to skip that.
โ Patch e5f0a5a updated to revision 4d0c1156f8ac7af2297d1314cd7556185cd16ae4
โ Synced with 6 node(s)
To rad://z3cyotNHuasWowQ2h4yF9c3tFFdvc/z6MkvZwzK64f3GuDcAs6dEcje89ddfHkBjS1v9Dkh7aCGq3C
+ b766431...80b8d42 anomalous-data-897af -> patches/e5f0a5a5adaa33c3b931235967e4930ece9bb617 (forced update)
We see that the change that was pushed is represented by a new identifier:
4d0c1156f8ac7af2297d1314cd7556185cd16ae4
This identifier represents the current version of the patch. Patch versions,
called *revisions* in Radicle, are immutable. Therefore, each update to a patch
creates a new revision, and patch updates are non-destructive, even when you
force-push.
> ๐พ
>
> If the branch upstream is not set to the patch reference, eg.
> `rad/patches/e5f0a5a..`, you can set it with `rad patch set e5f0a5a`.
As with issues, we can display the patch using the `show` sub-command:
$ rad patch show e5f0a5a
โญโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฎ
โ Title Add anomalous data from ship 897AF โ
โ Patch e5f0a5a5adaa33c3b931235967e4930ece9bb617 โ
โ Author paxel (you) โ
โ Head 80b8d420658834afc444a13c03f0c3ff6875a71c โ
โ Branches anomalous-data-897af โ
โ Commits ahead 1, behind 0 โ
โ Status open โ
โ โ
โ Data from ship 897AF. โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโค
โ 80b8d42 Add anomalous data from ship 897AF โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโค
โ โ opened by paxel (you) (b766431) 58 minutes ago โ
โ โ updated to 4d0c1156f8ac7af2297d1314cd7556185cd16ae4 (80b8d42) 44 minutes ago โ
โฐโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฏ
Notice at the bottom that there is a timeline, with the original patch head
(`b766431`) and the updated head (`80b8d42`) after a new revisions (`4d0c115`)
was created via a patch update.
Revisions are much more than changesets; they can carry useful metadata such as
reviews, comments, and a top-level description that spans all the commits under
it. That's why you see two identifiers for the revision, the first one is the
hash of the revision, and the second is the hash of the code itself (eg. your
branch head).
> ๐ง
>
> All patches start with an *initial* revision. This revision has the same identifier
> as the patch itself, ie. `e5f0a5a5adaa33c3b931235967e4930ece9bb617` in the
> example above.
### Merging patches into the canonical
Now that we've opened a patch, let's switch perspectives again and return to
Calyx-land. Calyx will want to `checkout` the patch, review it, possibly make
changes and run tests, and then `merge` it. Let's walk through this process
together.
First, within the repository, Calyx runs `rad patch` and notices there is a new patch.
$ rad patch
โญโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฎ
โ โ ID Title Author Head + - Updated โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโค
โ โ e5f0a5a Add anomalous data from ship 897AF z6MkvZwโฆ7aCGq3C 80b8d42 +50382 -0 1 hour ago โ
โฐโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฏ
Calyx then uses the `checkout` sub-command of `patch` to switch to the patch:
$ rad patch checkout e5f0a5a
โ Switched to branch patch/e5f0a5a at revision 4d0c1156f8ac7af2297d1314cd7556185cd16ae4
โ Branch patch/e5f0a5a setup to track rad/patches/e5f0a5a5adaa33c3b931235967e4930ece9bb617
When collaborating with peers, itโs often useful to be able to checkout a patch
in its own branch. With a patch checkout, you can browse the code, run tests
and even propose your own revision to the patch.
The `checkout` sub-command switches to a new local branch which has the patch
checked out at a specific revision. By default, the latest of the patch
author's revisions is chosen, but you can specify a different revision using
the `--revision` option. See `rad patch --help` for more information.
> ๐พ
>
> If you'd just like to view the patch changes without checking out the code,
> use the `diff` command!
>
> rad patch diff e5f0a5a
>
It's a rare occasion that someone submits a perfect patch that can be merged
as-is. For example, in some cases a maintainer may want to rebase the patch's commits on top
of the main branch, which could have moved since the patch was proposed.
Calyx will do just that by running the following command from the patch
checkout:
$ git rebase main
This replays the patch's commits on top of the current `main` branch. All
that's left to do is to update the patch itself, with a new revision:
$ git push -o patch.message="Rebased!" --force
โ Patch e5f0a5a updated to revision 1e0596d917725c447106b1efc900bebf4b95a810
โ Synced with 12 node(s)
To rad://z3cyotNHuasWowQ2h4yF9c3tFFdvc/z6Mkgom1bTxdh9fMFxFNXFMw3SbXnma6NARdsfcFuunurCap
* [new branch] patch/e5f0a5a -> patches/e5f0a5a5adaa33c3b931235967e4930ece9bb617
Although Calyx isn't the author of the patch he can propose a new revision. In
fact, *anyone* can do that, and you will see their revision if you follow them!
Since Calyx did a rebase, the `--force` flag was required. Notice also the `-o
patch.message` option; this allows Calyx to directly provide a comment related
to this revision, bypassing his editor.
> ๐ง
>
> Git has something called "push options", these are options that are passed to
> the remote helper and/or server when executing a push, and can be specified
> via `-o $ git remote -v
paxel rad://z3cyotNHuasWowQ2h4yF9c3tFFdvc/z6MkvZwzK64f3GuDcAs6dEcje89ddfHkBjS1v9Dkh7aCGq3C (fetch)
paxel rad://z3cyotNHuasWowQ2h4yF9c3tFFdvc/z6MkvZwzK64f3GuDcAs6dEcje89ddfHkBjS1v9Dkh7aCGq3C (push)
rad rad://z3cyotNHuasWowQ2h4yF9c3tFFdvc (fetch)
rad rad://z3cyotNHuasWowQ2h4yF9c3tFFdvc/z6Mkgom1bTxdh9fMFxFNXFMw3SbXnma6NARdsfcFuunurCap (push)
In the above output, we see the names of the remotes on the left. We see that
the `paxel` remote points to a different namespace than the `rad` remote, which
points to Calyx's namespace. Remotes can also be viewed using `rad remote`:
$ rad remote
paxel z6MkvZwzK64f3GuDcAs6dEcje89ddfHkBjS1v9Dkh7aCGq3C (fetch)
rad (canonical upstream) (fetch)
rad z6Mkgom1bTxdh9fMFxFNXFMw3SbXnma6NARdsfcFuunurCap (push)
Now that a remote is setup, Calyx can fetch our branches with `git fetch`:
$ git fetch paxel
From rad://z3cyotNHuasWowQ2h4yF9c3tFFdvc/z6MkvZwzK64f3GuDcAs6dEcje89ddfHkBjS1v9Dkh7aCGq3C
* [new branch] dark-star-secrets -> paxel/dark-star-secrets
Oh darn, what has he found! If you don't want a branch to be published on
the Radicle network, avoid pushing it to your `rad` remote!
> ๐พ
>
> You can always use `rad remote list --untracked` to find peers that you are
> following but are not tracking in your working copy.
### Synchronizing the canonical
Now that Calyx has updated the repository's `main` branch by merging our patch,
all we need to do is pull those changes ourselves, to have the most up to date
state.
We'll start by switching back to our `main` branch with `git checkout main`,
and then we'll initiate a regular `pull`:
$ git pull
Fetching rad
From rad://z3cyotNHuasWowQ2h4yF9c3tFFdvc
e81db74..25f8515 main -> rad/main
Updating e81db74..25f8515
Fast-forward
...
> ๐ง
>
> The `git pull` command is really just a `git fetch` followed by a `git
> merge`. If you're comfortable with Git, it can be a good idea to first run
> the `fetch`, see which remote-tracking branches were updated, and decide what
> to merge yourself.
There we go, our working copy is now up to date with Calyx's.
If you get `Already up to date.`, it could mean that the changes pushed by
Calyx haven't reached your node yet. In that case, it's a good idea to ask
your node to fetch changes from the network:
$ rad sync --fetch
โ Fetching rad:z3cyotNHuasWowQ2h4yF9c3tFFdvc from z6MkrLMโฆocNYPm7..
โ Fetching rad:z3cyotNHuasWowQ2h4yF9c3tFFdvc from z6Mkg5Zโฆ4Q8qCHw..
โ Fetched repository from 2 seed(s)
After the `sync` command succeeds, try to `git pull` again.
And, that's a wrap! You now know the most relevant nitty gritty details of how
to leverage Radicle for code collaboration.
*One thing to keep in mind is that Radicle doesn't have advanced code review
features yet for patches, but that is coming in a near-term release.*
## 3. Selectively Revealing Repositories
In his influential work, [A Cypherpunk's Manifesto][cyph-man] (1993), Eric
Hughes eloquently encapsulated the essence of privacy, stating: ***Privacy is
the power to selectively reveal oneself to the world.*** This notion of
self-determination and control over one's personal information stands in stark
contrast to the reality of using "private repository" features on traditional
centralized code forges. In those systems, privacy is merely an illusion
maintained by terms of service agreements, as data is stored in cleartext, fully
accessible to the platform's employees, vulnerable to potential misuse or
leaks, and subject to external pressures such as government requests. Users are
left with no real control, forced to blindly trust that their code and data
won't be viewed, exploited, or even used without consent for purposes like
training large language models.
In contrast, Radicle's decentralized approach puts the power of privacy directly
in the hands of users by leveraging public key cryptography and granular access
control mechanisms. The *power to selectively reveal* is a foundational
principle in Radicle, fostering a more resilient and safer environment for
code collaboration. Through selective replication, private repositories are only
accessible to and replicated by repository collaborators, while fully encrypted
connections ensure confidential data transfer between peers.
By combining selective replication and encrypted and authenticated connections,
repositories are invisible to the rest of the network. This approach
effectively creates isolated spaces for private collaboration, forgoing the
need for encryption at rest.
In this chapter, we'll explore how to maintain sovereignty and control over a
private repository while collaborating with a set of peers and a trusted
seed node.
### Initializing a private repository
When a private repository is created in Radicle, it is only visible and
accessible to explicitly authorized peers. Privacy is extended to all aspects of
the repository, including its data, creation time, Repository ID (RID),
Collaborative Objects (COBs), and its set of collaborators.
To maintain this privacy during data transfer, all connections between nodes,
including those to seed nodes, are fully encrypted using an AEAD algorithm,
`ChaCha20-Poly1305`.
To demonstrate how this works in practice, let's create a private repository for
a sensitive research project we're working on with our peer, Calyx. We'll start
by initializing a repository within a new directory named
`schrรถdingers-paradox` and committing our initial research findings:
$ cd schrรถdingers-paradox
$ git init
$ cp ~/secrets/897af-captain.log data/897af-captain.log
$ git commit -a -m "Add captain's log from ship 897AF"
Next, to securely share this with Calyx, we initialize it as a private
repository in Radicle using the `--private` flag:
$ rad init --private
This invocation functions similarly to the public repository initialization
process; the key difference is that it automatically configures the
`visibility` option of the repository to private. As a result, the repository
remains unannounced ๐ฅท and unpublished on the network, reflecting its nature.
$ rad init --private
Initializing private radicle ๐พ repository in /home/paxel/src/schrรถdingers-paradox..
...
Your Repository ID (RID) is rad:z3jEQE4VMzkR1UVeSLiN9E8AMtV6a.
You can show it any time by running `rad .` from this directory.
You have created a private repository.
This repository will only be visible to you, and to peers you explicitly allow.
To make it public, run `rad publish`.
To push changes, run `git push`.
If we run `rad ls --private`, we'll find the repository with its `private`
visibility.
โญโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฎ โ Name RID Visibility โ โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโค โ schrรถdingers-paradox rad:z3jEQE4VMzkR1UVeSLiN9E8AMtV6a private โ โฐโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฏ### Curating the *allow* list Now that we have our private repository, the next step is to grant access to our collaborators. The newly created private repository, `schrรถdingers-paradox`, will initially be accessible only by us, the lone delegate. This is due to the fact that repository delegates always have access to their private repositories. However, to collaborate on this repository with others, we need to curate its allow list to include the DIDs of Calyx, and at least one [seed node][seeder] *we trust*. This seed node will act as a trusted relay, necessary for the synchronization of repository state between Calyx and us. Though this trusted seed node needs a public DNS address, it doesn't have to be advertised to the network. One can simply omit adding the address to the `externalAddresses` key in the Radicle node configuration. > ๐ป > > Private repositories are not encrypted at rest, so any node that you add to > the allow list will have visibility over the contents of your private > repository. In the [Chapter 4][ch4] we explore a different setup that works > over Tor and doesn't require a trusted seed node. We can add both Calyx and our trusted seed node to the allow list using a single `rad id update` command. This command requires a `--title` for the update, along with each authorized DID specified with the `--allow` flag: $ rad id update --title "Allow Calyx and seed.darkstar.example" \ --allow did:key:z6Mkgom1bTxdh9fMFxFNXFMw3SbXnma6NARdsfcFuunurCap \ --allow did:key:z6MkqNZS9QWvC4wbZ8Vz4hQZ1FzN8q4XGj2KGmK9qNgQ8VWt Once we submit the update above, it is automatically approved, as we are the repository's sole delegate. If you look at the resulting diff, you see that both Calyx and our trusted node are being added to the `allow` list under the `visibility` key: ```json "allow": [ "did:key:z6Mkgom1bTxdh9fMFxFNXFMw3SbXnma6NARdsfcFuunurCap", "did:key:z6MkqNZS9QWvC4wbZ8Vz4hQZ1FzN8q4XGj2KGmK9qNgQ8VWt" ] ``` > ๐พ > > It is also possible to update a repository that is currently public to become > private, with a repository identity update: > ``` > $ rad id update --title "Make private" --visibility private > ``` > This won't delete historic repository data from public seed nodes or other > peers that previously seeded or cloned the repository, meaning users will > still be able to clone the old version of the repository. > > Instead, future updates to the repository, including the repository's private > status will be hidden to unauthorized users, only to be announced and > accessible to those explicitly defined in the `allow` list. ### Replicating to our seed node Now that we've set up our private repository, it's essential to configure it from our trusted seed node. Since our seed node is likely configured with a selective seeding policy, we'll have to tell it to seed our private repository with the `rad seed` command. Since `schrรถdingers-paradox` is a private repository, we also need to specify our (Paxel's) Node ID using the `--from` flag to explicitly indicate a source node to fetch from. We therefore run the following command from within an SSH session on our seed node: $ rad seed rad:z3jEQE4VMzkR1UVeSLiN9E8AMtV6a --from z6MkvZwzK64f3GuDcAs6dEcje89ddfHkBjS1v9Dkh7aCGq3C This will update darkstar's seeding policy and attempt to fetch the repository from our node. For the fetching to be successful, we'll have to be connected to the seed node. Check that it is indeed the case with `rad node status`, and use `rad node connect` or adjust your node's configuration if it isn't the case. > ๐พ > > If you're experiencing issues with repository replication, try these steps: > > 1. Check your current connections: > ``` > $ rad node status > ``` > > 2. If your seed node isn't listed, manually connect using: > ``` > $ rad node connect > ``` > For example: > ``` > $ rad node connect z6MkqNZS9QWvC4wbZ8Vz4hQZ1FzN8q4XGj2KGmK9qNgQ8VWt@seed.darkstar.example:8776 > ``` > > To find your seed node's address, run `rad node config --addresses` while logged in > to the seed node. > > For comprehensive information on setting up and managing seed nodes, refer to > our [Seeder's Guide][seeder]. Once the repository is on the seed, you should be able to see it by running `rad ls --private` from within the SSH session. It can then serve as an always online reliable access point for other authorized peers. Remember, only peers on the repository's allow list will be able to fetch from this seed node. ### Cloning as a trusted peer With our repository now successfully seeded, Calyx can clone our project. Since `schrรถdingers-paradox` is a private repository, Calyx needs to specify the seed node to fetch from, using the `--seed` flag. In this case, Calyx specifies the Node ID of `seed.darkstar.example`: $ rad clone rad:z3jEQE4VMzkR1UVeSLiN9E8AMtV6a --seed z6MkqNZS9QWvC4wbZ8Vz4hQZ1FzN8q4XGj2KGmK9qNgQ8VWt Once the repository is fetched, it's no longer necessary to specify the seed. Commands such as `rad sync` will automatically try to sync with our trusted seed. *With a local copy of the repository, Calyx can now collaborate freely, in full secrecy.* ### Removing nodes from the *allow* list In the event that our seed node became compromised, we could revoke access privileges to the repository from it. The same `rad id update` command is used, but this time with the `--disallow` flag: $ rad id update --title "Darkstar is compromised!" \ --disallow did:key:z6MkqNZS9QWvC4wbZ8Vz4hQZ1FzN8q4XGj2KGmK9qNgQ8VWt Our *no-longer-trusted* seed node will now be unable to fetch updates from us for `schrรถdingers-paradox`. > ๐พ > > As time goes by, you might decide that a repository no longer needs to be > private. In such a case, you can easily change its visibility. Simply run `rad > publish` within a repository's working copy to transform it from private to > public. > ๐ป > > Radicle's codebase hasn't yet undergone formal security audits. While we're > confident in its security, undiscovered vulnerabilities may exist. If you > encounter any issues, we encourage you to report them to > **security@radicle.xyz**. ## 4. Embracing the Onion **[Tor][tor]**, "The Onion Router", is a decentralized network that anonymizes users' online activity by routing internet traffic through multiple encrypted relays, providing stronger anonymity compared to traditional VPNs. To further enhance repository and user privacy, Radicle nodes can be configured to run behind Tor. This allows connections to be made to `.onion` addresses, as well as hiding one's IP address and exposing Radicle as a Tor *onion service*. Depending on how you configure Radicle, it offers several key advantages: * **Enhanced anonymity**: Your node's real IP address is hidden, making it difficult for others to track your online activities or determine your location. * **NAT traversal**: Tor automatically handles [NAT traversal][nat], eliminating the need for manual port forwarding or UPnP configuration. This means peers can directly connect with one another without a seed node, even behind a restrictive firewall. * **Censorship resistance**: Repositories accessible via Tor are more resilient against censorship attempts, as the Tor network is designed to circumvent blocking. [nat]: https://en.wikipedia.org/wiki/NAT_traversal Network Address Translation (NAT) typically creates barriers for direct peer-to-peer communication. Devices behind NAT gateways are often isolated with non-routable private IP addresses, making them inaccessible from the public internet. This is common in most consumer internet setups. Tor addresses this issue by providing static `.onion` addresses โ cryptographic identifiers representing nodes that are routable across the Tor network. This allows peers behind NAT to connect directly without needing to know each other's public IP addresses, overcoming limitations faced by traditional peer-to-peer networks. This chapter will explore a few distinct ways to configure Radicle with Tor: 1. **Mixed Mode**: Only connections to `.onion` addresses go through Tor, while other connections work normally. 2. **Full Proxy Mode**: All traffic is routed through Tor for maximum anonymity, including traffic to nodes that are *not* behind Tor. 3. **Transparent Proxy Mode**: Leverages an existing fully transparent Tor proxy on the network. Before proceeding, ensure you have Tor installed on your system. Use your preferred package manager to install it (the package name is typically "tor"). For detailed instructions, refer to the Tor [installation guide][install-tor]. ### Setting up a Tor Onion Service for Radicle We've been collaborating with Calyx on the private `schrรถdingers-paradox` repository. Recently, we removed a compromised seed node from the repository's `allow` list, which inadvertently cut off Calyx's access to the repository. To restore Calyx's access and enhance the security of our sensitive research, we'll configure our node as a Tor Onion Service (also known as a hidden service). This setup will make our node accessible via a `.onion` address, allowing Calyx to connect directly to us without relying on any intermediaries. Let's set up our Tor Onion Service. The following steps are for Linux-based systems, but they should be similar for other operating systems. First we create a new `radicle` directory for our Onion Service, ensuring it's readable and writable: $ sudo mkdir -m 700 /var/lib/tor/radicle This directory will store information and cryptographic keys for our Onion Service. Then we update our Tor configuration (`/etc/tor/torrc`) by adding the following lines to it: HiddenServiceDir /var/lib/tor/radicle HiddenServicePort 8776 These lines set the `HiddenServiceDir` to the path of the directory we just created and specify the `HiddenServicePort` as `8776`, which is the default Radicle node port. Finally, we restart our Tor daemon to apply the configuration changes: $ sudo systemctl restart tor Our `.onion` address is stored in a file under our Onion Service directory. Let's take a look: $ sudo cat /var/lib/tor/radicle/hostname 1odmmeotgcfx65l5hn6ejkaruvai222vs7o7tmtllszqk5xbysolfdd.onion We can copy this address to our clipboard, as we'll need it to configure our Radicle node in the next steps. > ๐ง > > If you are a **macOS** user, install Tor via `brew install tor` and restart > it via `brew services restart tor`. > > Use `mkdir -m 700 ~/.tor/radicle` to create your onion service directory. > > The Tor configuration file is located at `/usr/local/etc/tor/torrc` and your > `.onion` address can be found in `~/.tor/radicle/hostname`. > > If you are a **Debian** user who got Tor from a Debian repo, you may need to > change the ownership of the `radicle` directory to the `debian-tor` user and > group after creating it: > > $ sudo chown -R debian-tor:debian-tor /var/lib/tor/radicle #### Configuring Radicle in *Mixed Mode* Now that we have Tor properly set up, it's time to configure the networking on our Radicle node to work with it. There are several configuration options available, but for our use case, we'll implement the *Mixed Mode* where only connections to `.onion` addresses go through Tor, while regular connections go through the regular internet. For our particular use-case, we're trying to collaborate on a private repository, not to hide our IP address. This configuration offers a balance between privacy and performance: * It maintains low latency for regular public nodes. * It allows connectivity through Tor, for nodes that are exposed as an onion service.