🏛️ Decentralized.Host

Sovereign self-hosted infrastructure where hosts stay in control. No SaaS dependencies. No telemetry. No vendor lock-in.

---

What is Decentralized.Host?

Decentralized.Host is a complete infrastructure system where:

• ✅ Hosts stay sovereign — Each host has local policy. No centralized admission control.
• ✅ Work is signed intent — Every assignment is cryptographically signed (Ed25519). No silent mutations.
• ✅ State stays honest — Desired ≠ Admitted ≠ Executing ≠ Observed ≠ Verified. Unknown stays unknown.
• ✅ Storage is content-addressed — BLAKE3 hashes, Merkle anti-entropy, automatic repair from peers.
• ✅ Control plane is HA — Raft consensus, mutual TLS, signed backups, zero workload interruption on leader loss.
• ✅ Mesh is peer-to-peer — Userspace WireGuard, gossip topology discovery, no central gateway.
• ✅ Zero external dependencies — Operator console runs on the control plane itself. No cloud APIs. No callbacks.

How It Works

Connect your cloud. Own it over time. Start by importing GitHub, Vercel, Supabase, Docker, Kubernetes—observe them in one graph, then migrate workloads to owned infrastructure as you choose.

Current Scope: Provider discovery, observation, and local policy enforcement. Production multi-machine qualification and settlement features coming in v0.2+.

Community: We welcome contributions, sponsorships, and collaboration! See CONTRIBUTING.md to get started.

---

What This Is

Decentralized.Host is a provider-agnostic control plane that imports your existing cloud (GitHub, Vercel, Supabase, Docker, Kubernetes, Ollama) into a unified resource graph, then progressively enables migration to owned infrastructure.

v0.1 (Current): Provider Connection & Observation

• dh connect: Discover and authenticate to GitHub, GitLab, Vercel, Railway, Supabase, Cloudflare, Docker, Kubernetes, AWS, GCP, Azure, and local Ollama/vLLM instances
• dh graph: Visualize all resources (repos, deployments, databases, containers, models) in one project graph with dependency, privacy, and cost analysis
• dh doctor: Scored analysis of sovereignty, portability, privacy risks, and cost per resource
• dh migrate <resource>: Move workloads to owned infrastructure with before/after cryptographic proof
• dh prove: Evidence-gated promotion gates (signatures, policy checks, state verification)

v0.2+: Progressive Ownership

• Local control plane bootstrap with Ed25519 signed intent
• Per-host policy enforcement for imported workloads
• Multi-node mesh with WireGuard and mTLS
• Privacy-boundary scheduling (data locality constraints)
• Raft consensus + immutable audit trail

See 100 Capabilities: 50 Problems + 50 Innovations for the long-term vision. v0.1 focuses on the viral loop (connect → graph → doctor → migrate → prove); v0.2+ adds the foundations.

---

v0.1 Architecture

Provider Adapter Pattern

Each provider (GitHub, Vercel, Supabase, Docker, K8s, etc.) has a standardized adapter implementing:

• Discover(): Find resources in the provider (repos, deployments, databases, containers)
• Import(): Bring resources into the unified graph with full metadata
• Observe(): Poll state continuously and detect changes
• Plan(): Calculate migration steps (what to move, where, in what order)
• Diff(): Compare source vs destination before/after proof
• Capabilities(): Report what the provider supports (encryption, policy, scheduling)

Universal Resource Graph

Single data model for all resources regardless of provider:

┌─────────────────────────────────────────────────────────────────────┐
│                    OPERATOR (dh CLI / Console)                      │
└──────────────────────────┬──────────────────────────────────────────┘
                           │ signed work proposals
                           ▼
         ┌─────────────────────────────────────┐
         │   CONTROL PLANE (Raft, HA, TLS)    │
         │  • Consensus • Audit Trail • PKI   │
         └──┬────────────────────────────────┬─┘
            │ signed assignments              │ signed observations
            ▼                                 ▼
      ┌────────────────────────────────────────────────────┐
      │         HOSTS (Sovereign, Policy-gated)            │
      │  ┌─────────────────────────────────────────────┐   │
      │  │ Local Policy Engine → Admit/Deny            │   │
      │  │ Runtime (Process/Docker) → Execute          │   │
      │  │ Journal (Hash-chain) → Observe & Log        │   │
      │  │ WireGuard Mesh → Peer-to-peer storage       │   │
      │  └─────────────────────────────────────────────┘   │
      └────────────────────────────────────────────────────┘

