The Peer Network

P2P collaboration, delegates, GitHub bridges, and the Radicle ecosystem

Team workflow on Radicle

On GitHub, collaboration goes through a central server: you fork, you push, you open a PR. On Radicle, there is no central server. The workflow is fundamentally different.

The peer-to-peer workflow

# Classic GitHub workflow:
# 1. Fork the repository (on the server)
# 2. Clone your fork
# 3. Push your branch
# 4. Open a Pull Request (on the server)
# 5. The maintainer merges (on the server)

# Radicle workflow:
# 1. Clone the project: rad clone rad:z...
# 2. Create your branch and code
# 3. Propose a patch: rad patch create
# 4. The maintainer reviews and merges: rad patch merge
# 5. Everyone synchronizes: rad sync

The fundamental difference: on Radicle, each peer owns a complete copy of the project, including patches, issues, and metadata. There is no single "source of truth" on a server. The source of truth is the consensus among the project's delegates.

A concrete scenario

Imagine three developers - Alice, Bob, and Carol - working together on a Radicle project:

# Alice creates the project
# (on Alice's machine)
rad init
rad push

# Bob clones the project
# (on Bob's machine)
rad clone rad:z2e7R...

# Bob proposes an improvement
git switch -c add-tests
# ... code ...
git commit -m "Add unit tests"
rad patch create

# Alice reviews Bob's patch
# (on Alice's machine)
rad sync                          # Fetches Bob's patch
rad patch list                    # Sees the patch
rad patch show <id>              # Examines the changes
rad patch comment <id> --message "Approved!"
rad patch merge <id>             # Merges

# Carol synchronizes to get the latest version
# (on Carol's machine)
rad sync
git pull

Project management - delegates and permissions

On a Radicle project, governance relies on the concept of delegates. These are the trusted people who have the power to merge patches and make decisions about the project.

Delegates

When you create a project with rad init, you automatically become the sole delegate. You can then add others:

# View current project delegates
rad inspect

# Modify project delegates
rad id edit

The threshold

The threshold defines how many delegates must approve a change for it to be considered valid. By default, the threshold is 1 (a single delegate is enough).

# With 3 delegates and threshold=2:
# 2 out of 3 delegates must agree to merge a patch
# It's a majority voting system

# Modify the threshold (via rad id edit)
rad id edit

This mechanism is powerful: it allows creating democratic governance without any central authority. It is similar to multi-signature systems in cryptography.

Project visibility

A Radicle project can have different levels of visibility:

• Public: any peer who knows the RID can clone and contribute. This is the default behavior
• Private: only explicitly authorized peers can access the project. Useful for company projects or works in progress

Team patch review

Code review is just as important on Radicle as on GitHub. The tools are different, but the principle remains the same: read, comment, improve.

Examining a patch

# List pending patches
rad patch list --state open

# View patch details (title, author, commits)
rad patch show <patch-id>

# View the patch diff
rad patch diff <patch-id>

Commenting and discussing

# Add a general comment
rad patch comment <patch-id> --message "The code is clean, but error handling is missing."

# Comments are signed and propagated to all peers
# Every contributor can see the complete discussion

Formal review

# Approve a patch (positive review)
rad patch review <patch-id> --accept

# Request changes
rad patch review <patch-id> --reject --message "Tests need to be fixed before merging."

Patch lifecycle

# 1. Creation       : rad patch create        (state: open)
# 2. Discussion     : rad patch comment       (state: open)
# 3. Review         : rad patch review        (state: open)
# 4a. Acceptance    : rad patch merge         (state: merged)
# 4b. Rejection     : rad patch close         (state: closed)
# 5. Update         : rad patch update        (author pushes new commits)

Bridges with GitHub

The world is not going to migrate to Radicle overnight. Most of your colleagues and open source projects use GitHub. Fortunately, Radicle and GitHub can coexist.

Why bridges?

• Progressive transition: you can start using Radicle without abandoning GitHub
• Redundancy: your code exists on both GitHub and the Radicle network
• Accessibility: contributors who don't know Radicle can still go through GitHub

Bidirectional mirroring

Mirroring consists of synchronizing a repository between GitHub and Radicle in both directions:

# Your repository has two remotes:
git remote -v
# origin     git@github.com:your-user/your-project.git (GitHub)
# rad        rad://z2e7R... (Radicle)

# Push to both at the same time
git push origin main
rad push

# Or configure an alias to push everywhere
git config alias.push-all '!git push origin main && rad push'
git push-all

radicle-ci-broker

