How to Use Radicle: The Beginner's Guide

CodexFuse Team · 2026-11-01T20:02:56.261Z · 12 min read min read

From install to your first published repository, this beginner walkthrough covers how to use Radicle — the peer-to-peer code forge built on Git.

How to Use Radicle: The Beginner's Guide

Quick note before we start: this guide is about Radicle the peer-to-peer code forge, not "radicle" the Scheme-like programming language, not Radicale the CalDAV and CardDAV calendar server, and not Roots Radicle the WordPress starter kit.

If you searched how to use radicle and landed here, you are in the right place for the code-collaboration tool, and this radicle tutorial walks you from a blank terminal to your first published repository with the current Heartwood release. If you already know GitHub, the concepts will feel familiar — our GitHub beginner guide covers the centralized side of that story — but from here on, we leave servers behind.

What Is Radicle, Exactly?

Radicle is a peer-to-peer code forge built on Git. There is no central server and no single entity controlling the network or user data; repositories are replicated across peers. Cryptographic identities verify code and social artifacts like issues and patches. It is built in Rust, it is free and open source forever under MIT and Apache 2.0, and it uses no blockchain and no cryptocurrency.

The Radicle mental model: Git plus gossip

Start with this picture: Radicle is Git plus gossip. Your node holds the repository, your identity is a DID keypair instead of a username, and publishing means your node gossips the repo to the peers it is connected to. In radicle p2p networking there is no central server to push to and no company account to sign into — every peer carries the data it cares about.

That is p2p code collaboration in its purest form, and it is what makes Radicle a genuine decentralized github alternative. There is no platform in the middle that can change the rules, lock your account, or go down. Under the hood, radicle git repositories are ordinary Git repositories — commits, branches, and merges all work exactly as you know them — which is why our Git beginner guide still applies once you are inside a Radicle repo.

How do I install the Radicle node?

Installing takes one command. The official installer fetches the current toolchain and puts it in place — the current release is Radicle 1.10.3, released 08.09.2026, and there is no account or signup anywhere in the process.

curl -sSLf https://radicle.dev/install | sh
rad --version

The script installs into ~/.radicle/bin and adds it to your PATH. The toolchain has three parts: the rad CLI you type into, the radicle-node daemon that gossips with peers, and the git-remote-rad helper that teaches Git to speak rad:// URLs.

Radicle runs on Linux, macOS, and BSD; on Windows you build from source. If you prefer a package manager, the official quick start documents Homebrew (brew install radicle), an apt repository for Debian and Ubuntu, Arch AUR (radicle-bin), Nix (radicle-node), and cargo from source. For history buffs: radicle 1.0 shipped on 10.09.2024, and the 1.10.x line is the current Heartwood generation.

What is my radicle identity, and why is the keypair my account?

Radicle has no usernames and no passwords. Your radicle identity is an Ed25519 keypair, and the radicle did derived from it is your account. Creating it starts one flow — identity, then node, then your first repository:

rad auth
rad node start
rad node status
cd /path/to/my-project
rad init

The rad auth step asks for an alias — a human-readable node name — and a passphrase that protects your private key. It then prints your DID, which looks like did:key:z6Mkux1..., for example the documented did:key:z6MkpA56z2R7powZHMdCJ6PsecwMgTnmVCXtn3h1LiPBtrMd. You can view it any time with rad self or rad self --did.

This is the most important lesson of this whole guide: your passphrase and private key cannot be recovered if lost. Losing the key means losing your identity and your repositories — there is no reset link and no support desk. Signing goes through ssh-agent, and today there is exactly one identity per device, with no multi-device sync or key rotation yet.

How do I start, check, and stop my node?

Your radicle node is the daemon that keeps you on the network. The rad node start command launches it, rad node status shows your connections to peer nodes — entries like seed.example.xyz:8776 with sync state and outbound or inbound direction — and rad node stop shuts it down.

Node configuration lives in ~/.radicle/config.json. A running node is required for syncing and discovery, but Radicle is local-first: everything you do offline still works, and the network is only needed when you want to publish or fetch.

How do I publish my first repository?

Run rad init inside any existing Git project — it was the last command in the flow above. It asks four questions — Name, Description, Default branch, and Visibility (public or private) — then hands you your repository's address.

That address is the RID: rad:z plus a base58 identifier, for example rad:z3gqcJUoA1n9HaHKufZs5FCSGazv5. The command prints your Repository ID and confirms the project was announced to the network. You can show the RID any time by running rad . from inside the directory.

After publishing, rad sync status shows which nodes have replicated you, plain git push moves new commits, and rad sync forces a sync round. This is also where visibility matters most — read the next section before you pick "private".

What is the seed rule — and why the private-repo warning?

A radicle seed node is an always-on, internet-reachable server that hosts content for peers. To seed is to give back — bandwidth, storage, and data availability. Each operator chooses which repositories to seed through seeding policies, either permissive or selective, and your repository stays available as long as at least one seeding node is online.

