Hypergraph Meta Cluster - Hypernode Bundle

Version: 2.0.0 Release Date: 2025-01-31 License: MIT

An autonomous, self-configuring hypernode bundle for joining the Hypergraph Meta Cluster network. This bundle provides automated deployment, factory integration, and secure authentication for distributed hypergraph computation.

Overview
Features
Quick Start
Architecture
Configuration
CLI Reference
Fabrik Gating System
Public Endpoints
Deployment Scenarios
API Reference
Security
Troubleshooting
License & Support

Overview

The Hypernode Bundle is a complete, production-ready deployment package that enables any compatible system to join the Hypergraph Meta Cluster as an authenticated node. It includes:

Automated Setup: One-command initialization and deployment
Factory Integration: Ed25519-signed handshake with the Factory App
Hypergraph Authentication: Metacluster registration and consensus participation
Public Endpoints: Automatic DNS registration and TLS configuration
Fabrik Gating: Role-based and tribe-based access control
Multi-Architecture Support: x86_64, ARM64, Raspberry Pi
Service Mesh: Docker Swarm and WireGuard VPN integration

Features

Core Capabilities

Self-Provisioning: Automatic VM or container deployment
Zero-Touch Configuration: Interactive or automated setup
Factory Handshake: Cryptographic authentication with the Factory
Metacluster Registration: Join the hypergraph as an authenticated peer
Consent Gating: Peer-approved sensitive operations
Public API Endpoints: HTTPS with automatic Let's Encrypt
Resource Gates: Fine-grained access control
Monitoring: Prometheus, Grafana, and custom dashboards
Auto-Updates: Self-updating with rolling deployment

Service Profiles

Minimal Profile (4 services):

API Gateway, Graph Service, Storage Hub, Webapp

Standard Profile (12 services):

All minimal + Hypergraph Lab, Semantic Lab, Ledger Bridge, Key Manager, Model Gateway, Data Rhizome, Nginx, Redis

Full Profile (30+ services):

All standard + SDR Capture, GPIO Agent, Vision Agent, Weather satellites, Bitcoin, IPFS, and more

Quick Start

Prerequisites

OS: Ubuntu 22.04+, Debian 11+, Fedora 39+, Raspberry Pi OS
RAM: 2GB minimum (4GB+ recommended)
Disk: 20GB minimum (100GB+ recommended)
Network: Public IP or NAT traversal capability
Container Engine: Docker 24+ or Podman 4+

One-Command Install

curl -fsSL https://hypergraph.dev/install.sh | bash

This script will:

Detect your OS and architecture
Install dependencies (Docker, WireGuard, etc.)
Generate node identity and cryptographic keys
Register with the Factory and Hypergraph network
Configure services based on your hardware
Launch the hypernode and join the mesh

Manual Installation

# Clone or extract the bundle
cd hypergraph_meta_cluster_bundle

# Run the automated setup
./hypernode_bundle/setup-hypernode.sh

# Or use the CLI for interactive setup
./cli/hypergraph init
./cli/hypergraph start

Architecture

Network Topology

Internet
   ↓ (HTTPS/WSS)
Nginx Reverse Proxy (Port 443)
   ↓
API Gateway (Ed25519 Auth)
   ↓
WireGuard VPN Mesh (10.88.0.0/16)
   ↓
Docker Swarm Overlay (hypergraph_overlay)
   ↓ (Service Discovery)
Microservices Mesh
   ├── Hypergraph Lab
   ├── Semantic Lab
   ├── Ledger Bridge
   ├── Storage Hub
   └── Graph Service

Authentication Flow

1. Node generates Ed25519 keypair
2. Node sends registration request to Factory
3. Factory validates and issues node certificate
4. Node joins Hypergraph metacluster with signed identity
5. Peers verify node signature before accepting connections
6. Consent-gated operations require peer quorum

Factory Handshake Protocol

