Skip to main content

​
Overview

This template provides a production‑ready Radicle instance as a Monk runnable. You can:
  • Run it directly to get a managed peer-to-peer code collaboration platform
  • Inherit it in your own infrastructure to add decentralized Git hosting
Radicle is a sovereign peer-to-peer network for code collaboration. It enables developers to collaborate on code without relying on trusted intermediaries. Built on Git, Radicle provides secure peer-to-peer collaboration, resilient to censorship and centralized control.

​
What this template manages

  • Radicle node (seed node)
  • Radicle HTTP API
  • Git repository hosting
  • Peer-to-peer networking
  • Identity and authentication
  • Web UI on port 8080 (httpd)

​
Quick start (run directly)

  1. Load templates
monk load MANIFEST
  1. Run Radicle seed node
monk run radicle/seed
  1. Customize configuration (recommended via inheritance)
Running directly uses the defaults defined in this template’s variables. To customize node configuration:
  • Preferred: inherit and override variables as shown below.
  • Alternative: fork/clone and edit the variables in radicle.yaml, then monk load MANIFEST and run.
Once started:
  • HTTP API: http://localhost:8080
  • Connect with Radicle CLI (rad)

​
Configuration

Key variables you can customize in this template: 
variables:
  radicle-image-tag: "latest"              # Radicle image tag
  httpd-port: "8080"                       # HTTP API port
  p2p-port: "8776"                         # P2P networking port
  node-alias: "my-seed"                    # node alias/name
  external-address: "seed.example.com:8776" # external P2P address
Data is persisted under ${monk-volume-path}/radicle on the host. Inherit the Radicle seed node in your infrastructure for decentralized Git hosting. Example: 
namespace: myteam

seed:
  defines: runnable
  inherits: radicle/seed
  variables:
    node-alias: "team-seed"
    external-address: "git.myteam.com:8776"
    httpd-port: "8080"
    p2p-port: "8776"
Run the seed node: 
monk run myteam/seed

​
Ports and connectivity

  • Service: radicle-httpd on TCP port 8080 (HTTP API)
  • Service: radicle-node on TCP port 8776 (P2P network)
  • Git over HTTP: accessible via HTTP API
  • From Radicle CLI, connect to seed node using node ID and address

​
Persistence and data

  • Data path: ${monk-volume-path}/radicle:/app/.radicle
  • Git repositories: stored in Radicle storage
  • Node identity and configuration persisted in data path

​
Features

  • Peer-to-Peer: No central server, censorship-resistant
  • Git Native: Built on Git, compatible with existing workflows
  • Cryptographic Identity: Key-based authentication
  • Offline-First: Work locally, sync when connected
  • Social Coding: Issues, patches, and discussions
  • Seed Nodes: Public nodes for discovery and availability
  • Secure: End-to-end encrypted, signed commits

​
Radicle CLI Usage

Install Radicle CLI and connect to your seed: 
# Initialize a repository
rad init

# Push to Radicle network
rad push

# Clone a repository
rad clone rad://...

# Configure seed node
rad config set seed.default <seed-node-id>@<seed-address>:8776

​
Seed Node

Seed nodes provide:
  • Discovery: Help peers find each other
  • Availability: Always-online repository hosting
  • Replication: Backup copies of repositories
  • HTTP Gateway: Web access to repositories

​
Identities

Radicle uses cryptographic identities:
  • Device ID: Unique identifier for each device
  • Project ID: Unique identifier for each project
  • Peer ID: Unique identifier for each peer

​
Use cases

Radicle excels at:
  • Decentralized open-source development
  • Censorship-resistant code collaboration
  • Private team collaboration without GitHub
  • Air-gapped environments
  • Sovereign infrastructure
  • Web3 and crypto projects

​
Integration with Git

Radicle integrates seamlessly: 
# Add Radicle as remote
git remote add rad rad://...

# Push to Radicle
git push rad main

# Pull from Radicle
git pull rad main
  • Combine with monitoring tools for observability
  • Integrate with CI/CD pipelines for automated workflows

​
Troubleshooting

  • Access HTTP API at http://localhost:8080 to verify the seed node is running.
  • Check node status:
rad node status
  • View node ID and peer list:
rad self
rad node peers
  • Check logs:
monk logs -l 500 -f radicle/seed
  • For connectivity issues:
    • Verify P2P port 8776 is accessible from external networks
    • Check firewall rules allow incoming connections on port 8776
    • Ensure external-address matches your actual public address
  • For synchronization issues, check seed node connectivity and peer list
  • Monitor disk space for repository storage under ${monk-volume-path}/radicle
  • Ensure system time is synchronized (important for P2P networking)