IMPORTANT WARNING — from the official Radicle FAQ, current as of 2026-11-02: private repositories should NOT be used until the 23.09.2026 network-protocol vulnerability is resolved. A private repository is not announced to the network and is only replicated to nodes you explicitly allow, but until the protocol fix lands, do not rely on a private repository for secrecy.

The seed rule in one line: before you share an RID, make sure at least one seed node carries it — otherwise your repository disappears from the network the moment your own machine goes offline.

radicle clone: how do I fetch a repository?

Cloning pulls a repository from the peers and seeds you are connected to. It works like git clone, except Radicle first asks the network for the repository by its RID:

rad clone rad:z3gqcJUoA1n9HaHKufZs5FCSGazv5

The command creates a local working copy and updates your seeding policy for that RID to the "followed" scope — meaning your node will now help carry it. From here, every Git habit you already have still works: branch, commit, push.

radicle issues and radicle patches: code review without a server

radicle issues live inside the repository itself, stored in Git as Collaborative Objects (COBs) and signed with your key — so they work offline too:

rad issue open
rad issue list
rad issue show
git push rad HEAD:refs/patches
rad patch
rad patch show

The rad issue open command drops you into an editor where the first line becomes the title and the rest becomes the body; rad issue list and rad issue show let you browse what is there.

radicle patches are the pull-request equivalent. Pushing your HEAD to the special ref — git push rad HEAD:refs/patches — makes the remote helper prompt for a patch title and body, using the same title/body convention as commits. Review patches with rad patch and rad patch show; a handy alias is [alias] patch = push self HEAD:refs/patches, after which plain git patch opens a patch. The patch base is the latest commit of your default branch, and patches support non-destructive updates with revision-tied reviews.

One cultural difference from GitHub: there is no shared write access. Each user pushes to their own namespace, and collaboration happens through issues, patches, and code review.

The 5-step first deploy: how to use radicle today

1. Install the toolchain with the official curl one-liner.
2. Run rad auth, pick an alias, and store your passphrase somewhere you will not lose it.
3. Start your node with rad node start and confirm it with rad node status.
4. Publish a repository with rad init from inside any Git project.
5. Apply the seed rule: confirm at least one seed node carries your RID before you share it, and keep the private-repo warning in mind.

Git commands vs Radicle commands: the cheat sheet

7 beginner mistakes to avoid

Radicle vs GitHub vs Forgejo: which one is for you?

GitHub hosts your code on centralized servers — Radicle replicates it peer-to-peer with no central host. So the radicle vs github question is really about hosting philosophy, not features:

Forgejo is YOUR OWN server — Radicle has NO servers, only gossiping nodes. If self-hosting is your lane, our Forgejo beginner guide walks you through that world.

Git, Jujutsu, and Radicle: three different layers

Git is the repository format Radicle is built on — which is why the Git guide linked above still applies inside every Radicle repo. Jujutsu is an alternative local version-control tool with its own command set, and our Jujutsu beginner guide introduces it.

The clean split is this: jj is the LOCAL version-control layer — Radicle is the COLLABORATION/network layer that syncs repos between people. Git gives Radicle its storage format, Jujutsu offers a different local workflow, and Radicle provides the network that moves repositories between people.

Sources

Every fact in this guide was fetched on 2026-11-02 from:

• Radicle homepage — "Radicle: the sovereign forge" (radicle.xyz): current release 1.10.3 (08.09.2026), the install command, free-and-open-source statement.
• "Getting Started with Radicle" — the official quick start (radicle.dev/guides/quick-start): install methods, rad auth and the DID flow, node commands, rad init prompts and RID format, clone, issues, and patches.
• Radicle FAQ (radicle.dev/faq): seed node definition, seeding policies, the private-repository security warning, no shared write access, no blockchain.
• Radicle Seeder Guide (radicle.dev/guides/seeder): "To seed is to give back", permissive vs selective seeding policies, Node IDs.
• "My Radicle Journey" by Peter Demin (peter.demin.dev): independent confirmation of the rad auth DID output, the rad init RID output, and building from source.
• "Using Radicle CI for Development" (blog.liw.fi): advanced-usage context and an independent rad init transcript.

Frequently Asked Questions

Is Radicle free to use?

Yes. Radicle is free and open source forever under MIT and Apache 2.0, with no account and no signup. Development is funded by Radworks grants, which the project states carry no influence over it.

Does Radicle use blockchain?

No. Radicle uses public-key cryptography and a gossip protocol to replicate repositories — there is no blockchain and no cryptocurrency. (A few old blog posts claim otherwise; the official FAQ is explicit that both are absent.)

Can I use Radicle with my existing Git repository?

Yes. Run rad init inside any existing Git project and it becomes a Radicle repository with its full history, because Radicle repositories are Git repositories under the hood. Your local workflow does not have to change.

What happens if my seed node goes offline?

Your repository stays available as long as at least one seeding node carrying it remains online. If every seeder drops it and your own node is offline too, peers cannot fetch it — which is exactly why the seed rule in this guide matters.

Can I migrate a project from GitHub to Radicle?

Yes, and it is deliberately simple: take your local Git copy of the project, run rad init inside it, and the full history publishes to the Radicle network under a new RID. There is no import wizard because none is needed — Git is Git.