// 1. Node → Factory: Registration Request
POST /api/factory/register
{
  "nodeId": "uuid-v4",
  "publicKey": "Ed25519 public key",
  "capabilities": ["gpu", "sdr", "storage"],
  "location": "eu-west-1",
  "timestamp": "ISO8601"
}
// Request signed with X-Signature header

// 2. Factory → Node: Certificate Issuance
{
  "success": true,
  "certificate": "X.509 certificate",
  "hypergraphAddress": "10.88.0.42",
  "bootstrapPeers": ["10.88.0.1", "10.88.0.2"],
  "token": "JWT token for API access"
}

// 3. Node → Hypergraph: Metacluster Join
POST /api/hypergraph/join
{
  "nodeId": "uuid-v4",
  "certificate": "Factory-issued cert",
  "capabilities": ["gpu", "sdr", "storage"],
  "signature": "Ed25519 signature"
}

// 4. Hypergraph → Node: Peer List
{
  "success": true,
  "peers": [...],
  "consensusRules": {...},
  "tribe": "default"
}

Configuration

Environment Profiles

Development (.env.dev):

Local services on localhost
HTTP (no TLS)
Debug logging
Mock blockchain

Staging (.env.staging):

Services on VPN
Self-signed TLS
Info logging
Testnet blockchain

Production (.env.prod):

Public endpoints
Let's Encrypt TLS
Warn logging
Mainnet blockchain

Node Configuration

Edit ~/.hypergraph/config.yaml:

node:
  id: "auto-generated-uuid"
  name: "my-hypernode"
  location: "eu-west-1"
  profile: "standard"  # minimal | standard | full

network:
  vpn:
    enabled: true
    interface: wg0
    port: 51820

  docker_swarm:
    enabled: true
    role: worker  # worker | manager

  dns:
    provider: infomaniak
    domain: hypergraph.dev
    auto_register: true

services:
  factory:
    enabled: true
    url: https://factory.hypergraph.dev

  hypergraph:
    enabled: true
    consensus: true

security:
  firewall: true
  tls: true
  consent_gating: true

fabrik:
  enabled: true
  default_tribe: "public"
  default_role: "guest"

  tribes:
    - name: "core"
      roles: ["admin", "operator"]
      gates: ["hypergraph:write", "factory:admin"]

    - name: "builders"
      roles: ["builder", "reviewer"]
      gates: ["image:build", "deploy:staging"]

    - name: "public"
      roles: ["guest", "user"]
      gates: ["api:read", "storage:read"]

CLI Reference

The hypergraph CLI provides complete node management. See ../cli/hypergraph-cli.sh for full implementation.

Node Management

hypergraph init                      # Initialize node (interactive)
hypergraph init --profile standard   # Use preset profile
hypergraph start                     # Start all services
hypergraph stop                      # Stop all services
hypergraph status                    # Show node and service status

Network Commands

hypergraph network info       # Show VPN IP, peers, etc.
hypergraph network peers      # List connected peers
hypergraph network test       # Test connectivity

Factory Integration

hypergraph factory register   # Register with Factory
hypergraph factory validate   # Verify certificate
hypergraph factory status     # Connection and auth state

Security

hypergraph security audit        # Run security audit
hypergraph security rotate-keys  # Generate new keys
hypergraph doctor                # Full health check

Fabrik Gating System

Overview

Fabrik provides fine-grained access control based on:

Roles: User capabilities (admin, builder, user, guest)
Tribes: Organizational units with shared access
Gates: Protected resources requiring specific permissions
Consent: Peer-approved operations for sensitive actions

Role Hierarchy

admin (all gates)
  ├── operator (runtime management)
  ├── builder (deployment & builds)
  └── security (key management)

user (read/write data)
  ├── contributor (submit data)
  └── reviewer (approve submissions)

guest (read-only)

Consent Gating

Sensitive operations require peer approval:

// Example: Hypergraph Lab inference
POST /api/v1/hypergraph-lab/differentiate
{
  "input": {...},
  "consent": {
    "token": "lab-epoch-001",
    "peers": ["peer-a-uuid", "peer-b-uuid"],
    "threshold": 2,
    "authority": {
      "name": "admin",
      "signature": "Ed25519 signature"
    }
  }
}

