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

118
docs/ai-agent-framework/architecture.md Normal file
View File

@@ -0,0 +1,118 @@
---
sidebar_position: 2
---
# Agent Architecture & Design
This page summarizes the intended design of Mycelium Agents, based on the public descriptions on the main site. The details may evolve as we approach the 2026 launch.
## High‑Level View
From the **Agent Design** and **Advantages** sections:
- Each agent **runs entirely inside your environment**.
- Agents **communicate peer‑to‑peer** across trusted nodes.
- Agents **access data locally** without exposing it to external providers.
- Agents are **portable**, moving with your infrastructure rather than with a single cloud vendor.
Conceptually:
```mermaid
graph TD
A[Your Devices & Nodes] --> B[Agent Runtime]
B --> C[Local Data & Tools]
B --> D[Mycelium Network]
D --> E[Other Agents & Nodes]
```
- The **runtime** executes agent logic.
- Agents load and store data through local backends (files, QSFS, databases).
- Communication uses **Mycelium Network** between environments.
## Core Properties
### Local Execution
From the "Local Execution" highlight:
> *“Agents run entirely inside your environment. Models, logic, and memory stay within your own trusted hardware, never behind third‑party APIs.”*
Implications:
- You choose where agents run: laptop, homelab, edge cluster, or VDC.
- No requirement to send prompts or data to centralized AI APIs.
- Compliance and sovereignty become much easier to reason about.
### Mesh Connectivity
From the "Mesh Connectivity" highlight:
> *“They communicate peer‑to‑peer across trusted nodes. Agents form direct encrypted paths between environments, without relays or central servers.”*
This leverages **Mycelium Network** to:
- Give agents a global, encrypted address space.
- Enable cross‑site coordination (home ↔ office ↔ cloud ↔ edge).
- Avoid central bottlenecks and single points of failure.
### Private Data Access
From the "Private Data Access" highlight:
> *“They use your data without sending it elsewhere. Your datasets, embeddings, and context never leave your boundaries.”*
Design goals:
- Agents can work directly against local file systems, QSFS, and internal services.
- Sensitive inputs and outputs remain in environments you choose.
- Remote calls (if any) are explicit and policy‑controlled.
### Portability
From the "Portability" highlight:
> *“They move with you, not with a cloud provider. Agents follow your devices, networks, and workflows, remaining sovereign across every location.”*
Over time the framework aims to allow:
- Re‑deploying agents between different nodes and VDCs.
- Maintaining state while moving execution closer to data or users.
- Using heterogeneous infrastructure (homelab + hoster nodes + VDCs) as one fabric.
## Example Deployment Topologies
### Single‑Node Local Agent
- Agent runtime on your workstation.
- Local data and tools only.
- Mycelium Network used for optional remote access.
### Multi‑Node Mesh
- Agents running on several nodes (e.g. laptop, homelab, hoster node).
- P2P coordination over Mycelium.
- Some agents specialized for data access, others for orchestration.
### VDC‑Backed Agent Cluster
- Runtime deployed into a **VDC** as a set of Kubernetes workloads.
- Agents expose services reachable only via Mycelium Network.
- QSFS and other Mycelium components used for storage.
## Security & Trust (Preview)
From the "Security Architecture" and related messaging:
- **Provable sovereignty** – Assign workloads to trusted zones and verify state with cryptographic proofs.
- **Autonomous zero‑trust** – Identity, policy, and attestation enforced continuously.
- **Planetary‑scale resilience** – Mesh routing around failures, including regional outages.
As the framework evolves, expect more detailed specifications around:
- Identity & authentication between agents.
- Policy models for where and how agents may run.
- Auditability and observability of agent behavior.
## Status
The architecture described here is intentionally high‑level and forward‑looking. For timelines and how to prepare, see **[Overview](/ai-agent-framework/overview)** and **[Getting Ready for Agents](/ai-agent-framework/getting-ready)**.

84
docs/ai-agent-framework/getting-ready.md Normal file
View File

@@ -0,0 +1,84 @@
---
sidebar_position: 4
---
# Getting Ready for Agents
The Agent Framework is planned for **H1 2026**, but you can start preparing your infrastructure and workflows today.
This page is based on the "Call To Action" content from the Mycelium Agents page.
## 1. Establish the Networking Layer
Agents will rely on **Mycelium Network** for secure, peer‑to‑peer connectivity.
- Install and use **[Mycelium Network](/network)** on your key devices.
- Become comfortable with overlay addresses and testing connectivity.
- Decide which machines, clusters, and locations will be part of your "agent fabric".
## 2. Set Up Compute & Clusters
Use **Mycelium Cloud** and **Virtual Data Centers** as the compute substrate for future agents.
- Deploy clusters via **[Mycelium Cloud Getting Started](/cloud/getting-started)**.
- Explore **[Kubernetes Basics](/cloud/kubernetes-basics)** and the **[Deployment Tutorials](/cloud/tutorial)**.
- Design where different workloads should live (personal VDC, shared VDC, edge nodes, etc.).
If you plan to run larger AI workloads, consider capacity with GPUs or high‑memory nodes.
## 3. Decide How You’ll Host Capacity
If you want agents to run on hardware beyond your personal machines, look into becoming a **hoster**:
- Read **[Hosters Overview](/hosters/overview)** to understand the role.
- Choose hardware via **[Buy or Build a Node](/hosters/buy-node)** and **[Advanced Node Options](/hosters/advanced-nodes)**.
- Set up your node using **[Set Up Your Node](/hosters/setup)**.
- Learn about **[Hosting Economics (SPORE)](/hosters/economics)**.
This prepares a foundation where agents can later run on your own nodes or on community capacity.
## 4. Map Your Data & Privacy Requirements
Agents are meant to operate on **your** data, not someone else’s cloud silo.
Begin planning:
- Where your key datasets live today.
- Which data must stay in specific jurisdictions or networks.
- Which data could be processed on edge nodes, VDCs, or both.
- How quantum‑safe and replicated storage (e.g. QSFS) might fit into your architecture.
## 5. Start with Today’s Components
From the call‑to‑action message:
> *“The Agent Framework launches in H1 2026, but the foundation is ready now. Use today’s components — models, storage, compute, and network — to deploy workloads, connect nodes, and prepare for the next generation of distributed AI.”*
Practical steps you can take now:
- Deploy AI workloads on Mycelium Cloud clusters.
- Use Mycelium Network to connect dev machines, clusters, and edge boxes.
- Experiment with multi‑node workflows and data flows across environments.
- Treat these as early prototypes that agents will later formalize and automate.
## 6. Stay Informed
As the Agent Framework evolves, watch for:
- Updated documentation and architecture deep‑dives.
- Early SDKs, CLIs, or runtimes for prototyping.
- Example patterns combining agents, VDCs, and QSFS.
Follow official channels (site, docs, community) for announcements.
---
## Summary
You don’t need to wait for the Agent Framework launch to start building:
- Use **network**, **cloud**, **VDC**, and **hosting** pieces today.
- Organize data and infrastructure so that agents can slot in later.
- Think in terms of **sovereign, distributed AI** rather than centralized APIs.
When agents arrive, you’ll already have the networking, compute, and data foundations in place.

76
docs/ai-agent-framework/overview.md Normal file
View File

@@ -0,0 +1,76 @@
---
sidebar_position: 1
slug: /ai-agent-framework
---
# Mycelium Agent Framework (Preview)
> **Status:** Coming in 2026 – early design subject to change.
Mycelium Agents are **private, sovereign, and distributed AI systems** that run on infrastructure you control. Instead of sending your data and logic to a centralized AI cloud, agents live **inside your own environment** and connect over the **Mycelium Network**.
This page gives a high‑level preview of the framework and how it fits into the rest of Mycelium.
## What Are Mycelium Agents?
From the marketing overview:
> *“Private, Sovereign and Distributed AI You Control.”*
Mycelium Agents are designed so that:
- **Execution stays local** – Models, logic, and memory run on your own hardware.
- **Connectivity is peer‑to‑peer** – Agents communicate over Mycelium’s encrypted mesh.
- **Data remains private** – Your datasets, embeddings, and tools stay inside your trust boundary.
- **Agents are portable** – They can move with you across devices, clusters, and locations.
## Design Principles
The Agent Framework is being designed around a few core principles (see **Agent Design** and **Advantages** on the main site):
- **Inside your environment** – Each agent operates entirely within your chosen infrastructure (laptop, homelab, edge node, cluster).
- **Mesh connectivity** – Agents talk to each other across trusted nodes using Mycelium Network, without central relays.
- **Local data access** – Agents read and write data locally (file systems, QSFS, databases) without shipping it to a third‑party.
- **Zero‑trust posture** – Identity, policy, and attestation are enforced continuously.
- **Portability** – Agents follow your workflows, not a particular cloud provider.
## Relationship to the Rest of Mycelium
The Agent Framework is built on top of existing Mycelium components:
- **Mycelium Network** – Encrypted IPv6 overlay and addressing fabric between nodes.
- **Mycelium Cloud / VDC** – Kubernetes clusters and virtual data centers hosting compute.
- **QSFS / Storage** – Quantum‑safe, replicated storage for long‑term data and model artifacts.
- **Hosters** – Community‑run capacity providing the underlying infrastructure.
Agents are planned to run:
- On your own devices (laptops, workstations, homelabs).
- On edge or datacenter nodes provided by hosters.
- Inside VDCs as part of larger application stacks.
## What You Can Expect
While the full technical spec is still evolving, you can expect:
- A **runtime** for defining and running agents on your nodes.
- A **connectivity layer** for secure P2P communication between agents.
- A **policy model** for where agents may run and which data they may access.
- **Composability** with existing tools – containers, Kubernetes, storage backends, and Mycelium networking.
## Timeline and Scope
- **Launch window:** Agent Framework targeted for **H1 2026**.
- **Preview phase:** Before launch, expect design updates, early prototypes, and integration examples.
- **Ecosystem:** The goal is to make agents first‑class citizens of the wider Mycelium / ThreeFold ecosystem.
## How to Prepare
Although the Agent Framework itself is not yet released, you can prepare today by using the underlying components:
- **Networking:** Get familiar with **[Mycelium Network](/network)** and how overlay addressing works.
- **Compute:** Use **[Mycelium Cloud](/cloud)** and **[VDCs](/vdc)** to deploy clusters and workloads.
- **Capacity:** If you want to run agents on your own or community hardware, explore **[Hosters](/hosters)**.
- **Data:** Consider how sensitive data will be stored and accessed locally (e.g. QSFS).
See **[Getting Ready for Agents](/ai-agent-framework/getting-ready)** for a more practical checklist.

87
docs/ai-agent-framework/use-cases.md Normal file
View File

@@ -0,0 +1,87 @@
---
sidebar_position: 3
---
# Agent Use Cases
This page adapts the **Agent Use Cases** section from the Mycelium site into documentation form.
## What the Framework Enables
> *“The framework gives you full control over where agents live, how they connect, and what data they use.”*
Agents are intended to be:
- **Location‑aware** – you decide which nodes or VDCs they inhabit.
- **Network‑aware** – connectivity and topology are visible and controllable.
- **Data‑aware** – data stays where it should, with explicit movement.
## Example Use Cases
### Run Agents on Your Own Hardware
Deploy agents directly on:
- Laptops and workstations.
- Homelabs and edge boxes.
- VDCs and clusters you control.
You are not tied to any single cloud or vendor; agents execute where it makes the most sense for latency, privacy, or cost.
### Connect Agents Over the Mycelium Network
Use **Mycelium Network** as the secure fabric between agents.
- Private overlay addressing across homes, offices, and datacenters.
- Encrypted paths between nodes in different countries or environments.
- One consistent address space spanning local and remote infrastructure.
### Keep Data and Memory Private by Default
Agents are designed to:
- Use local datasets, tools, prompts, and embeddings.
- Avoid sending sensitive context to external AI APIs by default.
- Respect policies for which data may be shared and where.
This is especially important for regulated sectors and internal systems.
### Build Workflows Across Cloud + Edge
Orchestrate multi‑node workflows that span:
- Edge clusters near data sources.
- Central VDCs for heavier compute or aggregation.
- Personal devices for interaction and control.
Examples:
- Real‑time processing at the edge, with summarized results aggregated in a VDC.
- Agents coordinating tasks between office locations and remote workers.
- Data pipelines that never leave your chosen infrastructure.
### Operate in Regulated Contexts
Run agents where strict requirements apply:
- Healthcare, finance, public sector, and other regulated domains.
- Environments with **data residency** constraints.
- Workloads requiring verified identity and controlled connectivity.
The combination of **local execution**, **sovereign infrastructure**, and **encrypted mesh networking** is intended to make regulatory compliance more tractable.
### Blend Local and Remote Intelligence
Not all tasks need to run on the same node:
- Lightweight agents might run locally for responsiveness and interactivity.
- Heavier workloads can be scheduled to trusted remote nodes (e.g. GPU clusters).
- Data movement is explicit and policy‑driven.
This supports hybrid strategies where you balance privacy, performance, and cost.
---
## Looking Ahead
These use cases are **illustrative** and may expand as the Agent Framework matures. For how to prepare your infrastructure today, see **[Getting Ready for Agents](/ai-agent-framework/getting-ready)**.