---

Key Features

🔐 Cryptographic Sovereignty

• Ed25519 identities for all actors
• Signed work assignments (no silent task migration)
• Signed observations and audit trails
• Replay and forgery rejection at every boundary
• Hash-chain ledger with tamper detection

📦 Distributed Storage

• BLAKE3 content-addressed storage (CAS)
• FastCDC for chunking and deduplication
• Merkle tree anti-entropy repair
• Automatic peer-to-peer healing
• Quorum snapshots (no single point of failure)

🌐 Self-Hosted Mesh

• Userspace WireGuard (no kernel module needed)
• Peer-to-peer gossip topology discovery
• Signed key bindings and rotation
• Host revocation support
• gVisor netstack (runs on any OS)

🏛️ HA Control Plane

• Raft consensus (3 or 5 members)
• Leader-only TLS bundle issuer
• Mutual TLS for all control APIs
• Signed backups and restore
• ~1.2s failover, zero failed requests

⚙️ Local Policy Enforcement

• Per-host admission control (no global consensus)
• Resource ledger model (CPU/memory capacity)
• Policy update atomicity
• Clock skew tolerance (±30s)
• Full audit trail of every decision

🧪 Comprehensive Chaos Testing

• 17 failure scenarios (leader crash, network partition, disk full, OOM, clock skew, etc.)
• Sustained traffic during chaos
• Invariant verification under failures
• Signed chaos reports

---

Quick Start (5 minutes)

Prerequisites

• Go 1.26+
• (Optional) Docker, Python 3, PostgreSQL

Build & Run

From Source:

# Clone and build
git clone https://github.com/CodesbyFebin/Decentralized-
cd Decentralized-
make build

# Start a 3-node dev cluster (real processes, real sockets)
./bin/dh dev up --dir ./devcluster

# In another terminal, use the operator CLI
export DH_HOME=./devcluster/operator

# View apps and status
./bin/dh get apps
./bin/dh describe app web

# Check mesh health and peer RTT
./bin/dh mesh peers

# Verify audit trail (local ledger verification)
./bin/dh audit verify

# Run a chaos scenario (leader crash, network partition, etc.)
./bin/dh chaos run --scenario leader-crash

# Tear down
./bin/dh dev down --dir ./devcluster

Expected output:

• ✅ 3 control-plane members elected leader via Raft
• ✅ 3 hosts joined and pinned certificates
• ✅ Sample app deployed with 3 replicas (desired/admitted/observed)
• ✅ Mesh peers exchanging signed gossip messages
• ✅ Audit trail verified locally (0 tampering detected)
• ✅ Chaos injection (leader killed) → failover in ~1.2s → zero workload interruption

---

Project Status

Milestones & Testing

Each milestone is validated by real multi-process tests: real processes, real sockets, real WireGuard mesh, and kill -9 where the test calls for it.

Milestone	Status	What Works	Tests
M1: Sovereign Runtime	✅ COMPLETE	Ed25519 identities, signed assignments/observations, local admission, replay/forgery rejection	tests/integration/m1_test.go
M2: Sovereign Storage	✅ COMPLETE	BLAKE3 CAS, FastCDC, Merkle anti-entropy, quorum snapshots, peer healing	m2_test.go
M3: Trust & Mesh	✅ COMPLETE	Root-signed roster, WireGuard, gossip, key rotation, revocation	m3_test.go
M4: Edge & TLS	✅ COMPLETE	L7 proxy, draining, ACME (HTTP-01, DNS-01, wildcard), Pebble integration	m4_test.go
M5: HA Control Plane	✅ COMPLETE	Raft, leader-only issuer, mutual TLS, signed backups, restore	m5_test.go
M6: Chaos Testing	✅ COMPLETE	17 scenarios (leader crash, partition, disk full, OOM, clock skew...)	make chaos (17/17 PASS)
M7: Federation	✅ COMPLETE	Root-signed agreements, delegated placements, grantor re-signing	m7_test.go
M8: Conformance	✅ COMPLETE	dh/v1 spec, 136 test vectors, Python reference impl	make conformance