The radicle-ci-broker is a tool that connects Radicle patches to existing CI systems. When a patch is created on Radicle, the broker can trigger a GitHub Actions or GitLab CI pipeline:

# CI broker principle:
# 1. A patch arrives on Radicle
# 2. The broker detects the new patch
# 3. It pushes the code to GitHub (temporary branch)
# 4. GitHub Actions runs the tests
# 5. The result is reported back on the Radicle patch

It is a bridge between the decentralized world and existing CI tools. Eventually, Radicle is developing its own CI solutions, but in the meantime, the broker ensures you don't lose anything.

The Radicle web interface

Radicle is primarily a command-line tool, but web interfaces exist for those who prefer the browser.

app.radicle.xyz

app.radicle.xyz is the official Radicle web interface. It allows you to:

• Browse public projects on the network
• View source code, commits, and branches
• Check patches and issues
• Discover new projects

radicle-explorer (self-hosted)

You can also host your own web interface with radicle-explorer. It is a web application that connects to your local node:

# Install radicle-explorer (requires Node.js)
# The source code is available on GitHub:
git clone https://github.com/radicle-dev/radicle-explorer.git
cd radicle-explorer
npm install
npm run build

# Launch in development mode
npm run dev
# Opens http://localhost:3000

The explorer connects to your Radicle node's HTTP API and displays projects, patches, and issues in an elegant web interface.

Decision matrix - which tool to choose?

Radicle is not the answer to everything. Here is a matrix to help you choose the right tool for each situation:

The Radicle ecosystem

Heartwood - the protocol

Heartwood is the name of the protocol that powers Radicle. It is the "heart of wood" - the technical foundation upon which everything rests. Heartwood defines:

• How peers discover and connect to each other
• How data is replicated between nodes
• The format of patches, issues, and other collaborative objects
• The identity system based on DIDs

Heartwood is written in Rust, a language renowned for its performance and memory safety. The protocol is open and documented - anyone can implement a compatible client.

Ecosystem components

The roadmap

Radicle is under active development. Here are the main directions:

• UX improvement: richer web interface, better IDE integration
• Native CI/CD: running pipelines directly on the Radicle network
• Notifications: getting alerted about new patches and comments
• Performance: faster replication, better handling of large repositories
• Interoperability: improved bridges with GitHub, GitLab, and Forgejo

Practical exercise - Simulate a P2P collaboration

export RAD_HOME=~/.radicle-alice    # First profile
rad auth
export RAD_HOME=~/.radicle-bob      # Second profile
rad auth

# Create two working directories
mkdir -p ~/radicle-exercise/alice
mkdir -p ~/radicle-exercise/bob

# As Alice
cd ~/radicle-exercise/alice

# Create a Git repository
git init -b main shared-project
cd shared-project

# Create some content
cat > README.md <<EOF
# Shared Project
A collaborative project on the Radicle network.

## Contributors
- Alice (creator)
EOF

git add README.md
git commit -m "Initialize the shared project"

# Initialize Radicle
rad init
# Note the RID that appears: rad:z...

# As Bob
cd ~/radicle-exercise/bob

# Clone Alice's project
rad clone rad:z<the-project-rid>
cd shared-project

# Bob creates a branch and adds his contribution
git switch -c add-bob-contribution

cat >> README.md <<EOF

## Planned Features
- Peer-to-peer synchronization
- Decentralized code review
- Issues without a central server
EOF

git add README.md
git commit -m "Add planned features"

# Bob proposes a patch
rad patch create

# Back as Alice
cd ~/radicle-exercise/alice/shared-project

# Synchronize to receive Bob's patch
rad sync

# View patches
rad patch list

# Examine the patch
rad patch show <patch-id>

# Comment
rad patch comment <patch-id> --message "Excellent contribution, Bob!"

# Merge the patch
rad patch merge <patch-id>

# On Alice's side - view the result
cd ~/radicle-exercise/alice/shared-project
git log --oneline
cat README.md

# On Bob's side - synchronize
cd ~/radicle-exercise/bob/shared-project
rad sync
git pull
git log --oneline

# Bob creates an issue
cd ~/radicle-exercise/bob/shared-project
rad issue create --title "Add a LICENSE file" \
                 --description "The project does not have an open source license yet."

# Alice sees the issue
cd ~/radicle-exercise/alice/shared-project
rad sync
rad issue list

# Alice resolves the issue
echo "MIT License - Copyright $(date +%Y)" > LICENSE
git add LICENSE
git commit -m "Add MIT license"
rad push

# Alice closes the issue
rad issue close <issue-id>

Summary