> ## Documentation Index
> Fetch the complete documentation index at: https://docs.monk.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Radicle

> Ready-to-run Radicle container template for peer-to-peer code collaboration and decentralized Git hosting.

## 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

```bash theme={null}
monk load MANIFEST
```

2. Run Radicle seed node

```bash theme={null}
monk run radicle/seed
```

3. 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:

```yaml theme={null}
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.

## Use by inheritance (recommended for teams)

Inherit the Radicle seed node in your infrastructure for decentralized Git hosting. Example:

```yaml theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
# 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:

```bash theme={null}
# Add Radicle as remote
git remote add rad rad://...

# Push to Radicle
git push rad main

# Pull from Radicle
git pull rad main
```

## Related templates

* 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:

```bash theme={null}
rad node status
```

* View node ID and peer list:

```bash theme={null}
rad self
rad node peers
```

* Check logs:

```bash theme={null}
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)