289
docs/cloud/faq.md Normal file
View File

@@ -0,0 +1,289 @@
---
sidebar_position: 5
---
# Frequently Asked Questions
Common questions about deploying and managing Kubernetes clusters on Mycelium Cloud.
## General
### What is Mycelium Cloud?
Mycelium Cloud is a platform for deploying and managing Kubernetes clusters on the decentralized ThreeFold Grid infrastructure. It provides K3s clusters with Mycelium peer-to-peer networking, making it easy to run containerized applications on distributed, cost-effective infrastructure.
### What makes Mycelium Cloud different?
- **Decentralized Infrastructure** – Runs on ThreeFold Grid's distributed network
- **IPv6 Networking** – Built-in Mycelium peer-to-peer networking
- **Cost Effective** – Competitive pricing on decentralized infrastructure
- **No Vendor Lock-in** – Standard Kubernetes (K3s) – works with all K8s tools
- **Global Distribution** – Deploy across worldwide node locations
### Is it suitable for production workloads?
Yes! Mycelium Cloud supports production workloads with:
- High availability cluster configurations (multi-master)
- Persistent storage options
- Monitoring and logging capabilities
- Standard Kubernetes security features
## Getting Started
### How do I create an account?
1. Visit [Mycelium Cloud](https://myceliumcloud.tf)
2. Fill in your registration details
3. Verify your email address
4. Add credits and SSH keys from your dashboard
See the **[Getting Started Guide](/cloud/getting-started)** for detailed steps.
### What do I need to get started?
- **Mycelium installed** – For network access ([Install guide](/network/install))
- **kubectl installed** – For cluster management ([Install kubectl](https://kubernetes.io/docs/tasks/tools/))
- **SSH key pair** – For node access
- **Account credits** – To fund your deployments
### What Kubernetes version is supported?
Mycelium Cloud uses **K3s v1.26+**, which provides:
- Full Kubernetes API compatibility
- Lightweight resource usage
- High availability features
- Dual-stack networking (IPv4/IPv6)
## Cluster Management
### How do I access my cluster?
Two methods:
**1. kubectl (Recommended):**
```bash
# Download kubeconfig from dashboard
export KUBECONFIG=/path/to/mycluster-config.yaml
kubectl get nodes
```
**2. SSH:**
```bash
# Start Mycelium, then SSH to node IPs
ssh root@<mycelium-ip>
```
See **[Getting Started](/cloud/getting-started#step-4-access-your-cluster)** for details.
### Can I scale my cluster after deployment?
Yes! You can:
- Add or remove worker nodes through the dashboard
- Scale applications independently using kubectl
- Modify cluster configuration
```bash
# Scale deployment
kubectl scale deployment myapp --replicas=5
```
### What happens if a node fails?
- **Worker Node Failure** – Kubernetes automatically reschedules pods to healthy nodes
- **Master Node Failure** – In HA setups (3+ masters), other masters take over
- **Self-Healing** – Pods are automatically restarted if they crash
## Networking
### How do I expose applications to the internet?
Options include:
**1. NodePort Services:**
```yaml
type: NodePort
```
**2. Port Forwarding (Development):**
```bash
kubectl port-forward service/myapp 8080:80
```
**3. Ingress Controllers:**
Set up an ingress controller for HTTP/HTTPS routing with custom domains.
### Do I need public IP addresses?
No! Mycelium Cloud uses **Mycelium networking**:
- Each node gets a unique Mycelium IPv6 address
- Access nodes and services via Mycelium network
- All traffic encrypted end-to-end
- No need for public IPs or complex firewall configurations
## Troubleshooting
### My cluster deployment failed. What should I do?
1. **Check Logs** – Review deployment logs in the dashboard
2. **Verify Credits** – Ensure sufficient account balance
3. **Node Availability** – Confirm selected nodes are available
4. **Configuration** – Validate cluster configuration settings
5. **Contact Support** – If issues persist, reach out via Telegram or GitHub
### I can't connect with kubectl. How do I fix this?
```bash
# 1. Verify kubeconfig is set
echo $KUBECONFIG
# 2. Check Mycelium is running
# (Open Mycelium app or run: sudo mycelium --peers ...)
# 3. Test cluster connectivity
kubectl cluster-info
# 4. Verify cluster is running in dashboard
```
Common issues:
- Mycelium not running on your machine
- Wrong kubeconfig file path
- Cluster stopped in dashboard
- Network firewall blocking connections
### My pods are not starting. What's wrong?
```bash
# Check pod status
kubectl get pods
# Describe pod for events
kubectl describe pod <pod-name>
# Check logs
kubectl logs <pod-name>
# Check node resources
kubectl top nodes
```
Common causes:
- **Resource Limits** – Insufficient CPU/memory on nodes
- **Image Issues** – Cannot pull container images
- **Configuration** – Invalid pod specifications
- **Storage** – Persistent volume issues
### How do I check cluster health?
```bash
# Check node status
kubectl get nodes
# Check system pods
kubectl get pods -n kube-system
# View events
kubectl get events --sort-by=.metadata.creationTimestamp
# Check resource usage
kubectl top nodes
kubectl top pods
```
## Storage & Data
### How do I persist data?
Use **PersistentVolumeClaims** (PVCs):
```yaml
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
name: my-data
spec:
accessModes:
- ReadWriteOnce
resources:
requests:
storage: 10Gi
```
See **[Deployment Tutorials](/cloud/tutorial#tutorial-3-stateful-application-with-persistent-storage)** for a complete example.
### How do I backup my cluster?
Backup strategies:
- **Application Data** – Use PVC snapshots or backup tools
- **Configurations** – Version control your YAML manifests in Git
- **etcd Snapshots** – Cluster state backups (advanced)
## Security
### How secure is Mycelium Cloud?
Security features:
- **Encrypted Communication** – All traffic encrypted via Mycelium network
- **Network Isolation** – Secure pod-to-pod communication
- **RBAC** – Kubernetes role-based access control
- **SSH Key Authentication** – Secure node access
- **No Public IPs** – Reduced attack surface
### How do I manage secrets?
Use Kubernetes Secrets:
```bash
# Create secret
kubectl create secret generic db-password --from-literal=password=mypassword
# Use in pod
env:
- name: DB_PASSWORD
valueFrom:
secretKeyRef:
name: db-password
key: password
```
See **[Kubernetes Basics](/cloud/kubernetes-basics#secrets)** for more details.
## Getting Help
### Where can I get more information and support?
- **Documentation** – [Getting Started](/cloud/getting-started), [Deployment Tutorials](/cloud/tutorial)
- **Community** – [ThreeFold Telegram](https://t.me/threefold/1)
### How do I report a bug?
1. Check existing [GitHub Issues](https://github.com/codescalers/kubecloud/issues)
2. Create a new issue with:
- Cluster configuration
- Error messages and logs
- Steps to reproduce
- Expected vs actual behavior
---
## Still Have Questions?
Check out these resources:
- **[Getting Started Guide](/cloud/getting-started)** – Step-by-step cluster deployment
- **[Deployment Tutorials](/cloud/tutorial)** – Practical deployment examples
- **[Kubernetes Basics](/cloud/kubernetes-basics)** – Essential K8s concepts
- **[Kubernetes Documentation](https://kubernetes.io/docs/)** – Official K8s docs

233
docs/cloud/for-developers.md Normal file
View File

@@ -0,0 +1,233 @@
---
sidebar_position: 6
---
# Mycelium Cloud for Developers
*Developer Guide to Decentralized Cloud Computing*
## Overview
Mycelium Cloud provides a comprehensive platform for deploying and managing Kubernetes clusters on the decentralized ThreeFold Grid infrastructure. This guide covers the core features and capabilities available to developers.
## Architecture
### Decentralized Infrastructure
Mycelium Cloud deploys on ThreeFold Grid's distributed network, providing:
- **Direct Node Access** – Each node gets a unique Mycelium IP address
- **Cross-Node Communication** – Services communicate across nodes using Mycelium networking
- **Secure Communication** – All traffic is encrypted through the Mycelium network
- **No Public IPs Required** – Services accessible via Mycelium IPs
### Network Flow
User Machine → Mycelium Network → Cluster Node → Service
### Kubernetes Management
- **K3s Support** – Full K3s cluster deployment and management
- **IPv6 Networking** – Mycelium peer-to-peer networking
- **High Availability** – Multi-master cluster support
---
## Core Features
### Mycelium Networking
Ultra-fast, decentralized networking inspired by nature. Mycelium Networking forms a resilient, adaptive mesh that routes around failures and optimizes for speed and security.
**Features:**
- End-to-end encrypted
- Nature-inspired
- Direct node communication
- Secure peer-to-peer connections
### Zero-Image Technology
Metadata-driven zero-images cut artifacts up to 100x, slashing bandwidth and deployment overhead.
**Benefits:**
- **Deterministic Deployments** – Cryptographic verification ensures every workload deploys exactly as intended—no tampering, no drift
- **Multi-Workload Compatibility with Secure Boot** – Run containers, VMs, and Linux workloads anywhere with stateless secure boot and continuous verification
- **Smart Contract-Based Deployment** – Cryptographically signed contracts orchestrate every workload with transparent, tamper-proof execution
### Quantum-Safe Storage (QSS)
Quantum-resistant encryption secures data beyond the app layer so ownership and control stay yours.
**Features:**
- **Self-Healing Storage System** – Autonomous recovery heals failures or corruption instantly, preserving integrity without human intervention
- **Multi-Protocol Data Access** – Serve the same data via IPFS, S3, WebDAV, HTTP, and native file systems for seamless integration
- **Geo-Aware Data Placement & Replication** – Define residency, redundancy, and distribution per workload while zone-to-zone replication hardens resilience
### Multi-Master Clusters
High-availability Kubernetes clusters with multiple control plane nodes. Automatic failover, leader election, and zero-downtime upgrades built-in.
**Capabilities:**
- **HA Control Plane**
- **Automatic Failover**
- **Zero-downtime Upgrades**
### Effortless Load Balancing & Scaling
Mycelium Cloud automatically balances traffic and scales your services up or down based on demand. Enjoy high availability and optimal performance with zero manual intervention.
**Features:**
- **Auto-scaling**
- **Built-in load balancing**
- **High availability**
### Simple Web Gateway Access
Expose any service to the public web with a simple Kubernetes resource. No complex Ingress controllers. Domain and prefix-based routing is built-in.
**Benefits:**
- **Simple configuration**
- **Built-in routing**
- **No ingress controllers**
---
## Getting Started
### 1. Account Setup
- **Sign Up** – Create your account from the signup page
- **Verify Email** – Check your email and verify your account
- **Add Funds** – Navigate to your dashboard and add credits to your account
- **Add SSH Key** – Navigate to the *Add SSH* card and upload your public SSH key
### 2. Deploy Your First Cluster
- **Access Deploy** – Click **Deploy Cluster** from your dashboard
- **Configure VMs** – Define your virtual machines:
- Choose CPU, memory, and storage requirements
- Select the number of master and worker nodes
- **Select Nodes** – Choose ThreeFold Grid nodes for deployment
- **Review & Deploy** – Confirm your configuration and deploy
### 3. Access Your Cluster
#### Download kubeconfig
- Go to **Dashboard → Clusters** and click the download icon (⬇️)
- Set kubeconfig: `export KUBECONFIG=/path/to/config`
- Test: `kubectl get nodes`
#### SSH Access
- **Find Mycelium IPs** – Check cluster details page for node IPs
- **Download Mycelium Binary (Linux example):**
```bash
wget https://github.com/threefoldtech/mycelium/releases/latest/download/mycelium-private-x86_64-unknown-linux-musl.tar.gz
tar -xzf mycelium-private-x86_64-unknown-linux-musl.tar.gz
sudo chmod +x mycelium-private
sudo mv mycelium-private /usr/local/bin/mycelium
```
- **Start Mycelium:**
```bash
sudo mycelium --peers \
tcp://188.40.132.242:9651 \
tcp://136.243.47.186:9651 \
tcp://185.69.166.7:9651 \
tcp://185.69.166.8:9651 \
tcp://65.21.231.58:9651 \
tcp://65.109.18.113:9651 \
tcp://209.159.146.190:9651 \
tcp://5.78.122.16:9651 \
tcp://5.223.43.251:9651 \
tcp://142.93.217.194:9651
```
- **SSH to nodes:** `ssh root@<mycelium-ip>`
---
## Use Cases
### AI/ML Training
Run GPU-accelerated workloads for deep learning and data science on demand.
- **GPU Acceleration**
- **Scalable Compute**
- **Cost Optimization**
### Enterprise Kubernetes
Deploy production-grade clusters with full control and no vendor lock-in.
- **High Availability**
- **Security**
- **Compliance**
### Edge & IoT
Leverage global nodes for low-latency edge computing and IoT applications.
- **Low Latency**
- **Global Distribution**
- **Real-time Processing**
### DigitalMe Example
Example of what can be done with Mycelium Cloud. With a very simple execution, the following can be deployed on a K8s cluster and served on Mycelium IPs:
- **Cryptpad** – Encrypted document collaboration
- **Elements** – Matrix chat (the Rust one)
- **Stallwart** – Mail/calendar/contacts
- **Gitea** – Git hosting and code collaboration
- **Nextcloud** – File storage and synchronization
- **LiveKit or Jitsi** – Video conferencing integrated with Elements/Nextcloud
- **SSO** – Single Sign-On (future integration)
This demonstrates the platform's capability to host complex, integrated applications with minimal configuration.
---
## Key Differentiators
### Sovereign by Design
Control jurisdiction, residency, and governance for every workload with transparent, verifiable operations.
### Secure by Default
Cryptographic verification, secure boot, and zero-image delivery protect the entire lifecycle automatically.
### Ready to Scale
Autonomous orchestration keeps the platform elastic, cost-efficient, and always available across the globe.
---
## Security Architecture
### Provable Sovereignty
Assign workloads to trusted zones, verify state with cryptographic proofs, and maintain full lineage for every byte.
### Autonomous Zero-Trust
Identity, policy, and attestation are enforced continuously—no manual keys, no hidden backdoors, no shared control.
### Planetary-Scale Resilience
Mesh-connected infrastructure routes around failure, keeping applications responsive even when regions go dark.
---
*Mycelium Cloud – Comprehensive platform for decentralized Kubernetes deployment.*

347
docs/cloud/getting-started.md Normal file
View File

@@ -0,0 +1,347 @@
---
sidebar_position: 2
---
# Getting Started with Mycelium Cloud
Deploy your first Kubernetes cluster on the ThreeFold Grid in just a few steps.
## Prerequisites
Before you begin, make sure you have:
- ✅ **Mycelium installed** – Easy app for iOS, Android, macOS, Windows ([Install guide](/network/install))
- ✅ **SSH key pair** – For node access
- ✅ **kubectl installed** – For managing your cluster ([Install kubectl](https://kubernetes.io/docs/tasks/tools/))
- ✅ **Credits** – To fund your deployment
:::info Installing Mycelium is Easy!
Most users can install the Mycelium app from their App Store or download the desktop app – no command-line needed!
:::
## Step 1: Create Your Account
### Sign Up
1. Go to [Mycelium Cloud](https://myceliumcloud.tf/)
2. Fill in your details:
- Email address
- Password
- Confirm password
3. Click **Sign Up**
### Verify Email
1. Check your email inbox
2. Click the verification link
3. Your account is now active
## Step 2: Set Up Your Account
### Add Credits
1. Log in to your dashboard
2. Navigate to **Credits** or **Billing** section
3. Add funds to your account
- Choose payment method
- Enter amount
- Complete payment
Your credits will be used to pay for cluster resources (CPU, RAM, storage, time).
### Add SSH Key
1. Navigate to **SSH Keys** section (or **Add SSH** card)
2. Click **Add SSH Key**
3. Paste your **public key** (usually `~/.ssh/id_rsa.pub`)
4. Give it a name
5. Save
:::tip Need an SSH Key?
If you don't have one:
```bash
# Generate a new SSH key pair
ssh-keygen -t rsa -b 4096 -C "your_email@example.com"
# View your public key
cat ~/.ssh/id_rsa.pub
```
Copy the output and paste it into the dashboard.
:::
## Step 3: Deploy Your First Cluster
### Access Deployment Page
1. From your dashboard, click **Deploy Cluster** or **New Cluster**
2. You'll see the cluster configuration wizard
### Configure Your Cluster
#### Basic Settings
- **Cluster Name**: Give your cluster a unique name
- **Description**: Optional description of the cluster purpose
#### Master Nodes
Configure your control plane nodes:
- **Count**: Number of master nodes
- 1 for development/testing
- 3 for production (high availability)
- **CPU**: Number of cores per master (2–4 recommended)
- **RAM**: Memory per master (4–8GB recommended)
- **Storage**: Disk space per master (20–50GB)
#### Worker Nodes
Configure your workload nodes:
- **Count**: Number of worker nodes (1–10+)
- **CPU**: Cores per worker (based on workload)
- **RAM**: Memory per worker (based on workload)
- **Storage**: Disk space per worker (based on workload)
**Example Configuration (Starter):**
```text
Masters: 1 node (2 CPU, 4GB RAM, 25GB storage)
Workers: 2 nodes (2 CPU, 4GB RAM, 50GB storage each)
```
### Select Nodes
1. The system will show available ThreeFold Grid nodes
2. Select nodes for your deployment
- Choose based on location, specs, and availability
- System may auto-select optimal nodes
3. Review your selections
### Review & Deploy
1. Review your configuration:
- Node counts and specs
- Selected grid nodes
- Estimated cost
2. Confirm you have sufficient credits
3. Click **Deploy**
The deployment process will begin. This typically takes 5–15 minutes.
## Step 4: Access Your Cluster
Once deployed, you can access your cluster in two ways: kubectl and SSH.
### Method 1: kubectl Access
#### Download kubeconfig
1. Go to **Dashboard** → **Clusters**
2. Find your cluster
3. Click the download icon (⬇️) or **Get Config**
4. Save the file (e.g., `mycluster-config.yaml`)
#### Configure kubectl
```bash
# Set kubeconfig for this session
export KUBECONFIG=/path/to/mycluster-config.yaml
# Or copy to default location
mkdir -p ~/.kube
cp mycluster-config.yaml ~/.kube/config
# Test connection
kubectl get nodes
```
You should see your cluster nodes listed:
```text
NAME STATUS ROLES AGE VERSION
master-1 Ready control-plane,master 10m v1.26.0+k3s1
worker-1 Ready <none> 9m v1.26.0+k3s1
worker-2 Ready <none> 9m v1.26.0+k3s1
```
### Method 2: SSH Access
#### Start Mycelium
If not already running, start Mycelium on your local machine:
**Using the App (Easy):**
1. Open the Mycelium app
2. Click **Start**
3. That's it!
**Using Command-Line (Linux):**
```bash
sudo mycelium --peers \
tcp://188.40.132.242:9651 \
tcp://185.69.166.8:9651
```
#### Get Node IPs
From your dashboard:
1. Go to your cluster details
2. Find the **Mycelium IPs** for each node
3. Note them down (e.g., `400:1234:5678:abcd::1`)
#### SSH to Nodes
```bash
# SSH to master node
ssh root@400:1234:5678:abcd::1
# SSH to worker node
ssh root@400:1234:5678:abcd::2
```
You're now connected to your cluster node!
## Step 5: Deploy Your First Application
Let's deploy a simple web application to test your cluster.
### Create a Deployment
```bash
# Create an nginx deployment
kubectl create deployment hello-web --image=nginx:latest
# Check deployment status
kubectl get deployments
kubectl get pods
```
### Expose the Service
```bash
# Expose as a service
kubectl expose deployment hello-web --port=80 --type=ClusterIP
# Check service
kubectl get services
```
### Access the Service
```bash
# Port forward to your local machine
kubectl port-forward service/hello-web 8080:80
```
Open `http://localhost:8080` in your browser. You should see the nginx welcome page!
## Step 6: Monitor Your Cluster
### Using Dashboard
Your Mycelium Cloud dashboard shows:
- Cluster status (running, stopped, etc.)
- Resource usage
- Cost tracking
- Node health
### Using kubectl
```bash
# View cluster info
kubectl cluster-info
# Check node status
kubectl get nodes
# View all resources
kubectl get all --all-namespaces
# Check cluster events
kubectl get events
```
## Managing Your Cluster
### Scale Workers
Add more worker nodes:
1. Go to cluster details in dashboard
2. Click **Scale** or **Add Nodes**
3. Configure new worker nodes
4. Deploy
### Delete Resources
```bash
# Delete the test deployment
kubectl delete deployment hello-web
kubectl delete service hello-web
```
### Stop/Start Cluster
From the dashboard:
- **Stop**: Pause cluster (saves costs)
- **Start**: Resume cluster
- **Delete**: Permanently remove (frees all resources)
## Troubleshooting
### Can't Connect with kubectl
1. **Check kubeconfig** – Ensure `KUBECONFIG` is set correctly
2. **Verify Mycelium** – Make sure Mycelium is running
3. **Check cluster status** – Ensure cluster is running in dashboard
4. **Test network** – Try pinging cluster nodes via Mycelium IPs
```bash
# Test Mycelium connectivity
ping6 <cluster-node-mycelium-ip>
```
### Can't SSH to Nodes
1. **Mycelium running** – Ensure Mycelium daemon is active
2. **SSH key added** – Verify your public key is in dashboard
3. **Correct IP** – Double-check Mycelium IP from dashboard
4. **Network access** – Test with `ping6` first
### Pods Not Starting
```bash
# Check pod status
kubectl describe pod <pod-name>
# Check node resources
kubectl top nodes
# Check events
kubectl get events --sort-by='.lastTimestamp'
```
## Resources
- **[Mycelium Cloud](https://myceliumcloud.tf/)**
- **[Kubernetes Docs](https://kubernetes.io/docs/)**
- **[kubectl Cheat Sheet](https://kubernetes.io/docs/reference/kubectl/cheatsheet/)**
- **[Community Chat](https://t.me/threefold/1)**
---
:::tip Cluster Running Successfully?
Great! Now try the **[Deployment Tutorials](/cloud/tutorial)** to deploy more complex applications.
:::

344
docs/cloud/kubernetes-basics.md Normal file
View File

@@ -0,0 +1,344 @@
---
sidebar_position: 4
---
# Kubernetes Basics
Essential Kubernetes concepts for deploying applications on Mycelium Cloud.
## What is Kubernetes?
Kubernetes (K8s) is a container orchestration platform that automates deploying, scaling, and managing containerized applications. Mycelium Cloud uses **K3s**, a lightweight Kubernetes distribution perfect for edge and cloud environments.
### Why Kubernetes?
- **Automated Deployment** – Deploy containers across multiple nodes
- **Self-Healing** – Automatically restart failed containers
- **Horizontal Scaling** – Scale applications up or down based on demand
- **Service Discovery** – Automatic DNS and load balancing
- **Rolling Updates** – Update applications with zero downtime
## Core Concepts
### Pods
A **Pod** is the smallest deployable unit in Kubernetes. It represents one or more containers that share:
- Network namespace (same IP address)
- Storage volumes
- Configuration
```yaml
apiVersion: v1
kind: Pod
metadata:
name: nginx-pod
spec:
containers:
- name: nginx
image: nginx:1.21
ports:
- containerPort: 80
```
```bash
# View pods
kubectl get pods
# View pod details
kubectl describe pod nginx-pod
# View pod logs
kubectl logs nginx-pod
```
### Deployments
A **Deployment** manages a replicated set of Pods and provides declarative updates.
Features:
- **Replica Management** – Maintain desired number of pods
- **Rolling Updates** – Update pods with zero downtime
- **Rollback** – Revert to previous versions
- **Self-Healing** – Replace failed pods automatically
```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: nginx-deployment
spec:
replicas: 3
selector:
matchLabels:
app: nginx
template:
metadata:
labels:
app: nginx
spec:
containers:
- name: nginx
image: nginx:1.21
ports:
- containerPort: 80
```
```bash
# Create deployment
kubectl apply -f deployment.yaml
# View deployments
kubectl get deployments
# Scale deployment
kubectl scale deployment nginx-deployment --replicas=5
# Update image
kubectl set image deployment/nginx-deployment nginx=nginx:1.22
```
### Services
**Services** provide stable network endpoints for accessing pods.
#### ClusterIP (Default)
Internal-only service, accessible within the cluster:
```yaml
apiVersion: v1
kind: Service
metadata:
name: my-service
spec:
type: ClusterIP
selector:
app: nginx
ports:
- port: 80
targetPort: 80
```
#### NodePort
Exposes service on each node's IP at a static port:
```yaml
apiVersion: v1
kind: Service
metadata:
name: my-service
spec:
type: NodePort
selector:
app: nginx
ports:
- port: 80
targetPort: 80
nodePort: 30080 # 30000-32767
```
```bash
# View services
kubectl get services
# Describe service
kubectl describe service my-service
```
### Namespaces
**Namespaces** provide logical isolation for resources within a cluster.
```bash
# List namespaces
kubectl get namespaces
# Create namespace
kubectl create namespace my-app
# Use namespace
kubectl get pods -n my-app
```
## Storage
### Persistent Volumes
**PersistentVolumeClaim (PVC)** – Request for storage:
```yaml
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
name: pvc-data
spec:
accessModes:
- ReadWriteOnce
resources:
requests:
storage: 10Gi
```
Use in pod:
```yaml
spec:
containers:
- name: app
image: myapp:latest
volumeMounts:
- name: data
mountPath: /data
volumes:
- name: data
persistentVolumeClaim:
claimName: pvc-data
```
## Configuration
### ConfigMaps
Store non-sensitive configuration data:
```yaml
apiVersion: v1
kind: ConfigMap
metadata:
name: app-config
data:
database_url: "postgres://db:5432/mydb"
log_level: "info"
```
```bash
# Create from literal
kubectl create configmap app-config --from-literal=key=value
# View configmaps
kubectl get configmaps
```
### Secrets
Store sensitive data (passwords, tokens, keys):
```yaml
apiVersion: v1
kind: Secret
metadata:
name: app-secret
type: Opaque
data:
password: cGFzc3dvcmQxMjM= # base64 encoded
```
```bash
# Create secret
kubectl create secret generic app-secret --from-literal=password=password123
# View secrets
kubectl get secrets
```
## Essential kubectl Commands
```bash
# Cluster info
kubectl cluster-info
kubectl get nodes
# Pods
kubectl get pods
kubectl get pods -o wide
kubectl describe pod <pod-name>
kubectl logs <pod-name>
kubectl logs -f <pod-name> # Follow logs
kubectl exec -it <pod-name> -- /bin/bash
# Deployments
kubectl get deployments
kubectl scale deployment <name> --replicas=5
kubectl rollout status deployment/<name>
kubectl rollout undo deployment/<name>
# Services
kubectl get services
kubectl describe service <service-name>
# Apply/Delete resources
kubectl apply -f file.yaml
kubectl delete -f file.yaml
# Port forwarding
kubectl port-forward pod/<pod-name> 8080:80
kubectl port-forward service/<service-name> 8080:80
# View all resources
kubectl get all --all-namespaces
# Check events
kubectl get events --sort-by=.metadata.creationTimestamp
```
## Labels and Selectors
**Labels** are key-value pairs attached to objects:
```yaml
metadata:
labels:
app: nginx
environment: production
tier: frontend
```
**Selectors** query objects by labels:
```bash
# Get pods with label
kubectl get pods -l app=nginx
# Get pods with multiple labels
kubectl get pods -l app=nginx,environment=production
```
## Best Practices
1. **Use Deployments** – Not bare pods, for self-healing and scaling
```yaml
resources:
requests:
memory: "64Mi"
cpu: "250m"
limits:
memory: "128Mi"
cpu: "500m"
```
2. **Use Health Checks** – Implement liveness and readiness probes
3. **Use Namespaces** – Organize resources logically
4. **Version Control** – Store manifests in Git
5. **Use Labels** – Tag resources for organization
6. **Secrets Management** – Never hardcode sensitive data
## Next Steps
- **[Deployment Tutorials](/cloud/tutorial)** – Deploy real applications
- **[FAQ](/cloud/faq)** – Common questions and answers
## Additional Resources
- **Kubernetes Documentation**: [kubernetes.io/docs](https://kubernetes.io/docs/)
- **kubectl Cheat Sheet**: [kubernetes.io/docs/reference/kubectl/cheatsheet](https://kubernetes.io/docs/reference/kubectl/cheatsheet/)
- **K3s Documentation**: [docs.k3s.io](https://docs.k3s.io/)
---
:::tip Want to Learn More?
This covers the basics to get you started. For advanced topics like StatefulSets, DaemonSets, Ingress, and RBAC, check out the comprehensive Kubernetes documentation linked above.
:::

194
docs/cloud/overview.md Normal file
View File

@@ -0,0 +1,194 @@
---
sidebar_position: 1
slug: /cloud
---
# What is Mycelium Cloud?
Mycelium Cloud lets you deploy and manage **Kubernetes clusters** on the decentralized ThreeFold Grid infrastructure.
Run your containerized workloads on distributed, cost-effective infrastructure with built-in security and global availability.
## How It Works
Mycelium Cloud provides a complete platform for cloud-native applications:
1. **Sign up** for an account.
2. **Add credits** to fund your deployments.
3. **Deploy clusters** with custom configurations.
4. **Manage workloads** using standard Kubernetes tools.
All of this runs on the ThreeFold Grid's decentralized infrastructure.
## Why Use Mycelium Cloud?
### 🌍 Decentralized Infrastructure
- Deploy on ThreeFold Grid's distributed network.
- No dependency on centralized cloud providers.
- Global node distribution.
- True infrastructure sovereignty.
### 📦 Full Kubernetes Management
- **K3s clusters** – Lightweight, production-ready Kubernetes.
- **Multi-master support** – High availability configurations.
- **Standard tooling** – Use `kubectl`, Helm, and your favorite tools.
- **Complete control** – Full cluster access.
### 🔐 Secure by Default
- **Mycelium networking** – Encrypted peer-to-peer connections.
- **No public IPs needed** – Access via the Mycelium overlay network.
- **End-to-end encryption** – All traffic secured.
- **Private by design** – Your infrastructure, your control.
### 💰 Cost Effective
- **Competitive pricing** on decentralized infrastructure.
- **Pay for what you use** – Flexible resource allocation.
- **No vendor lock-in** – Standard Kubernetes portability.
- **Global availability** – Deploy where you need.
## Key Features
| Feature | Description |
|---------|-------------|
| **K3s Kubernetes** | Lightweight, certified Kubernetes distribution |
| **Mycelium Networking** | IPv6 overlay with encrypted P2P connections |
| **High Availability** | Multi-master clusters for production workloads |
| **Global Nodes** | Deploy across worldwide ThreeFold Grid locations |
| **Standard APIs** | Use `kubectl`, Helm, and all Kubernetes tools |
| **Web Dashboard** | Manage clusters through an intuitive UI |
| **SSH Access** | Direct node access for debugging and management |
| **Flexible Sizing** | Custom CPU, RAM, and storage configurations |
## Architecture
Mycelium Cloud uses peer-to-peer networking for direct access:
```
┌────────────────┐
│ Your Machine │
│ (kubectl) │
└───────┬────────┘
│
│ Mycelium Network
│ (encrypted P2P)
│
┌───────▼──────────────────────────────┐
│ Kubernetes Cluster │
│ ┌──────────┐ ┌──────────┐ │
│ │ Master │ │ Worker │ ... │
│ │ Node │ │ Node │ │
│ └──────────┘ └──────────┘ │
└──────────────────────────────────────┘
ThreeFold Grid Infrastructure
```
**Network flow:**
- Your machine connects via the Mycelium network.
- Each cluster node has a unique Mycelium IPv6 address.
- All communication is encrypted end-to-end.
- Direct node access – no gateways or proxies.
## Common Use Cases
### Development & Testing
- Spin up test clusters quickly.
- Experiment with Kubernetes features.
- CI/CD pipeline testing.
- Multi-environment development.
### Production Workloads
- Web applications and APIs.
- Microservices architectures.
- Databases and stateful services.
- Background processing jobs.
### Decentralized Applications
- P2P services.
- Distributed computing.
- Edge computing deployments.
- Privacy-focused applications.
### Learning Kubernetes
- Hands-on practice.
- Tutorial environments.
- Training clusters.
- Safe experimentation.
## Technology Stack
- **Kubernetes:** K3s v1.26+ (production-ready, lightweight).
- **Networking:** Mycelium CNI with IPv6 support.
- **Infrastructure:** ThreeFold Grid decentralized nodes.
- **Management:** Web dashboard + API + `kubectl`.
## What You Get
When you deploy a cluster:
- ✅ **Fully configured K3s cluster** – Ready to use.
- ✅ **Mycelium networking** – Secure connectivity.
- ✅ **kubeconfig file** – Standard `kubectl` access.
- ✅ **SSH access** – Direct node management.
- ✅ **Dashboard monitoring** – Cluster status and metrics.
- ✅ **Flexible scaling** – Add/remove nodes as needed.
## Getting Started
Ready to deploy your first cluster? Start here:
1. **[Getting Started](/cloud/getting-started)** – Create an account and deploy.
2. **[Deployment Tutorials](/cloud/tutorial)** – Deploy your first applications.
:::info Prerequisites
You should have:
- **Mycelium installed** – For network access. See **[Install Mycelium Network](/network/install)**.
- **`kubectl` installed** – For cluster management.
- **SSH key** – For node access.
- **Credits** – To fund your deployments.
:::
## Pricing
Pricing is based on resource usage:
- CPU cores.
- RAM allocation.
- Storage capacity.
- Deployment duration.
Check the dashboard for current rates. The decentralized infrastructure typically offers competitive pricing compared to traditional cloud providers.
## Resources
- **Mycelium Cloud** – [myceliumcloud.tf](https://myceliumcloud.tf)
- **Kubernetes Basics** – [/cloud/kubernetes-basics](/cloud/kubernetes-basics)
- **FAQ** – [/cloud/faq](/cloud/faq)
- **Kubernetes Docs** – [kubernetes.io/docs](https://kubernetes.io/docs/)
- **Community Chat** – [t.me/threefold/1](https://t.me/threefold/1)
- **GitHub Repository** – [github.com/codescalers/kubecloud](https://github.com/codescalers/kubecloud)
## Comparison to Traditional Cloud
| Aspect | Mycelium Cloud | Traditional Cloud |
|------------------|----------------|-----------------------|
| Infrastructure | Decentralized | Centralized |
| Control | Full sovereignty | Vendor-controlled |
| Networking | P2P encrypted | Public IPs, gateways |
| Pricing | Competitive | Often expensive |
| Lock-in | None (standard K8s) | Vendor-specific |
| Privacy | High | Varies by provider |
| Setup | Quick & simple | Can be complex |
:::tip Next Step
Ready to deploy? Start with the **[Getting Started Guide](/cloud/getting-started)** to create your first cluster.
:::

571
docs/cloud/tutorial.md Normal file
View File

@@ -0,0 +1,571 @@
---
sidebar_position: 3
---
# Deployment Tutorials
Learn by example with these practical deployment tutorials for Mycelium Cloud.
## Prerequisites
Before starting these tutorials, ensure you have:
- ✅ Deployed cluster with kubectl access
- ✅ Mycelium running for network access
- ✅ kubectl configured with your cluster
```bash
# Verify your setup
kubectl get nodes
# Should show your cluster nodes
```
## Tutorial 1: Hello World with Nginx
Deploy a simple web server to verify your cluster is working.
### Step 1: Create the Deployment
Save as `hello-world-deploy.yaml`:
```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: hello-world
spec:
replicas: 1
selector:
matchLabels:
app: hello-world
template:
metadata:
labels:
app: hello-world
spec:
containers:
- name: nginx
image: nginx:1.21
ports:
- containerPort: 80
```
Apply it:
```bash
kubectl apply -f hello-world-deploy.yaml
```
### Step 2: Expose the Service
Save as `hello-world-svc.yaml`:
```yaml
apiVersion: v1
kind: Service
metadata:
name: hello-world-service
spec:
selector:
app: hello-world
ports:
- port: 80
targetPort: 80
type: ClusterIP
```
Apply it:
```bash
kubectl apply -f hello-world-svc.yaml
```
### Step 3: Access Your Application
```bash
# Port forward to local machine
kubectl port-forward service/hello-world-service 8080:80
```
Open `http://localhost:8080` – you should see the Nginx welcome page!
### Cleanup
```bash
kubectl delete -f hello-world-deploy.yaml
kubectl delete -f hello-world-svc.yaml
```
## Tutorial 2: Python Servers with Load Balancing
Deploy multiple Python HTTP servers to demonstrate load balancing.
### Step 1: Create the Deployments
Save as `python-servers.yaml`:
```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: python-server-1
spec:
replicas: 2
selector:
matchLabels:
app: python-server
server-id: "1"
template:
metadata:
labels:
app: python-server
server-id: "1"
spec:
containers:
- name: python-server
image: python:3.9-slim
command: ["python", "-c"]
args:
- |
import http.server, socketserver, json
class Handler(http.server.SimpleHTTPRequestHandler):
def do_GET(self):
self.send_response(200)
self.send_header('Content-type', 'application/json')
self.end_headers()
response = {"server": "Python Server 1", "pod": "$(hostname)"}
self.wfile.write(json.dumps(response).encode())
with socketserver.TCPServer(("", 8000), Handler) as httpd:
httpd.serve_forever()
ports:
- containerPort: 8000
---
apiVersion: apps/v1
kind: Deployment
metadata:
name: python-server-2
spec:
replicas: 2
selector:
matchLabels:
app: python-server
server-id: "2"
template:
metadata:
labels:
app: python-server
server-id: "2"
spec:
containers:
- name: python-server
image: python:3.9-slim
command: ["python", "-c"]
args:
- |
import http.server, socketserver, json
class Handler(http.server.SimpleHTTPRequestHandler):
def do_GET(self):
self.send_response(200)
self.send_header('Content-type', 'application/json')
self.end_headers()
response = {"server": "Python Server 2", "pod": "$(hostname)"}
self.wfile.write(json.dumps(response).encode())
with socketserver.TCPServer(("", 8000), Handler) as httpd:
httpd.serve_forever()
ports:
- containerPort: 8000
---
apiVersion: apps/v1
kind: Deployment
metadata:
name: python-server-3
spec:
replicas: 2
selector:
matchLabels:
app: python-server
server-id: "3"
template:
metadata:
labels:
app: python-server
server-id: "3"
spec:
containers:
- name: python-server
image: python:3.9-slim
command: ["python", "-c"]
args:
- |
import http.server, socketserver, json
class Handler(http.server.SimpleHTTPRequestHandler):
def do_GET(self):
self.send_response(200)
self.send_header('Content-type', 'application/json')
self.end_headers()
response = {"server": "Python Server 3", "pod": "$(hostname)"}
self.wfile.write(json.dumps(response).encode())
with socketserver.TCPServer(("", 8000), Handler) as httpd:
httpd.serve_forever()
ports:
- containerPort: 8000
```
### Step 2: Create Load Balancing Service
Save as `python-lb-service.yaml`:
```yaml
apiVersion: v1
kind: Service
metadata:
name: python-lb
spec:
selector:
app: python-server
ports:
- port: 80
targetPort: 8000
type: ClusterIP
```
### Step 3: Deploy Everything
```bash
kubectl apply -f python-servers.yaml
kubectl apply -f python-lb-service.yaml
# Wait for pods to be ready
kubectl get pods -l app=python-server
```
### Step 4: Test Load Balancing
```bash
# Port forward the service
kubectl port-forward service/python-lb 8080:80
# In another terminal, test the load balancing
for i in {1..10}; do
curl http://localhost:8080
done
```
You'll see responses from different servers and pods, showing the load balancing in action!
### Cleanup
```bash
kubectl delete -f python-servers.yaml
kubectl delete -f python-lb-service.yaml
```
## Tutorial 3: Stateful Application with Persistent Storage
Deploy a simple application that persists data.
### Step 1: Create Persistent Volume Claim
Save as `storage.yaml`:
```yaml
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
name: data-pvc
spec:
accessModes:
- ReadWriteOnce
resources:
requests:
storage: 1Gi
```
### Step 2: Create Stateful Deployment
Save as `stateful-app.yaml`:
```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: data-app
spec:
replicas: 1
selector:
matchLabels:
app: data-app
template:
metadata:
labels:
app: data-app
spec:
containers:
- name: app
image: busybox:latest
command: ["sh", "-c"]
args:
- |
echo "Starting data application..."
while true; do
date >> /data/log.txt
echo "Written at $(date)" >> /data/log.txt
sleep 10
done
volumeMounts:
- name: data
mountPath: /data
volumes:
- name: data
persistentVolumeClaim:
claimName: data-pvc
```
### Step 3: Deploy and Verify
```bash
kubectl apply -f storage.yaml
kubectl apply -f stateful-app.yaml
# Wait for pod to be ready
kubectl get pods -l app=data-app
# Check the logs being written
kubectl exec -it $(kubectl get pod -l app=data-app -o name) -- cat /data/log.txt
```
### Step 4: Test Persistence
```bash
# Delete the pod
kubectl delete pod -l app=data-app
# Wait for new pod to start
kubectl get pods -l app=data-app
# Check data persisted
kubectl exec -it $(kubectl get pod -l app=data-app -o name) -- cat /data/log.txt
```
The data from before the pod deletion should still be there!
### Cleanup
```bash
kubectl delete -f stateful-app.yaml
kubectl delete -f storage.yaml
```
## Tutorial 4: Multi-Tier Application
Deploy a simple web app with a database backend.
### Step 1: Deploy Redis Database
Save as `redis.yaml`:
```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: redis
spec:
replicas: 1
selector:
matchLabels:
app: redis
template:
metadata:
labels:
app: redis
spec:
containers:
- name: redis
image: redis:7-alpine
ports:
- containerPort: 6379
---
apiVersion: v1
kind: Service
metadata:
name: redis
spec:
selector:
app: redis
ports:
- port: 6379
targetPort: 6379
type: ClusterIP
```
### Step 2: Deploy Frontend Application
Save as `frontend.yaml`:
```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: frontend
spec:
replicas: 3
selector:
matchLabels:
app: frontend
template:
metadata:
labels:
app: frontend
spec:
containers:
- name: frontend
image: nginx:alpine
ports:
- containerPort: 80
env:
- name: REDIS_HOST
value: "redis"
- name: REDIS_PORT
value: "6379"
---
apiVersion: v1
kind: Service
metadata:
name: frontend
spec:
selector:
app: frontend
ports:
- port: 80
targetPort: 80
type: ClusterIP
```
### Step 3: Deploy and Access
```bash
kubectl apply -f redis.yaml
kubectl apply -f frontend.yaml
# Wait for all pods
kubectl get pods
# Port forward to access frontend
kubectl port-forward service/frontend 8080:80
```
Open `http://localhost:8080` to access your multi-tier application.
### Cleanup
```bash
kubectl delete -f frontend.yaml
kubectl delete -f redis.yaml
```
## Best Practices
### Resource Limits
Always set resource limits:
```yaml
resources:
requests:
memory: "64Mi"
cpu: "250m"
limits:
memory: "128Mi"
cpu: "500m"
```
### Health Checks
Add liveness and readiness probes:
```yaml
livenessProbe:
httpGet:
path: /health
port: 8080
initialDelaySeconds: 30
periodSeconds: 10
readinessProbe:
httpGet:
path: /ready
port: 8080
initialDelaySeconds: 5
periodSeconds: 5
```
### Labels and Annotations
Use descriptive labels:
```yaml
metadata:
labels:
app: myapp
version: v1.0
environment: production
```
## Troubleshooting
### Pods Not Starting
```bash
# Check pod status
kubectl describe pod <pod-name>
# Check logs
kubectl logs <pod-name>
# Check events
kubectl get events --sort-by='.lastTimestamp'
```
### Service Not Accessible
```bash
# Check service
kubectl describe service <service-name>
# Check endpoints
kubectl get endpoints <service-name>
# Test from within cluster
kubectl run -it --rm debug --image=alpine --restart=Never -- sh
# Then: wget -O- http://service-name
```
### Resource Issues
```bash
# Check node resources
kubectl top nodes
# Check pod resources
kubectl top pods
# Check resource requests/limits
kubectl describe nodes
```
## Next Steps
Now that you've completed these tutorials:
- Deploy your own applications
- Explore [Helm](https://helm.sh/) for package management
- Learn about [Ingress controllers](https://kubernetes.io/docs/concepts/services-networking/ingress/) for advanced routing
- Study [StatefulSets](https://kubernetes.io/docs/concepts/workloads/controllers/statefulset/) for databases
- Explore [ConfigMaps and Secrets](https://kubernetes.io/docs/concepts/configuration/) for configuration management
---
:::tip Keep Learning
These tutorials cover the basics. The real power of Kubernetes comes from combining these concepts to build complex, scalable applications on the ThreeFold Grid!
:::

128
docs/hosters/advanced-nodes.md Normal file
View File

@@ -0,0 +1,128 @@
---
sidebar_position: 3
---
# Advanced Node Options
Beyond traditional hosting nodes, there are specialized **Edge Compute** and **Edge AI** configurations designed for enhanced earning potential and more demanding workloads.
## Edge Compute Node
**Based on GMKtec NUCBox M6 Ultra (Ryzen 5 7640HS)**
### Specifications
| Component | Specification |
|-----------|---------------|
| **CPU** | AMD Ryzen 5 7640HS (6 cores / 12 threads, up to ~5.0 GHz) |
| **RAM** | 32 GB |
| **Storage** | 1 TB NVMe SSD |
| **Power Usage** | ~30–40 W typical under load |
| **Network** | 2.5GbE LAN |
| **Form Factor** | Mini PC, silent and 24/7‑ready |
### Usage Options
#### Option 1: Use It Yourself (Private Edge)
- ✅ Full control of the hardware and software stack.
- ✅ Ideal for private AI, dev, or homelab workloads.
- ✅ No hosting fees – your own personal edge compute.
#### Option 2: Host for the Mycelium / ThreeFold Network
- ✅ Allocate "slices" of CPU, RAM, and storage as public capacity.
- ✅ Offer them on the marketplace and match customer demand.
- ✅ Earn SPORE with a guaranteed baseline via bid tiers.
- ✅ Example: standard compute tiers pay a minimum price (in SPORE) per slice.
#### Option 3: Hybrid
- ✅ Keep part of the machine for your private workloads.
- ✅ Rent out the remaining capacity to the network.
- ✅ Balance personal use and automated revenue.
---
## Edge AI Node
**Based on Ryzen AI MAX+ 395 platform**
### Specifications
| Component | Specification |
|-----------|---------------|
| **CPU** | AMD Ryzen™ AI MAX+ 395 (8C/16T, up to 5.1 GHz) |
| **AI Accelerator** | Integrated NPU (~50 TOPS) |
| **RAM** | 128 GB DDR5 |
| **Storage** | 2 TB NVMe SSD |
| **Power Usage** | ~45–55 W typical load |
| **Network** | Dual 2.5 G LAN |
| **Form Factor** | Compact, silent, designed for 24/7 AI workloads |
### AI‑Focused Features
- ✅ **Built‑in AI acceleration** – Dedicated NPU for local AI inference.
- ✅ **High memory headroom** – 128GB DDR5 for large models and context windows.
- ✅ **Edge AI ready** – Run models close to data sources for low latency.
- ✅ **Ideal for Mycelium Agents** and data‑sensitive AI workflows.
---
## How Rewards Flow
The earning logic for advanced nodes is the same as for any hosting node:
```mermaid
graph TD
A[Node Provides Capacity] --> B[User Rents Resources]
B --> C[80% to You<br/>SPORE Tokens]
B --> D[10% Burned<br/>Makes SPORE Scarcer]
B --> E[10% Mycelium<br/>Development]
C --> F[You Choose:<br/>Hold • Convert • Use]
D --> G[SPORE Supply Decreases<br/>Your Holdings More Scarce]
E --> H[Ecosystem Grows<br/>More Demand Over Time]
```
Advanced nodes simply position you for **higher‑value workloads** and **future AI‑centric demand**.
---
## Comparison: Edge vs Traditional Nodes
| Feature | Edge Compute | Edge AI | Traditional Mini Node |
|--------|--------------|--------|------------------------|
| **CPU Performance** | High (6‑core Zen 4) | Very High (8‑core AI) | Moderate |
| **RAM** | 32 GB | 128 GB DDR5 | 32 GB typical |
| **AI Capabilities** | Basic (CPU only) | Advanced NPU | None |
| **Power Usage** | ~30–40 W | ~45–55 W | ~60 W+ |
| **Best For** | General compute & cloud | AI/ML & agents | Entry‑level hosting |
---
## Getting Started with Edge Nodes
### Ready to Buy?
1. Research pricing and availability for **GMKtec NUCBox M6 Ultra** or **Ryzen AI MAX+ 395**.
2. Decide whether you want a **private**, **hosting**, or **hybrid** usage model.
3. Follow the **[Setup Guide](/hosters/setup)** to connect the node to your farm and the grid.
4. Read **[SPORE Economics](/hosters/economics)** to understand the reward model.
### Need Help Deciding?
- **Edge Compute** – Best for efficient general‑purpose compute with solid earning potential.
- **Edge AI** – Best for AI workloads, Mycelium Agents, and high‑end hosting.
- **Traditional nodes** – Best for starting small and learning the stack.
:::tip Pro Tip
Consider starting with a smaller, traditional hosting node to gain operational experience. Once you understand the economics and monitoring, upgrading to Edge Compute or Edge AI becomes a much easier decision.
:::
## Reference Links
- **GMKtec NUCBox M6 Ultra** – [gmktec.com/products/amd-ryzen-5-7640hs-mini-pc-nucbox-m6-ultra](https://www.gmktec.com/products/amd-ryzen-5-7640hs-mini-pc-nucbox-m6-ultra)
- **Ryzen AI MAX+ 395 EVO X2** – [gmktec.com/products/amd-ryzen%E2%84%A2-ai-max-395-evo-x2-ai-mini-pc](https://www.gmktec.com/products/amd-ryzen%E2%84%A2-ai-max-395-evo-x2-ai-mini-pc)
- **Learn SPORE Economics** – **[Farming/Hosting Economics](/hosters/economics)**
- **Community Discussion** – [t.me/threefoldfarmers](https://t.me/threefoldfarmers)

182
docs/hosters/buy-node.md Normal file
View File

@@ -0,0 +1,182 @@
---
sidebar_position: 2
---
# Buy or Build Your Hosting Node
You have two main paths to becoming a hoster on the Mycelium / ThreeFold Grid stack:
- **Buy a pre‑configured node** from an official vendor.
- **Build your own node** from compatible hardware.
Both can earn SPORE; the right choice depends on your budget, time, and hardware skills.
## Option 1: Buy a Pre‑Built Node (Easiest)
### Why Buy Pre‑Built?
✅ **Plug‑and‑play** – Arrives ready to host.
✅ **Vendor support** – Get help when you need it.
✅ **Optimized hardware** – Tested configurations for 24/7 uptime.
✅ **Warranty** – Hardware support and replacements.
✅ **Quick start** – Hosting within hours after delivery.
### Where to Buy
:::info Official Node Vendor
Purchase certified nodes from **YourData Network**:
[yourdata.network/product-category/nodes](https://yourdata.network/product-category/nodes/)
These nodes are pre‑configured, tested, and ready to join the grid.
Need recommendations or sizing advice? Join the community:
**Telegram (Hosters/Farmers)** – [t.me/threefoldfarmers](https://t.me/threefoldfarmers)
:::
### What to Look For
When selecting a pre‑built node, consider:
- **Capacity** – CPU cores, RAM, and SSD size.
- **Power Efficiency** – Lower watts = better long‑term returns.
- **Warranty & Support** – Vendor guarantees and replacement policies.
- **Shipping & Duties** – Full landed cost, not just hardware price.
### Typical Node Profiles
**Entry Level**
- 4–8 CPU cores.
- 16GB RAM.
- 500GB–1TB SSD.
- Very low power (~50W) – ideal for home hosting.
**Mid Range**
- 8–16 CPU cores.
- 32–64GB RAM.
- 1–2TB SSD.
- Balanced performance (~100W).
**High Performance**
- 16+ CPU cores.
- 64–128GB+ RAM.
- 2TB+ SSD (often multiple drives).
- Designed for maximum capacity (~150–200W).
### Specialized Edge & AI Nodes
Beyond traditional hoster nodes, there are **Edge Compute** and **Edge AI** configurations designed for higher‑value workloads:
- **Edge Compute Node** – GMKtec NUCBox M6 Ultra (Ryzen 5 7640HS, 32GB RAM).
- **Edge AI Node** – Ryzen AI MAX+ 395 platform (128GB RAM, integrated NPU).
Why consider these?
- Higher earning potential for compute‑heavy and AI workloads.
- Optimized for hybrid usage (your private workloads + rented capacity).
- Future‑proof for Mycelium Agent workloads and advanced cloud use cases.
For details, see **[Advanced Node Options](/hosters/advanced-nodes)**.
## Option 2: Build Your Own Node (DIY)
### Why Build Your Own?
✅ **Lower upfront cost** – Reuse or repurpose existing hardware.
✅ **Flexibility** – Choose exactly which components you run.
✅ **Learning experience** – Understand the stack in depth.
✅ **Upgrade path** – Incremental improvements over time.
### Hardware Requirements (Guidance)
| Component | Minimum | Recommended |
|----------|---------|------------|
| **CPU** | 4 cores | 8+ modern cores (Ryzen / recent Intel) |
| **RAM** | 8GB | 16–64GB depending on workloads |
| **Storage** | 500GB SSD | 1TB+ NVMe SSD (+ optional HDDs) |
| **Network** | 1 Gbps Ethernet | 1 Gbps+ wired, stable uptime |
### Compatible Hardware
**Processors**
- Intel Core i5/i7/i9 (6th gen or newer).
- AMD Ryzen 5/7/9.
- Intel Xeon / AMD EPYC for larger deployments.
**Storage**
- SATA or NVMe SSDs for primary capacity.
- HDDs for additional bulk storage.
- Hardware RAID or ZFS possible on some setups.
**Network**
- Standard Ethernet NICs.
- Wired connection strongly recommended for reliability.
### Where to Source Hardware
- **Repurpose** – Old servers or workstations already on hand.
- **Consumer Parts** – Build from off‑the‑shelf PC components.
- **Used Enterprise** – Refurbished servers from online marketplaces.
- **Local Dealers** – Regional hardware vendors or system integrators.
:::tip Pro Tip
Start with one efficient node to learn the system before scaling. A modern low‑power configuration often has better net returns than an old, power‑hungry server because of electricity costs.
:::
## Cost Considerations
### Initial Investment
| Item | Pre‑Built | DIY |
|------|----------|-----|
| Hardware | ~$500–3000+ | ~$200–2000+ |
| Setup Time | 30–60 minutes | 2–6 hours |
| Technical Skill | Low | Medium–High |
| Support | Vendor | Community / self‑managed |
### Operating Costs
Ongoing costs mainly come from:
- ⚡ **Electricity** – Varies by hardware profile and local rates.
- 🌐 **Internet** – Often your existing line; business‑grade recommended for larger farms.
- 🔧 **Maintenance** – Occasional drive or PSU replacements.
Approximate monthly electricity (very rough examples):
- Efficient mini PC (~20W): **$1–3/month**.
- Standard desktop (~75W): **$5–15/month**.
- High‑performance node (~150W): **$10–30/month**.
## Making Your Decision
### Choose Pre‑Built If
- You want the **simplest** path to becoming a hoster.
- You value **hardware support** and warranties.
- You prefer a **plug‑and‑play** experience.
- Your time is more valuable than incremental cost savings.
### Choose DIY If
- You already have compatible hardware.
- You **enjoy technical projects** and tuning systems.
- You want to **optimize costs** aggressively.
- You're comfortable with BIOS, storage, and networking basics.
## What's Next?
Once you have a node (or a clear hardware plan), move on to:
**[Set Up Your Node](/hosters/setup)** – Install Zero‑OS, attach it to your farm, and start hosting capacity on the grid.
---
:::tip Need Help Deciding?
Ask the community in **ThreeFold Farmers / Hosters** chat: [t.me/threefoldfarmers](https://t.me/threefoldfarmers). Experienced operators can help you validate hardware ideas and ROI assumptions.
:::

181
docs/hosters/economics.md Normal file
View File

@@ -0,0 +1,181 @@
---
sidebar_position: 5
---
# Hosting Economics (SPORE)
This page explains how hosters earn money by contributing capacity to the grid and how **SPORE**, the ecosystem token, works.
> Originally this content was written for *ThreeFold Farming*. Here we describe it from the perspective of **hosters** supporting the Mycelium / ThreeFold stack.
## What is SPORE?
**SPORE** is the native token of the ThreeFold ecosystem. You earn SPORE for providing compute, storage, and network resources as a hoster.
### Key Facts
| Feature | Details |
|---------|---------|
| **Base Price (intro period)** | $0.01 per SPORE (fixed until June 30, 2026) |
| **After June 2026** | Price floats based on market demand |
| **What You Earn** | SPORE tokens for capacity and utilization |
| **Max Supply** | 10 billion SPORE (capped) |
| **Utility** | Payment to hosters, growth of the ecosystem |
### Why SPORE Can Appreciate
1. **Part of every payment is burned** – reducing circulating supply.
2. **Demand grows with adoption** – more workloads → more SPORE demand.
3. **Scarcity + demand** – over time this can support higher prices.
---
## How Revenue Is Split
When users pay for resources on your node, the payment is automatically split:
```mermaid
graph LR
A[User Pays for Resources] --> B[80% to Hoster<br/>SPORE Tokens]
A --> C[10% Burned<br/>Removed from circulation]
A --> D[10% Mycelium / ThreeFold<br/>Development]
B --> E[Your SPORE Balance Increases]
C --> F[Total SPORE Supply Decreases]
D --> G[Ecosystem & tooling improve]
```
### Example
If a user spends **$10** worth of SPORE on workloads:
| Recipient | Amount | What Happens |
|-----------|--------|--------------|
| **You (Hoster)** | $8 (800 SPORE) | Added to your balance |
| **Burned** | $1 (100 SPORE) | Destroyed permanently |
| **Development** | $1 (100 SPORE) | Funds infrastructure & software |
Over time, the burn + demand effects help make each remaining SPORE more scarce.
---
## Burning and Scarcity
Burning is simply **removing tokens from circulation forever**.
Conceptually:
- Without burning: supply stays flat, price tracks demand only.
- With burning: supply decreases as usage increases → additional upward pressure on price.
This is why long‑term hosters are incentivized to accumulate SPORE while continuing to provide capacity.
---
## Earnings Drivers
Your actual returns as a hoster depend on:
- **Capacity** – How much CPU, RAM, and storage your nodes provide.
- **Location & reliability** – Good connectivity and uptime attract more workloads.
- **Demand** – How many users deploy on the grid / Mycelium Cloud.
- **Time horizon** – SPORE price is fixed during the early phase, then becomes market‑driven.
### Rough Components of ROI
1. **Base rewards** – Capacity made available to the network.
2. **Utilization‑based income** – When workloads actually run on your nodes.
3. **Token appreciation (speculative)** – If SPORE price rises as adoption grows.
> Exact reward formulas can evolve over time. Always check the latest tokenomics and dashboards for up‑to‑date numbers.
---
## Managing Your SPORE
### 1. Hold (Long‑Term Thesis)
- Let SPORE accumulate in your wallet.
- Benefit from potential scarcity and ecosystem growth.
- Simple, low‑effort strategy.
### 2. Convert Some to Stability
- Convert a portion of SPORE to **Cloud Credits (CC)** or other units if/when available.
- Use CC for predictable budgeting, while keeping some SPORE for upside.
- Useful if hosting is part of a bigger business.
### 3. Hybrid Approach
Many hosters will:
- Keep a core SPORE position (long term).
- Periodically convert a portion to cover opex (power, connectivity, hardware refresh).
---
## Getting Started with Earnings
### Step 1: Set Up Your Node
Make sure your node is live and part of your farm:
- Follow **[Set Up Your Node](/hosters/setup)** to get connected.
- Confirm visibility in the dashboard.
### Step 2: Monitor Utilization
- Use the dashboard to see when and how your capacity is used.
- Watch resource allocation, uptime, and earned SPORE over time.
### Step 3: Iterate on Hardware & Pricing
- Improve power efficiency to increase net returns.
- Consider upgrading to **Edge Compute** or **Edge AI** nodes for higher‑value workloads.
- Stay informed about any bidding / pricing mechanisms offered by the platform.
---
## Common Questions
<details>
<summary><strong>When will I start earning SPORE?</strong></summary>
As soon as your node is online and offering capacity, you become eligible. Initial earnings typically appear within **24–48 hours** as the system starts assigning workloads.
</details>
<details>
<summary><strong>Can I lose money hosting?</strong></summary>
Hosting involves hardware and power costs. Profitability depends on utilization and SPORE value. However, baseline rewards and long‑term grid usage are designed to make serious, reliable hosters viable over time.
</details>
<details>
<summary><strong>What if SPORE price changes after 2026?</strong></summary>
After June 2026 the price becomes market‑driven. The burn mechanism and adoption are designed to support value, but token prices can still be volatile. Plan with a long‑term perspective and avoid over‑leveraging.
</details>
<details>
<summary><strong>How often do I get paid?</strong></summary>
SPORE accrues continuously and can be checked any time in your dashboards and wallets. There’s no manual payout process.
</details>
---
## Additional Resources
- **Community Forum** – [forum.threefold.io](https://forum.threefold.io)
- **Farming / Hosting Manual** – [manual.grid.tf/farmers/intro](https://manual.grid.tf/farmers/intro)
- **Community Chat** – [t.me/threefold/1](https://t.me/threefold/1)
---
:::tip Ready to Start Earning?
If you haven’t already, finish the **[Setup Guide](/hosters/setup)** and make sure your node is online. From there, SPORE rewards start accumulating automatically as the network uses your capacity.
:::

111
docs/hosters/overview.md Normal file
View File

@@ -0,0 +1,111 @@
---
sidebar_position: 1
slug: /hosters
---
# Hosters on the Mycelium Cloud
Hosters provide storage, compute, and network capacity to the Mycelium Cloud. In return, they earn **SPORE tokens** for making reliable, sovereign infrastructure available.
> Historically this role was called *ThreeFold Farming* and operators were called *farmers*. In the Mycelium context we refer to them as **hosters**.
## How It Works
As a **hoster**, you:
1. **Deploy a Node (3Node)** – Connect suitable server hardware to the ThreeFold Grid.
2. **Run Zero-OS** – A self-healing operating system that manages the node for you.
3. **Provide Capacity** – Your node offers storage, compute, and network resources.
4. **Earn Rewards** – You earn SPORE when capacity is reserved and used.
## Why Become a Hoster?
Hosters earn **SPORE tokens** for providing resources that power Mycelium Cloud clusters, virtual data centers, and edge workloads.
### 🌱 Simple & Autonomous
- Deploy once and let it run.
- Minimal ongoing maintenance.
- Self-healing Zero-OS handles low-level operations.
- No deep sysadmin background required.
### How Revenue Works
When users rent your node's resources, the payment is split automatically:
```mermaid
graph LR
A[User Pays] --> B[80% to Hoster<br/>SPORE Tokens]
A --> C[10% Burned<br/>Increases SPORE Scarcity]
A --> D[10% Mycelium<br/>Development]
```
You get a direct share of every workload that runs on your capacity, while the burn and development portions strengthen the ecosystem over time.
### 🌍 Make an Impact
- Support decentralized internet infrastructure.
- Provide an alternative to centralized hyperscalers.
- Enable digital sovereignty and data privacy.
- Help build the peer‑to‑peer internet that Mycelium enables.
## What You Need
### Hardware Requirements
**Minimum specs (rough guidance):**
- Modern server or workstation.
- Multi‑core processor (4+ cores recommended).
- 8GB+ RAM (16GB+ recommended).
- 500GB+ SSD storage.
- Reliable network connection.
**Or buy a pre‑built node:**
- Certified 3Nodes are available from vendors.
- Plug‑and‑play for an easier start.
- Optimized for 24/7 operation and good power efficiency.
### Other Requirements
- ⚡ Reliable power supply.
- 🌐 Stable wired internet connection.
- 📍 Physical space for the hardware.
- 🔧 Basic technical comfort (especially if building your own).
## Getting Started
Ready to become a hoster? Follow this path:
1. **[Buy or Build a Node](/hosters/buy-node)** – Choose your hardware option.
2. **[Set Up Your Node](/hosters/setup)** – Connect your 3Node to the grid and start hosting.
3. **Monitor & Earn** – Track utilization and rewards via the dashboard.
:::tip First Time Hosting?
If you're new to the ecosystem, starting with a pre‑built node from a trusted vendor is usually the smoothest path. You can always expand later with DIY hardware once you're comfortable.
:::
## The Hoster Journey
Hosters form a global community that backs the grid and the Mycelium Stack:
- Individuals running nodes at home or in small offices.
- Small businesses offering regional capacity.
- Data‑center operators scaling out full racks.
- Community initiatives building local digital infrastructure.
Every hoster helps expand a more open, sovereign internet.
## Resources
- **Dashboard** – [dashboard.grid.tf](https://dashboard.grid.tf) – Manage your node(s) and capacity.
- **Technical Manual** – [manual.grid.tf/farmers/intro](https://manual.grid.tf/farmers/intro) – In‑depth setup/farming docs (original terminology).
- **Community Chat** – [t.me/threefold/1](https://t.me/threefold/1) – Ask questions and share experiences.
- **Forum** – [forum.threefold.io](https://forum.threefold.io) – Long‑form discussions and updates.
---
:::tip Next Step
Once you're comfortable with the basics, explore **[Buy or Build a Node](/hosters/buy-node)** to pick the right hardware profile for your hosting strategy.
:::

151
docs/hosters/setup.md Normal file
View File

@@ -0,0 +1,151 @@
---
sidebar_position: 4
---
# Set Up Your Hosting Node
This guide summarizes how to set up a **ThreeFold / Mycelium hosting node (3Node)** and connect it to your farm so it can start earning SPORE.
The process differs slightly depending on whether you **bought a pre‑built node** or **built your own (DIY)**.
## Setup Overview
### Pre‑Built Node (Easiest)
**Time to hosting: ~30 minutes** after the node arrives.
1. **Create Account** – Use the ThreeFold Connect app.
2. **Create a Farm** – In the app, go to *Farming* → *Create farm* and note your **Farm ID**.
3. **Order Node** – Purchase from an official vendor and provide your Farm ID.
4. **Receive & Power On** – Connect power and network, then switch it on.
5. **Verify** – The node should appear online in your dashboard / app.
> You must have your **Farm ID before ordering** a pre‑built node so the vendor can pre‑configure it.
### DIY Node (More Steps)
**Time to hosting: ~2–6 hours**, depending on your experience.
1. **Create Account** – Install ThreeFold Connect and create your account.
2. **Create Farm** – In the app, create a farm and save your **Farm ID**.
3. **Download Zero‑OS** – Get a bootstrap image with your Farm ID from [v4.bootstrap.grid.tf](https://v4.bootstrap.grid.tf).
4. **Burn to USB** – Write the image to a USB drive (e.g. with BalenaEtcher).
5. **Configure BIOS** – Enable virtualization, set USB boot, configure power‑on behavior.
6. **Boot Node** – Insert USB, power on, and wait for Zero‑OS to start.
7. **Verify** – Confirm the node appears in the dashboard / app.
DIY requires more low‑level work (BIOS configuration, boot media, etc.), but gives you full control over hardware.
## Step 1: Install ThreeFold Connect
ThreeFold Connect is used for account creation, wallet, and farm management.
:::info Get the App
- **iOS** – [itunes.apple.com/.../3bot-login](https://itunes.apple.com/be/app/3bot-login/id1459845885?l=nl&mt=8)
- **Android** – [play.google.com/.../threebotlogin](https://play.google.com/store/apps/details?id=org.jimber.threebotlogin)
:::
## Step 2: Create Account & Farm
1. Open ThreeFold Connect.
2. Create a new account and **securely save your seed phrase** (offline).
3. Verify your email address.
4. Go to the **Farming** section.
5. Tap **+** to create a new farm.
6. Choose a farm name and select which wallet will receive rewards.
7. Confirm and **note your Farm ID**.
:::warning Security
Your **seed phrase** is the *only* way to recover your account. Write it down and store it safely offline. Never share it with anyone, and never enter it into untrusted apps or websites.
:::
## Step 3: Prepare Your Node
### If You Bought a Pre‑Built Node
- The vendor will typically preload Zero‑OS and configure your Farm ID.
- On arrival, simply connect **power** and **Ethernet**, and power it on.
- Wait a few minutes for the node to boot and register.
### If You Built a DIY Node
1. **Download Zero‑OS image** for your Farm ID from [v4.bootstrap.grid.tf](https://v4.bootstrap.grid.tf).
2. **Flash the image** to a USB drive (e.g. BalenaEtcher or `dd`).
3. **Enter BIOS/UEFI** on your machine and:
- Enable CPU virtualization features.
- Set USB drive as first boot device.
- Configure power‑on after power loss (recommended).
4. **Boot from USB** and wait for Zero‑OS to provision and join the grid.
## Step 4: Verify Node Status
After boot, the node should appear in your farm overview.
Check via:
- **ThreeFold Connect app** – See your farm and node status.
- **Dashboard** – [dashboard.grid.tf](https://dashboard.grid.tf) shows node details, uptime, and capacity.
If the node does not show up:
- Wait 10–15 minutes for initial registration.
- Double‑check the network cable and router.
- Confirm the correct Farm ID is used.
- Reboot the node and verify BIOS boot order.
## Monitoring & Growth
Once your node is online, you’re effectively a hoster – your capacity can be used by workloads launched via Mycelium Cloud and other tooling.
### Monitor Your Farm
- **ThreeFold Connect** – Quick view of node status and balances.
- **Dashboard** – Detailed node metrics, capacity, and utilization.
- **Community** – Use the Telegram farmers/hosters group for peer support.
### Expand Over Time
- Start with a single node until you’re comfortable.
- Add more nodes to the same farm to increase capacity and earning potential.
- Experiment with **Edge Compute** or **Edge AI** nodes for higher‑value workloads.
## Troubleshooting Quick Answers
**Node not appearing?**
- Wait a bit longer, check network connectivity, and confirm Farm ID.
- Ensure the router/firewall is not blocking outbound connections.
**DIY node won’t boot Zero‑OS?**
- Re‑flash the USB image.
- Check BIOS for correct boot order and virtualization settings.
- Try another USB drive or port.
## Deep‑Dive Guides
For full, step‑by‑step instructions (with screenshots and corner cases), use the official farming manuals (the terminology there still says *farmer*):
:::info Comprehensive Setup Guides
**Pre‑Built Node Setup**
[manual.grid.tf/farmers/category/buy-a-3node](https://manual.grid.tf/farmers/category/buy-a-3node)
**DIY Node Build Guide**
[manual.grid.tf/farmers/category/build-a-3node](https://manual.grid.tf/farmers/category/build-a-3node)
These include BIOS details, advanced troubleshooting, and more.
:::
## What’s Next?
🎉 **Your hosting node is now part of the grid.**
From here you can:
- Learn about rewards and SPORE in **[Hosting Economics](/hosters/economics)**.
- Consider adding capacity or upgrading hardware.
- Join the community for tips, monitoring strategies, and best practices.
:::tip Need Help?
The **Farmers / Hosters Community** at [t.me/threefoldfarmers](https://t.me/threefoldfarmers) has experienced operators who can help you debug setup issues and optimize your configuration.
:::

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

65
docs/overview-index.md Normal file
View File

@@ -0,0 +1,65 @@
---
slug: /
displayed_sidebar: null
wrapperClassName: overview-doc
---
# Project Mycelium Documentation
Welcome to the official documentation for **Project Mycelium**.
This site is organized around the core building blocks of the Mycelium stack:
- **Network** – The Mycelium IPv6 overlay network for secure, encrypted connectivity.
- **Cloud** – Mycelium Cloud for Kubernetes clusters on decentralized infrastructure.
- **VDC** – Virtual Data Centers for full cloud environments you control.
- **AI Agent Framework** – Mycelium Agents (coming 2026) for sovereign, distributed AI.
- **Hosters** – Individuals and organizations who contribute capacity to the grid.
Use the top navigation to jump directly to any of these areas.
## Who This Documentation Is For
- **Developers** who want to build on the Mycelium Network and Mycelium Cloud.
- **Organizations** who need sovereign cloud, data residency, and compliance.
- **Hosters** (ThreeFold "farmers") who want to run nodes and earn rewards.
## High-Level Architecture
At a high level, Project Mycelium combines:
1. **Mycelium Network**
A cryptographic IPv6 overlay that connects devices, nodes, and clusters in a secure peer-to-peer mesh.
2. **Mycelium Cloud**
A platform to deploy Kubernetes clusters on the decentralized ThreeFold Grid, using Mycelium Network for connectivity.
3. **Virtual Data Centers (VDCs)**
Composable environments built on top of Mycelium Cloud for applications, databases, internal services, and full personal/organizational clouds.
4. **AI Agent Framework**
A forthcoming framework that lets you run private, distributed AI agents inside environments you control.
5. **Hosters**
Node operators who provide compute, storage, and network capacity to the ecosystem and earn rewards for doing so.
Each section of this documentation dives into one of these layers.
## Where to Start
- If you want **secure networking between devices and clusters**:
- Start with **[Network](/network)**.
- If you want to **deploy Kubernetes clusters on decentralized infrastructure**:
- Start with **[Cloud](/cloud)**.
- If you are a **hoster / farmer** interested in running nodes and earning SPORE:
- Start with **[Hosters](/hosters)**.
- If you want to understand how **Virtual Data Centers** and the **AI Agent Framework** fit in:
- Read the overviews for **[VDC](/vdc)** and **[AI Agent Framework](/ai-agent-framework)**.
## Related Resources
- **Main website** – [www.projectmycelium.com](https://www.projectmycelium.com)
- **Mycelium Cloud** – [myceliumcloud.tf](https://myceliumcloud.tf)

75
docs/vdc/blueprints.md Normal file
View File

@@ -0,0 +1,75 @@
---
sidebar_position: 3
---
# VDC Blueprints & Example Environments
This section presents opinionated "blueprints" you can use as starting points for your own Virtual Data Centers.
## Digital Me – Personal Sovereign Cloud Workspace
Adapted from the **Cloud Blueprint** on the main Mycelium site, *Digital Me* is a personal cloud environment showcasing what’s possible on top of the Mycelium Stack.
### Goal
Provide a private, extensible workspace where:
- Your documents, files, and communication tools live on infrastructure you choose.
- You can integrate additional services or agents over time.
- Everything is reachable securely via Mycelium Network.
### Core Components
A typical Digital Me blueprint might include:
- **Cryptpad** – End‑to‑end encrypted document collaboration.
- **Gitea** – Git hosting, code review, and lightweight DevOps.
- **Nextcloud** – File storage, sync, and basic productivity apps.
- **Matrix (Elements)** – Real‑time chat and rooms.
- **Stallwart** – Mail, calendar, and contacts.
- **Video Conferencing** – LiveKit or Jitsi, optionally integrated with Matrix or Nextcloud.
- **SSO / Identity** – A unifying login layer (future iteration).
Each service runs as one or more Kubernetes workloads inside your VDC.
### How It Fits Together
```mermaid
graph TD
A[Mycelium Network] --> B[VDC (K3s Cluster)]
B --> C[Apps: Cryptpad, Gitea, Nextcloud, Matrix, Stallwart, Video]
C --> D[Your Devices]
D -. secure overlay .- A
```
- Your devices connect via Mycelium Network.
- Services are exposed only via overlay addresses or controlled gateways.
- Data can be stored on QSFS or other resilient storage options.
### Customizing the Blueprint
You can adapt Digital Me by:
- Swapping apps (e.g. another Git forge instead of Gitea).
- Adding specialized tools (design collaboration, analytics, etc.).
- Scaling vertically (larger nodes) or horizontally (more nodes) as usage grows.
- Integrating Mycelium Agents in the future to automate workflows.
## Other Blueprint Ideas
The same VDC primitives can be used for many patterns:
- **Team Collaboration Hub** – Shared docs, code, chat, CI/CD for a startup or studio.
- **Research Environment** – Compute + storage for data science, notebooks, and pipelines.
- **Edge Application Stack** – Regional VDCs running local services that sync to a core.
Blueprints are not prescriptive; they’re **starting points** that help you think in terms of composable services.
---
## Next Steps
- Learn more about **VDC capabilities** in the **[VDC Overview](/vdc)**.
- Explore concrete **[VDC Use Cases](/vdc/use-cases)**.
- When you’re ready to deploy, follow the **[Mycelium Cloud Getting Started guide](/cloud/getting-started)** to spin up your first cluster.

74
docs/vdc/overview.md Normal file
View File

@@ -0,0 +1,74 @@
---
sidebar_position: 1
slug: /vdc
---
# Virtual Data Centers (VDC)
Mycelium Virtual Data Centers (VDC) let you provision full cloud environments — compute, storage, and networking — without owning or operating physical servers.
They are built on top of **Mycelium Cloud** and the **ThreeFold Grid**, combining decentralized infrastructure with managed Kubernetes and Mycelium networking.
## What Is a VDC?
A VDC is your **dedicated environment** on the grid:
- Isolated clusters for applications, databases, and internal services.
- Customizable CPU, RAM, and storage profiles.
- Encrypted overlay networking using **Mycelium Network**.
- Integration with quantum‑safe storage (QSFS) and other Mycelium components.
Think of it as your own mini cloud region that you control, without having to run a datacenter.
## Key Capabilities
Adapted from the "Virtual Data Centers" focus in the Mycelium Cloud UI:
- **Dedicated environments** – Keep workloads, teams, and projects cleanly separated.
- **Elastic capacity** – Add or remove compute and storage on demand.
- **Migration paths** – Move workloads from public cloud or on‑prem into a VDC.
- **Compliance‑aware placement** – Choose where data and workloads reside.
- **Continuous monitoring & recovery** – Benefit from built‑in redundancy.
## How VDC Relates to Mycelium Cloud
Under the hood, a VDC is powered by **K3s Kubernetes clusters** running on the ThreeFold Grid via Mycelium Cloud:
```mermaid
graph TD
A[You] --> B[Mycelium Cloud Dashboard]
B --> C[Provision VDC / Cluster]
C --> D[ThreeFold Grid Nodes]
D --> E[Applications & Services]
A -. Mycelium Network .-> E
```
- You interact through the **Mycelium Cloud dashboard and APIs**.
- Clusters are deployed onto distributed grid nodes.
- Access happens over **Mycelium Network** using secure IPv6 overlay addresses.
## Common VDC Use Cases
- **Enterprise Kubernetes** – Multi‑service apps, APIs, back‑office systems.
- **Internal Platforms** – Developer platforms, CI/CD runners, internal tools.
- **AI / Data Workloads** – Training, inference, and data processing pipelines.
- **Hybrid & Edge** – Extend existing infrastructure into grid‑backed environments.
See **[VDC Use Cases](/vdc/use-cases)** for more detailed scenarios.
## Compared to Traditional Cloud
| Aspect | Mycelium VDC | Traditional Cloud |
|--------|--------------|-------------------|
| **Infrastructure** | Decentralized grid | Centralized datacenters |
| **Networking** | Encrypted P2P via Mycelium | Public IPs, centralized routing |
| **Sovereignty** | You choose jurisdictions & nodes | Provider‑controlled |
| **Lock‑in** | Standard Kubernetes & open tooling | Often proprietary services |
| **Cost Profile** | Competitive, usage‑based | Often complex and higher over time |
## Where to Go Next
- **New to VDC?** Start with **[VDC Use Cases](/vdc/use-cases)** to see concrete patterns.
- **Want a concrete blueprint?** Explore **[Blueprints & Example Environments](/vdc/blueprints)** such as *Digital Me*, a personal sovereign cloud workspace.
- **Need cluster details?** See **[Mycelium Cloud Overview](/cloud)** and **[Getting Started](/cloud/getting-started)**.

91
docs/vdc/use-cases.md Normal file
View File

@@ -0,0 +1,91 @@
---
sidebar_position: 2
---
# VDC Use Cases
Virtual Data Centers give you flexible building blocks for many types of workloads. This page highlights some of the most relevant patterns.
## 1. Enterprise Kubernetes
Run production workloads with full control and no hyperscaler lock‑in:
- Multi‑service applications and APIs.
- Internal tools, back‑office systems, and shared services.
- Microservice architectures using standard Kubernetes, Helm, and operators.
- Policy‑driven placement to keep data in specific regions or jurisdictions.
**Why use a VDC here?**
- Control over where clusters run and how they’re connected.
- Encrypted overlay networking via Mycelium instead of exposed public IPs.
- Compatibility with existing Kubernetes tooling and CI/CD chains.
## 2. AI & Machine Learning
Run training and inference close to your data while keeping it private.
- GPU‑accelerated training on dedicated clusters.
- Model serving endpoints behind Mycelium Network.
- Pipelines that combine **QSFS** (quantum‑safe storage) with compute.
- Future‑ready environments for **Mycelium Agents**.
**Key benefits**
- Data stays on hardware you or your partners select.
- Secure east‑west traffic via Mycelium overlays.
- Ability to burst across multiple nodes or sites.
## 3. Edge & IoT
Leverage the grid’s geographic spread to deploy workloads closer to users, sensors, and devices.
- Run latency‑sensitive services near where events occur.
- Ingest, process, and filter data at the edge before sending summaries upstream.
- Coordinate fleets of devices and gateways over Mycelium Network.
**Examples**
- Local analytics near industrial sites.
- Regional micro‑datacenters serving communities or campuses.
- Smart‑city workloads combining many distributed nodes.
## 4. Personal & Team Clouds
VDCs can back **personal sovereign environments** where your apps and data live entirely on infrastructure you choose.
- Self‑hosted collaboration suites (documents, chat, mail, files).
- Private developer environments and CI runners.
- Long‑term personal archives on QSFS.
The **Digital Me** blueprint (see below) is one concrete example of this pattern.
## 5. Hybrid & Migration Scenarios
Move workloads from traditional cloud or on‑prem into a VDC, or straddle both worlds.
- Gradual migration from centralized providers.
- Burst or spill‑over capacity into the grid.
- Disaster‑recovery clusters that can be spun up on demand.
## Example: Digital Me on Mycelium
The *Digital Me* concept shows what a personal sovereign cloud workspace can look like:
- **Cryptpad** – Encrypted document collaboration.
- **Elements (Matrix)** – Secure chat and communication.
- **Stallwart** – Mail, calendar, and contacts.
- **Gitea** – Git hosting and code collaboration.
- **Nextcloud** – File storage and sync.
- **LiveKit / Jitsi** – Video conferencing integrated with chat / files.
- **SSO** (future) – Single Sign‑On across the stack.
All of this can be orchestrated inside a VDC and surfaced via Mycelium networking.
---
## Related Documentation
- **[VDC Overview](/vdc)** – Concepts and architecture.
- **[Blueprints & Example Environments](/vdc/blueprints)** – How to assemble real‑world stacks.
- **[Mycelium Cloud for Developers](/cloud/for-developers)** – Deeper dive into the underlying platform.