ourworld_web/docs_projectmycelium
23
0
Fork 0
Code Issues 2 Pull Requests Actions Packages Projects Releases Wiki Activity

init

Browse Source
This commit is contained in:
mik-tf
2025-11-25 15:27:56 -05:00
commit c769942374
33 changed files with 24049 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

212
docs/network/architecture.md Normal file
View File

@@ -0,0 +1,212 @@
---
sidebar_position: 4
---
# Mycelium Network Architecture
Understanding Mycelium's architecture reveals why it's fundamentally different from traditional networking solutions.
## Core Innovation: Identity = Address
Mycelium's architecture revolves around **peers**. Each peer has a cryptographic private/public keypair, and these are used to encrypt all messages in an end-to-end fashion.
The hash of the public key is used as an **IPv6 address**. This means that the cryptographic identity and the network address of each peer are **inherently linked**.
### What This Means in Practice
Think of it like a postal system where you can send a secret message to anyone just by knowing their address. The recipient can read it simply because they reside at the intended destination, without requiring any additional coordination or precommunication.
- **Your address IS your identity** – No separation between who you are and where you are
- **Automatic encryption** – Messages are encrypted to the destination by design
- **No key exchange needed** – The address itself contains the encryption key
:::info Technical Lineage
This innovation was pioneered by the **cjdns** network, which later inspired **Yggdrasil**, from which Mycelium is inspired. Each generation has refined and improved upon this fundamental concept.
:::
## Why This Is More Secure Than TLS/HTTPS
Compare this to the regular web, where most traffic is encrypted using TLS/HTTPS.
### The TLS Problem
In traditional TLS/HTTPS:
- ❌ **No inherent link** between a TLS cryptographic identity (certificate) and the destination of the traffic
- ❌ **Self-signed certificates** are rare and not considered secure
- ❌ **Centralized certificate authorities** – devices must trust an external CA list
- ❌ **Single points of failure** – CAs can be compromised, fail, or be coerced
### The Mycelium Solution
- ✅ **Cryptographic identity = Network address** – MITM attacks are cryptographically impossible
- ✅ **No trusted intermediaries** – No certificate authorities to compromise
- ✅ **Decentralized by design** – No single point of failure
- ✅ **Improved security and resiliency** – Both benefits simultaneously
## Network Architecture: Underlay & Overlay
Mycelium creates a **mesh network** to deliver encrypted IP overlay traffic. But how do peers actually connect?
### The Underlay Network
Mycelium peers must connect somehow to form the mesh. Most commonly, peers connect **over the regular internet**, using it as an **underlay network**.
This is enabled by **public peers** – special nodes that are open to receive connections on the regular internet.
```
┌──────────────────────────────────────────────────┐
│ Regular Internet (Underlay) │
│ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ Public │ │ Public │ │ Public │ │
│ │ Peer A │ │ Peer B │ │ Peer C │ │
│ └────▲─────┘ └────▲─────┘ └────▲─────┘ │
│ │ │ │ │
└───────┼────────────────┼────────────────┼────────┘
│ │ │
┌───┴────┐ ┌───┴────┐ ┌───┴────┐
│ Your │◄─────►│ Your │◄─────►│ Your │
│Device 1│ Mesh │Device 2│ Mesh │Device 3│
└────────┘ └────────┘ └────────┘
Encrypted Mycelium Overlay Network
```
### The Overlay Network
On top of the underlay, Mycelium creates an **encrypted overlay** where:
- All traffic between your devices is end-to-end encrypted
- Routing is handled by the mesh protocol
- Your devices appear to be on the same local IPv6 network
## Resilient Multi-Path Routing
Here's where Mycelium achieves **more resilient routing than the regular internet**.
### How It Works
Each peer generally connects to **multiple public peers**, each offering a **different potential path** for traffic.
```
┌────────────────┐
│ Your Device │
└───┬─────┬─────┬┘
│ │ │
┌────────┤ │ └────────┐
│ │ │
┌───▼────┐ ┌───▼────┐ ┌────▼───┐
│Public │ │Public │ │Public │
│Peer 1 │ │Peer 2 │ │Peer 3 │
│Germany │ │Belgium │ │Finland │
└────────┘ └────────┘ └────────┘
Route A Route B Route C
```
### Real-World Resilience
If the route via one public peer is interrupted—such as by an **undersea cable cut**—there's a possibility to find another route via another public peer.
**Why the regular internet can't do this:**
- Most internet connections have a single ISP path
- BGP routing changes slowly and requires coordination
- No automatic multi-path at the user level
- Cable cuts can disconnect entire regions
**Why Mycelium can:**
- You're connected to multiple geographically diverse peers
- Mesh routing adapts automatically in seconds
- No coordination needed — it's peer-to-peer
- Traffic flows through available paths automatically
## Key Architectural Components
### 1. Cryptographic Keypair
Every Mycelium node generates:
- **Private key** – Kept secret, never shared
- **Public key** – Shared openly, identifies your node
### 2. IPv6 Address
Derived from your public key:
- **Format**: Standard IPv6 (for example `5c4:c176:bf44:b2ab:5e7e:f6a:b7e2:11ca`)
- **Unique**: Cryptographically guaranteed to be unique
- **Persistent**: Doesn't change unless you generate new keys
### 3. Peer Connections
Your node maintains connections to:
- **Public peers** – For internet connectivity and routing
- **Direct peers** – Other nodes you explicitly connect to
- **Discovered peers** – Nodes found through the mesh
### 4. Routing Table
Each node maintains:
- **Known peers** and their addresses
- **Path costs** to reach each peer
- **Multiple routes** to most destinations
- **Automatic updates** as the network changes
## Message Encryption Flow
When you send data to another Mycelium address:
1. **Lookup destination** – Find the IPv6 address.
2. **Derive public key** – Extract from the address.
3. **Encrypt message** – Using the destination's public key.
4. **Route through mesh** – Via the optimal path.
5. **Decrypt at destination** – Using the destination's private key.
Only the destination can decrypt — not even the public peers can read the content.
## Benefits of This Architecture
### Security Benefits
- **End-to-end encryption** – Built into the protocol
- **No MITM attacks** – Identity = Address prevents it
- **No trusted third parties** – Fully peer-to-peer
- **Private by default** – Encryption isn't optional
### Resilience Benefits
- **Multi-path routing** – Automatic failover
- **Self-healing** – Network adapts to failures
- **No single point of failure** – Fully distributed
- **Works behind NAT** – Firewall traversal built-in
### Simplicity Benefits
- **Zero configuration** – Just run and connect
- **Automatic key management** – No manual setup
- **Plug and play** – Works immediately
- **Cross-platform** – Same protocol everywhere
## Comparison with Other Technologies
| Feature | Mycelium | Traditional VPN | TLS/HTTPS | Tor |
|--------|----------|----------------|----------|-----|
| **Identity = Address** | ✅ Yes | ❌ No | ❌ No | ❌ No |
| **Decentralized** | ✅ Yes | ❌ Central server | ❌ Needs CAs | ✅ Yes |
| **Multi-path routing** | ✅ Yes | ❌ Single path | ❌ Single path | ✅ Yes |
| **Direct connections** | ✅ When possible | ❌ Via server | ✅ Yes | ❌ Via relays |
| **Zero config** | ✅ Yes | ❌ Needs setup | ✅ Browser only | ❌ Complex |
| **Performance** | ✅ Fast | ⚠️ Moderate | ✅ Fast | ❌ Slow |
## Technical Resources
- **Source Code** – [github.com/threefoldtech/mycelium](https://github.com/threefoldtech/mycelium)
- **Yggdrasil Network** – [yggdrasil-network.github.io](https://yggdrasil-network.github.io)
- **cjdns Project** – [github.com/cjdelisle/cjdns](https://github.com/cjdelisle/cjdns)
:::tip Understanding Makes It Powerful
Now that you understand how Mycelium works, you can appreciate why it's not just another VPN – it's a fundamentally different approach to secure networking that eliminates entire classes of security problems.
:::

174
docs/network/install.md Normal file
View File

@@ -0,0 +1,174 @@
---
sidebar_position: 2
---
# Install Mycelium Network
The Mycelium app is available for Android, Windows, macOS, and iOS. Installation is simple and user-friendly.
## Easy Installation (Recommended)
### iOS & macOS
Download the Mycelium app from the App Store:
**[Download from App Store](https://apps.apple.com/app/id6504277565)**
1. Open the App Store.
2. Search for "Mycelium" or use the link above.
3. Tap **Get** or **Install**.
4. Open the app and you're ready to go.
### Android
Download the Mycelium app from Google Play:
**[Download from Google Play](https://play.google.com/store/apps/details?id=tech.threefold.mycelium)**
1. Open Google Play Store.
2. Search for "Mycelium ThreeFold" or use the link above.
3. Tap **Install**.
4. Open the app and you're ready to go.
### Windows
Download the latest Windows app:
**[Download for Windows](https://github.com/threefoldtech/myceliumflut/releases)**
1. Go to the releases page.
2. Download the latest `.exe` file.
3. Double-click to install.
4. **Important:** Run as administrator for proper network connectivity.
:::tip Super Simple
The Mycelium app provides an easy graphical interface – no command-line needed. Just install, open, and start connecting.
:::
## What You Get
With the Mycelium app, you get:
- ✅ **Easy interface** – One-click to start/stop
- ✅ **Automatic setup** – No configuration needed
- ✅ **Peer management** – Add peers with a click
- ✅ **Your Mycelium address** – Copy with one tap
- ✅ **Status monitoring** – See connection status
## Linux Installation (Advanced)
For Linux users, Mycelium is installed via command-line.
### Using Pre-built Binaries (Recommended)
1. **Download the latest release:**
```bash
wget https://github.com/threefoldtech/mycelium/releases/latest/download/mycelium-linux-x64.tar.gz
```
2. **Extract and install:**
```bash
tar -xzf mycelium-linux-x64.tar.gz
chmod +x mycelium
sudo mv mycelium /usr/local/bin/
```
3. **Verify installation:**
```bash
mycelium --version
```
### Building from Source
If you prefer to build from source:
```bash
# Install Rust if you haven't already
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
# Clone and build
git clone https://github.com/threefoldtech/mycelium.git
cd mycelium/myceliumd
cargo build --release
# Install binary
sudo mv target/release/myceliumd /usr/local/bin/mycelium
```
## System Requirements
### For Apps (iOS, Android, macOS, Windows)
- **OS:** iOS 14+, Android 8+, macOS 11+, Windows 10+
- **RAM:** Minimal (runs in background)
- **Disk:** ~50 MB
- **Network:** Standard internet connection
### For Linux Command-Line
- **OS:** Any modern Linux distribution
- **RAM:** 50 MB
- **Disk:** 20 MB
- **Network:** IPv6 support (enabled by default on most systems)
## Troubleshooting
### App Not Starting (Windows)
**Windows users:** The app must run as administrator for network connectivity.
- Right-click the app icon.
- Select **Run as administrator**.
### App Not Connecting
1. **Check internet connection** – Ensure you're online.
2. **Restart the app** – Close and reopen.
3. **Add public peers** – Use the app's peer management (see Quick Start).
4. **Check firewall** – Ensure the app isn't blocked.
### Linux Command-Line Issues
**"Command not found" error:**
- Ensure `/usr/local/bin` is in your `PATH`.
- Try running with full path: `/usr/local/bin/mycelium`.
- Check file permissions: `ls -l /usr/local/bin/mycelium`.
**Permission denied:**
```bash
# Make the binary executable
chmod +x /usr/local/bin/mycelium
# Run with sudo for network operations
sudo mycelium --peers tcp://188.40.132.242:9651
```
**IPv6 Not Available:**
```bash
# Check if IPv6 is enabled
cat /proc/sys/net/ipv6/conf/all/disable_ipv6
# Enable if needed (0 = enabled)
sudo sysctl -w net.ipv6.conf.all.disable_ipv6=0
```
## What's Next?
Now that Mycelium is installed, connect to the network:
- **[Quick Start Guide](/network/quick-start)** – Connect in 5 minutes.
## Additional Resources
- **GitHub Repository** – [github.com/threefoldtech/mycelium](https://github.com/threefoldtech/mycelium)
- **Get Help** – [Telegram Community](https://t.me/threefold/1)
:::tip Ready to Connect?
Installation complete. Continue to the **[Quick Start](/network/quick-start)** guide to join the network.
:::

160
docs/network/overview.md Normal file
View File

@@ -0,0 +1,160 @@
---
sidebar_position: 1
slug: /network
---
# What is Mycelium Network?
Mycelium is an **IPv6 overlay network** that creates secure, encrypted connections between your devices anywhere in the world.
Think of it as your own private internet layer – but without the complexity of VPNs, port forwarding, or NAT traversal.
## How It Works
Mycelium creates a **peer-to-peer mesh network** where:
- 🌐 Each device gets its own unique IPv6 address
- 🔐 All traffic is automatically encrypted end-to-end
- 🚀 Smart routing finds the fastest path between devices
- 🔄 The network adapts automatically as devices join or leave
No central servers. No configuration complexity. Just secure connectivity.
## Why Use Mycelium?
### 🌍 Global Connectivity
Connect devices across the world as if they were on the same local network:
- Home server to laptop while traveling
- Multiple offices without complicated VPN setups
- IoT devices across different locations
- Development environments and remote services
### 🔒 Secure by Default
- **End-to-end encryption** – Traffic is encrypted between devices
- **No trust required** – No central authority can intercept
- **Automatic security** – No manual key exchange needed
- **Private by design** – Only you control your network
### 🚀 Smart & Fast
- **Automatic routing** – Finds optimal paths
- **NAT traversal** – Works behind firewalls
- **Resilient** – Routes around failures
- **Low overhead** – Minimal performance impact
### 📱 Cross-Platform & Easy to Use
Easy-to-use apps for most platforms:
- **iOS** – App Store
- **Android** – Google Play
- **macOS** – App Store
- **Windows** – Desktop app
- **Linux** – Command-line (for advanced users)
## Common Use Cases
### Remote Access
Access your home server or services from anywhere without opening ports or configuring complex VPNs.
```bash
# At home: Run Mycelium on your server
# Address: 5c4:c176:bf44:b2ab:5e7e:f6a:b7e2:11ca
# Traveling: Access your server via its Mycelium address
ssh user@5c4:c176:bf44:b2ab:5e7e:f6a:b7e2:11ca
```
### Private Networks
Create secure connections between multiple locations:
- Link office networks
- Connect distributed teams
- Secure IoT deployments
- Private cloud infrastructure
### Development & Testing
Build distributed applications with real-world networking:
- Test across geographic locations
- Develop P2P applications
- Simulate network topologies
- Remote debugging
### ThreeFold Grid Access
Connect to services on the ThreeFold Grid:
- Access deployed workloads
- Manage your infrastructure
- Use decentralized services
- Build on the grid
## Key Features
| Feature | Benefit |
|--------|---------|
| **Zero Configuration** | Works out of the box |
| **IPv6 Native** | Future-proof addressing |
| **P2P Mesh** | No single point of failure |
| **Automatic Encryption** | Secure without complexity |
| **NAT Traversal** | Works behind firewalls |
| **Smart Routing** | Optimal path selection |
| **Low Latency** | Direct connections when possible |
| **Cross-Platform** | Run anywhere |
## How Is It Different?
### vs Traditional VPNs
- ✅ **No central server** – Peer-to-peer mesh
- ✅ **Automatic routing** – No manual configuration
- ✅ **Lower latency** – Direct connections
- ✅ **Simpler setup** – Just run and connect
### vs Other Overlay Networks
- ✅ **IPv6 native** – Not limited to IPv4 address space
- ✅ **Production ready** – Used in ThreeFold infrastructure
- ✅ **Active development** – Continuous improvements
- ✅ **Open source** – Transparent and auditable
## Architecture Overview
```
┌──────────────┐ Encrypted Tunnel ┌──────────────┐
│ Device A │◄────────────────────────────►│ Device B │
│ Mycelium IP │ Over Internet │ Mycelium IP │
└──────────────┘ └──────────────┘
│ │
└────────────── Mesh Network ────────────────┘
(via Public Peers)
```
**How it works:**
- Devices run the Mycelium daemon
- Connect to public or private peers
- Build encrypted tunnels automatically
- Route traffic efficiently
**Want to understand the architecture in depth?** Read the **[Architecture Guide](/network/architecture)** to learn about Mycelium's cryptographic design, why it's more secure than TLS/HTTPS, and how its multi-path routing provides real-world resilience.
## Getting Started
Ready to try Mycelium? It's simple:
1. **[Install Mycelium](/network/install)** – Download the app for your device.
2. **[Quick Start](/network/quick-start)** – Connect in under 5 minutes.
## Resources
- **Source Code** – [github.com/threefoldtech/mycelium](https://github.com/threefoldtech/mycelium)
- **Community** – [t.me/threefold/1](https://t.me/threefold/1)
- **Forum** – [forum.threefold.io](https://forum.threefold.io)

247
docs/network/quick-start.md Normal file
View File

@@ -0,0 +1,247 @@
---
sidebar_position: 3
---
# Quick Start
Get connected to the Mycelium network in under 5 minutes.
## Using the Mycelium App (Easy)
If you're on iOS, Android, macOS, or Windows – use the app for the easiest experience.
### Step 1: Open the App
1. Open the Mycelium app you installed.
2. You'll see a simple interface with a **Start** button.
### Step 2: Start Mycelium
1. Click the **Start** button.
2. The app will automatically connect to the network.
3. That's it – you're now on the Mycelium network.
:::tip That's It
The app handles everything automatically. No configuration needed.
:::
### Step 3: Get Your Mycelium Address
Your unique Mycelium IPv6 address is shown in the app:
1. Look for your address on the main screen.
2. Click the **copy button** next to it to copy your address.
3. Share this address with others to let them connect to you.
### Step 4: Add More Peers (Optional)
For better connectivity, you can add public peers:
1. Click on the **Peers** section in the app.
2. Add peer addresses (see list below).
3. Click **Restart** to connect to the new peers.
**Example peers to add:**
```
tcp://188.40.132.242:9651
tcp://185.69.166.8:9651
tcp://65.21.231.58:9651
```
### Step 5: Test Your Connection
Try connecting to another Mycelium address to verify everything works.
---
## Using Command-Line (Linux & Advanced Users)
For Linux users or those who prefer the command-line.
### Step 1: Start Mycelium
```bash
sudo mycelium --peers tcp://188.40.132.242:9651 quic://185.69.166.8:9651
```
You should see output indicating Mycelium is starting and connecting to peers.
### Step 2: Get Your IPv6 Address
Open a **new terminal** and check your node info:
```bash
mycelium inspect --json
```
Example output:
```json
{
"publicKey": "abd16194646defe7ad2318a0f0a69eb2e3fe939c3b0b51cf0bb88bb8028ecd1d",
"address": "5c4:c176:bf44:b2ab:5e7e:f6a:b7e2:11ca"
}
```
**Save your address** – this is your unique Mycelium IPv6 address.
### Step 3: Test Connectivity
Ping one of the public peers to verify connectivity:
```bash
ping6 54b:83ab:6cb5:7b38:44ae:cd14:53f3:a907
```
If you see responses, you're connected.
### Step 4: Keep It Running (Linux)
**Run in Background:**
```bash
# Using nohup
nohup sudo mycelium --peers tcp://188.40.132.242:9651 quic://185.69.166.8:9651 &
```
**Better: Use systemd:**
Create `/etc/systemd/system/mycelium.service`:
```ini
[Unit]
Description=Mycelium Network
After=network.target
[Service]
Type=simple
ExecStart=/usr/local/bin/mycelium --peers tcp://188.40.132.242:9651 quic://185.69.166.8:9651
Restart=always
RestartSec=10
[Install]
WantedBy=multi-user.target
```
Enable and start:
```bash
sudo systemctl enable mycelium
sudo systemctl start mycelium
sudo systemctl status mycelium
```
---
## Public Peers List
Here are stable public peers you can connect to:
| Region | Address for App | Mycelium IP |
|----------|------------------------------|-------------------------------------------|
| Germany | tcp://188.40.132.242:9651 | 54b:83ab:6cb5:7b38:44ae:cd14:53f3:a907 |
| Germany | tcp://136.243.47.186:9651 | 40a:152c:b85b:9646:5b71:d03a:eb27:2462 |
| Belgium | tcp://185.69.166.7:9651 | 597:a4ef:806:b09:6650:cbbf:1b68:cc94 |
| Belgium | tcp://185.69.166.8:9651 | 549:8bce:fa45:e001:cbf8:f2e2:2da6:a67c |
| Finland | tcp://65.21.231.58:9651 | 410:2778:53bf:6f41:af28:1b60:d7c0:707a |
| Finland | tcp://65.109.18.113:9651 | 488:74ac:8a31:277b:9683:c8e:e14f:79a7 |
| US East | tcp://209.159.146.190:9651 | 4ab:a385:5a4e:ef8f:92e0:1605:7cb6:24b2 |
| US West | tcp://5.78.122.16:9651 | 4de:b695:3859:8234:d04c:5de6:8097:c27c |
| Singapore| tcp://5.223.43.251:9651 | 5eb:c711:f9ab:eb24:ff26:e392:a115:1c0e |
| India | tcp://142.93.217.194:9651 | 445:465:fe81:1e2b:5420:a029:6b0:9f61 |
**Using the App?** Just copy these addresses and paste them into the Peers section.
**Using Command-Line?** Add multiple peers for better reliability:
```bash
sudo mycelium --peers \
tcp://188.40.132.242:9651 \
tcp://185.69.166.8:9651 \
tcp://185.69.166.7:9651 \
tcp://65.21.231.58:9651
```
## What You Can Do Now
### SSH to Another Device
If you have SSH running on another device with Mycelium:
```bash
ssh user@5c4:c176:bf44:b2ab:5e7e:f6a:b7e2:11ca
```
### Access a Web Service
```bash
curl http://[5c4:c176:bf44:b2ab:5e7e:f6a:b7e2:11ca]:8080
```
Note: IPv6 addresses must be in brackets for URLs.
### Connect Multiple Devices
Run Mycelium on devices at different locations:
- They automatically find each other through the mesh.
- Use their Mycelium IPs to communicate.
- All traffic is encrypted end-to-end.
### Access ThreeFold Grid
Deploy workloads on the ThreeFold Grid and connect to them using your Mycelium connection. Use the ThreeFold Dashboard to deploy workloads with Mycelium enabled.
## Troubleshooting
### App Not Connecting
**Using the app:**
1. Restart the app.
2. Check your internet connection.
3. Add more peers.
4. Ensure the app isn't blocked by a firewall.
5. On Windows, run as administrator.
### Command-Line Issues
**Can't connect to peers:**
1. Check internet connectivity.
2. Try different peers.
3. Check firewall rules.
4. Ensure IPv6 is enabled.
**Can't ping other nodes:**
1. Wait a few minutes for network discovery.
2. Verify the address.
3. Check peer connections.
**Permission errors (Linux):**
- Must run with `sudo` to create the network interface.
- Check executable permissions: `chmod +x /usr/local/bin/mycelium`.
## What's Next?
Now that you're connected, explore what you can do:
- **Remote access** – Access services from anywhere.
- **Connect devices** – Link multiple locations securely.
- **ThreeFold Grid** – Access your grid deployments.
- **P2P applications** – Build distributed systems.
For more advanced setup options (custom ports, private peer networks, proxies, advanced routing), refer to the Mycelium GitHub repository.
## Resources
- **GitHub** – [github.com/threefoldtech/mycelium](https://github.com/threefoldtech/mycelium)
- **Community** – [t.me/threefold/1](https://t.me/threefold/1)
- **Forum** – [forum.threefold.io](https://forum.threefold.io)
:::tip Connected Successfully?
You're now part of the global Mycelium network. Next, explore **[Mycelium Cloud](/cloud)** to run workloads on the ThreeFold Grid.
:::