P1 Qualification (Local VM)

• Gates 11-20 (Robustness): Concurrent admission, capacity enforcement, policy atomicity, clock skew, artifact quarantine, cascade containment, silent migration prevention, mesh partition recovery, authorization, health probe integrity
• Gates 21-32 (Chaos): Leader crash, control-plane outage, network partition, disk full, OOM, packet chaos, clock skew, storage corruption, cascading failures, and more
• Status: 10/10 gates PASS → P1-LOCAL-VM-A01 QUALIFIED

---

Run All Tests

make test           # Unit tests (Go + Python)
make race           # Unit tests with race detector
make integration    # M1–M7 multi-process tests (~5 min)
make conformance    # dh/v1 conformance (136 vectors)
make chaos          # All 17 chaos scenarios (~90 min)

Full test suite coverage:

• Unit tests: 100s of tests across identity, policy, storage, mesh, control plane
• Integration tests: 5 minutes of real multi-process execution
• Conformance: 136 test vectors against Go and Python
• Chaos: 17 scenarios under sustained traffic with invariant verification

---

Production Deployment

For Real Installations

# Full installation and configuration
./bin/dh init \
  --control-plane-count 5 \
  --tls \
  --acme-provider letsencrypt \
  --data-dir /var/lib/dh \
  --config-dir /etc/dh

See docs/runbooks/install.md for:

• Bootstrap process
• TLS and certificate management
• Backup and restore procedures
• Monitoring and observability
• Federation setup

Kubernetes Integration (Optional)

Deploy the 3-5 member control plane on Kubernetes while keeping hosts on bare metal:

make deploy-kubernetes

See deploy/kubernetes/README.md.

Note: VM qualification evidence is not established by Kubernetes deployment. Use the local-VM qualification for hardware trust validation.

---

Architecture & Design

Core Principles

1. Sovereignty Over Consensus — Each host decides locally (no global vote needed)
2. Signed Intent Over Silent Mutations — All work is cryptographically signed
3. Honesty Over Assertion — Observed state is measured, not claimed (UNKNOWN if unmeasured)
4. Peer-to-Peer Over Gateway — Mesh is WireGuard gossip, not hub-and-spoke
5. Content-Addressed Storage — BLAKE3 hashes, not locations

Key Subsystems

• Protocol (dh/v1): Canonical envelope format, signed objects, capability tokens
• Identity (pkg/identity): Ed25519 key management, root CA, host certificates
• Policy (pkg/policy): Per-host admission rules, resource ledger, update atomicity
• Storage (pkg/storage): BLAKE3 CAS, FastCDC chunking, Merkle anti-entropy
• Mesh (pkg/mesh): WireGuard control plane, SWIM gossip, peer discovery
• Control Plane (pkg/control): Raft consensus, FSM, API, reconciler
• Node (pkg/node): Host agent, admission, journal, runtime execution
• Chaos (pkg/chaos): 17 scenario templates with invariant checks

Documentation

• Protocol Spec — Normative dh/v1 with 136 test vectors
• Architecture — System overview and component interaction
• Trust Model — Cryptographic assurance model
• Runbooks — Installation, operation, troubleshooting
• Decisions — Design trade-offs and rationale
• Production Blueprint — Hardening roadmap

---

Unique Differentiators

vs. Kubernetes

• Local policy control (no centralized scheduler overrides)
• Peer-to-peer storage (no central etcd/database)
• Signed audit trails (cryptographic assurance)
• Simpler networking (userspace WireGuard, no CNI plugins)
• Hardware trust (P1 qualification validates real failure domains)

vs. Nomad