Public Endpoints

Default Endpoints

https://NODE_ID.hypergraph.dev
  ├── /                    → Webapp (UI)
  ├── /api                 → API Gateway
  ├── /api/v1/hypergraph   → Hypergraph Lab
  ├── /api/v1/semantic     → Semantic Lab
  ├── /api/ledger          → Ledger Bridge
  ├── /storage             → Storage Hub
  └── /ws                  → WebSocket (real-time)

TLS Configuration

Let's Encrypt (automatic):

security:
  tls: true
  letsencrypt:
    enabled: true
    email: admin@hypergraph.dev

Deployment Scenarios

Cloud VM (AWS/GCP/Azure)

# Launch Ubuntu 22.04 VM with 4GB RAM, 50GB disk
# Open ports: 80, 443, 51820/UDP
curl -fsSL https://hypergraph.dev/install.sh | bash

Raspberry Pi

curl -fsSL https://hypergraph.dev/install-pi.sh | bash

Docker Swarm Cluster

# On manager
docker swarm init
WORKER_TOKEN=$(docker swarm join-token -q worker)

# On workers
./setup-hypernode.sh --swarm-token $WORKER_TOKEN

API Reference

Authentication

curl -X POST https://NODE/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"user","password":"pass"}'

Hypergraph Lab

curl -X POST https://NODE/api/v1/hypergraph-lab/differentiate \
  -H "Authorization: Bearer TOKEN" \
  -d '{"input":"text","consent":{...}}'

Semantic Lab

curl -X POST https://NODE/api/v1/semantic/playground \
  -d '{"text":"sample text","context":"analysis"}'

Security

Threat Model

Authentication: Ed25519 signatures prevent impersonation
Authorization: Fabrik gates enforce least-privilege
Consent: Peer quorum prevents unilateral actions
Encryption: TLS 1.3 for all network traffic
Firewall: Only VPN and HTTPS ports exposed

Best Practices

Rotate keys regularly (every 90 days)
Enable hardware auth for admin roles (YubiKey)
Use strong passwords (generated, not reused)
Monitor auth logs for anomalies
Keep software updated (auto-update enabled)

Troubleshooting

Factory Registration Fails

# Check connectivity
curl https://factory.hypergraph.dev/health

# Verify keys
ls ~/.hypergraph/keys/

# Re-register
./cli/hypergraph factory register

VPN Not Connecting

# Check WireGuard status
sudo wg show

# Rejoin VPN
./cli/hypergraph network leave
./cli/hypergraph network join

Services Won't Start

# Run diagnostics
./cli/hypergraph doctor

# View logs
./cli/hypergraph logs --verbose

License & Support

License: MIT License - see LICENSE

Support:

Documentation: https://docs.hypergraph.dev
Issues: https://github.com/your-org/hypergraph-hypernode/issues
Email: support@hypergraph.dev

Built with ❤️ for the Hypergraph Meta-Cluster

FilesExpand file tree

README.md

Latest commit

History

README.md

File metadata and controls

Hypergraph Meta Cluster - Hypernode Bundle

Table of Contents

Overview

Features

Core Capabilities

Service Profiles

Quick Start

Prerequisites

One-Command Install

Manual Installation

Architecture

Network Topology

Authentication Flow

Factory Handshake Protocol

Configuration

Environment Profiles

Node Configuration

CLI Reference

Node Management

Network Commands

Factory Integration

Security

Fabrik Gating System

Overview

Role Hierarchy

Consent Gating

Public Endpoints

Default Endpoints

TLS Configuration

Deployment Scenarios

Cloud VM (AWS/GCP/Azure)

Raspberry Pi

Docker Swarm Cluster

API Reference

Authentication

Hypergraph Lab

Semantic Lab

Security

Threat Model

Best Practices

Troubleshooting

Factory Registration Fails

VPN Not Connecting

Services Won't Start

License & Support