• Sovereign admission (not centralized)
• Content-addressed storage (built-in, peer-to-peer)
• Zero external APIs (operator console runs on cluster)
• Mesh is peer-to-peer (not agent-based with central routing)
• Cryptographic audit trail (tamper-resistant)

vs. Cloud APIs (EC2, Lambda, etc.)

• Full sovereignty (no vendor APIs, no callbacks, no phone-home)
• Works offline (no internet dependency)
• Cost-optimized (no per-request charges)
• Data stays local (no cloud sync)
• Compliance-ready (air-gapped, audit-proof)

---

Community & Contributing

We welcome contributions! See CONTRIBUTING.md for:

• Development setup
• Code style and conventions
• Testing requirements
• Commit message format
• Pull request process

Code of Conduct

See CODE_OF_CONDUCT.md. TL;DR: Be respectful, inclusive, and focused on solving problems.

Getting Help

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Runbooks: docs/runbooks/
• Protocol: dh/v1 Spec

---

License

Licensed under the GNU Affero General Public License v3. See LICENSE file for details.

---

Inspiration & Credits

Built on decades of distributed systems research:

• Raft consensus (Diego Ongaro, John Ousterhout)
• CRDT storage (SWIM gossip protocol)
• WireGuard (Jason A. Donenfeld)
• BLAKE3 (Jack O'Connor, Jean-Philippe Aumasson)
• Merkle trees (Ralph Merkle)
• FastCDC (Xia et al.)

---

Roadmap

Current Phase (P1): Foundation & Qualification

• ✅ M1–M8 milestones complete
• ✅ 10/10 P1 qualification gates passing
• ✅ Chaos testing (17/17 scenarios)
• ✅ 136-vector conformance testing
• 🚀 Production hardening (in progress)

Next Phase (P2): Multi-Physical & Multi-Operator

• Independent physical-host failure domains
• Independent administrative operator domains
• Advanced placement strategies
• Marketplace and resource trading

See docs/remaining-phases/README.md for detailed roadmap.

---

Performance & Scale

Measured Characteristics

• Control-plane failover: ~1.2 seconds
• Host join latency: ~2–5 seconds
• Mesh propagation: ~500ms (SWIM gossip)
• Storage repair: Peer-to-peer, O(chunk size)
• Audit verification: O(ledger size), ~100ms for 10k entries

Scalability

• Control plane: 3–5 members (Raft consensus)
• Hosts: Tested to 100+ (topology discovery via gossip)
• Workloads: Limited by host resources (process runtime) or --cpus/--memory (Docker runtime)
• Storage: Peer-to-peer replication (3x by default)

---

Security Considerations

Threat Model

• Byzantine operators: Not defended against (federation assumes trust)
• Compromised hosts: Isolated via local policy; cannot affect peers
• Compromised control plane: Audit trail immutable; host observations override

Audit & Compliance

• ✅ Full audit trail (hash-chained, cryptographically verified)
• ✅ No logs transmitted off-cluster
• ✅ Signed observations (operator cannot forge)
• ✅ Policy enforcement evidence (every admission decision logged)

---

Frequently Asked Questions

Q: Why not use Kubernetes? A: Kubernetes is centralized scheduling + configuration management. Decentralized.Host emphasizes host sovereignty, local policy, and P2P storage.

Q: How does this handle sensitive data? A: All data stays local to the cluster. WireGuard encryption in transit. BLAKE3 at rest. No cloud APIs or callbacks.

Q: Is this production-ready? A: M1–M8 milestones complete and tested. P1 qualification gates passing (10/10). Production hardening underway.

Q: Can I run this in a hyperscaler (AWS, GCP, etc.)? A: Yes, but the main value is in on-premises or air-gapped scenarios where you control the physical infrastructure.

Q: How do I get started? A: make build && ./bin/dh dev up --dir ./devcluster. Takes ~2 minutes.

---

Sponsors & Supporters

Built by Febin Codes and contributors.

---

📖 Documentation · 🚀 Quick Start · 💬 Discussions · 📝 Issues

Made with ❤️ for self-hosted infrastructure