Hivemind - Distributed Compute Runtime

A distributed compute runtime for public-network workers, now rewritten in Rust.

Quick Start

# Build
make build

# Run tests
make test

# Start development environment
make dev

User Guide

If you want to submit a task and write the task program, start here:

• docs/MANAGED_FUNCTION_RUNTIME.md — the active managed-function-v1 syntax, metering model, and settlement formula
• docs/PUBLIC_NETWORK_LIMITATIONS.md — what the network does not do yet, including that CPT is an internal quota unit
• The Docs and Usage rules pages on the official site render the same reference from frontend/src/lib/hivemind-site-data.mjs; frontend/site-contract.test.mjs checks the limits and failure codes it publishes against the enforcing source

Architecture

Hivemind is a batch-oriented distributed compute runtime. The system consists of:

• Hivemind Binary (hivemind-rs/) - Unified Rust binary containing all services
• Official Site (frontend/) - Public-facing product site, account center, and documentation
• Master UI (frontend/master-ui/) - React surface for users: task submission, API keys, dashboard
• Worker UI (frontend/worker-ui/) - React surface for workers: node status, task queue, earnings
• Infrastructure - Docker Compose for Redis and PostgreSQL

Services

All services run in a single binary (hivemind-bin):

Service	Port	Protocol	Description
Master API	8082	HTTP	User authentication, task management
Nodepool	50051	gRPC	Worker registration, task scheduling
Worker	50053	gRPC	Task execution, result reporting

Rust Crates

hivemind-rs/
├── crates/
│   ├── auth/           - JWT authentication
│   ├── common/         - Shared utilities
│   ├── config/         - Configuration management
│   ├── database/       - PostgreSQL & Redis integration
│   ├── hivemind-bin/   - Main binary entry point
│   ├── master-api/     - HTTP API handlers
│   ├── models/         - Data models
│   ├── node-manager/   - Worker management
│   ├── proto/          - gRPC protobuf definitions
│   ├── task-scheduler/ - Task dispatch & scheduling
│   ├── vpn-service/    - VPN management
│   └── worker-executor/- Task execution engine

Development

Prerequisites

• Rust 1.70+
• Docker (for Redis & PostgreSQL)
• Node.js 18+ (for frontend)

Build

# Build Rust binary
make build

# Build frontend
make build-frontend

# Release smoke all frontend surfaces
make smoke-frontend

The shared frontend release harness also runs directly on Windows PowerShell:

powershell -NoProfile -ExecutionPolicy Bypass -File scripts/build-release-frontends.ps1

$env:VITE_API_BASE = "http://127.0.0.1:8082"
$env:VITE_WORKER_CONTROL_BASE = "http://127.0.0.1:18080"
powershell -NoProfile -ExecutionPolicy Bypass -File scripts/release-frontend-smoke.ps1

Test

# Run all tests
make test

# Run tests with verbose output
make test-verbose

Lint & Format

# Run linter
make lint

# Format code
make fmt

Deployment

Exposed Ports

Service	Port	Description
Official Site	8080	Public product site and account center
Master UI	3000	User-facing task dashboard
Worker UI	3001	Worker node control panel
Master API	8082	HTTP API (auth, tasks)
Nodepool gRPC	50051	Worker registration
Worker gRPC	50053	Task execution
Worker HTTP	18080	Local worker control API
Redis	6379	Session & cache
PostgreSQL	5432	Persistent data

Docker Compose

# Start all services
make docker-up

# View logs
make docker-logs

# Stop all services
make docker-down

Three-surface release

The release candidate consists of the public Official Site/account center on port 8080, the task-oriented Master UI on port 3000, and the provider-oriented Worker UI on port 3001. The detailed operator runbook, environment contract, trust boundaries, smoke checks, browser tests, and troubleshooting steps are in docs/GETTING_STARTED.md.

From the repository root on Windows, build and leave the complete stack running:

powershell -NoProfile -ExecutionPolicy Bypass -File scripts/release-stack-smoke.ps1 -KeepRunning

Then run the real cross-surface browser journey:

cd frontend; npm run test:e2e

When verification is complete, return to the repository root and run docker compose down. See the runbook before using raw Compose in production: unlike the smoke harness, raw Compose requires secrets and the matching worker execution key pair to be supplied.

Managed consensus

Managed tasks settle through Nodepool-coordinated replicated execution by default. Nodepool assigns the same deterministic task to three distinct registered Workers and requires a strict majority of two to return matching canonical results. It persists a quorum certificate before completing or settling the task, and never falls back to a single-Worker result.

Consensus is agreement evidence, not independent correctness validation: a colluding or commonly compromised Worker majority can still agree on an incorrect result. Only deterministic, side-effect-free managed tasks are eligible. For v1, max_cpt is the maximum total task charge, including the 10% platform fee and all configured replicas (three by default); it is not a per-replica cap. Nodepool derives identical deterministic integer execution budgets from the fee-exclusive cap. For a 100 CPT cap and three replicas, each receives 30 CPT of execution budget, the worst-case hold is 99 CPT (90 usage + 9 fee), and the remaining 1 CPT stays with the owner. Settlement aggregates valid replica usage plus the fee and never exceeds max_cpt; unused held CPT is refunded. Automatic paid retries are disabled until a funded platform treasury is available, and retry work is not charged to task owners. The task-wide cap applies to new v1 submissions; historical tasks billed under the former per-replica contract remain as recorded and are not retroactively re-capped or refunded. Quorum output and payment eligibility are separate decisions.

The default rollout is enforce. Use observe for a canary that fans out replicas, records non-settling shadow state, and never exposes a billable result; use disabled to turn the consensus path off entirely.

MANAGED_CONSENSUS_ROLLOUT_MODE=enforce
MANAGED_CONSENSUS_REPLICA_COUNT=3
MANAGED_CONSENSUS_QUORUM=2
MANAGED_CONSENSUS_MAX_RESULT_BYTES=262144

Do not treat a consensus certificate as independent correctness validation, and do not enable it for side-effecting tasks.

Manual

# Start Redis
docker run -d -p 6379:6379 redis:7-alpine

# Start PostgreSQL
export POSTGRES_PASSWORD='replace-with-a-strong-password'
docker run -d -p 5432:5432 \
  -e POSTGRES_DB=hivemind \
  -e POSTGRES_USER=hivemind \
  -e POSTGRES_PASSWORD="$POSTGRES_PASSWORD" \
  postgres:16-alpine

# Run Hivemind
DATABASE_URL="postgres://hivemind:${POSTGRES_PASSWORD}@localhost:5432/hivemind" \
REDIS_URL=redis://localhost:6379 \
./target/release/hivemind-bin all

Configuration

Configuration is via environment variables. The table below describes server/service deployment settings; it is not a configuration checklist for ordinary packaged Master or Worker nodes. Those users do not set the server JWT_SECRET or manually pin a Nodepool IP: first authenticated login performs VPN enrollment, and the client discovers Nodepool through the overlay.

Variable	Default	Description
DATABASE_URL	-	PostgreSQL connection string
REDIS_URL	-	Redis connection string
JWT_SECRET	-	JWT signing secret
HIVEMIND_ADMIN_USERS	unset	Comma-separated usernames allowed to access /api/admin/* endpoints
HIVEMIND_TASK_SUBMIT_LIMIT_PER_MINUTE	60	Per-user task submission rate limit for a rolling 1-minute window (0 disables limiting)
WEBSITE_NODEPOOL_GRPC_ADDR	localhost:50051	Server-side nodepool target used only by the official website backend for account endpoints
MASTER_HTTP_ADDR	0.0.0.0:8082	Master HTTP listen address
NODEPOOL_GRPC_ADDR	0.0.0.0:50051	Nodepool gRPC listen/connect address
WORKER_GRPC_ADDR	0.0.0.0:50053	Worker gRPC listen address
WORKER_ADVERTISE_ADDR	-	Worker address registered with nodepool
EXECUTOR_SANDBOX_DIR	./sandbox	Per-task working directory root
MANAGED_CONSENSUS_ROLLOUT_MODE	enforce	Managed consensus rollout: disabled, observe, or enforce; the default is enforce, which settles managed tasks only from a strict-majority quorum certificate
MANAGED_CONSENSUS_REPLICA_COUNT	3	Distinct Worker replicas for consensus-managed tasks
MANAGED_CONSENSUS_QUORUM	2	Required matching replicas; must be a strict majority
MANAGED_CONSENSUS_TIMEOUT_SECS	120	Overall deadline for one consensus round
MANAGED_CONSENSUS_MAX_RESULT_BYTES	262144	Nodepool/Worker cap for one consensus result
LOG_LEVEL	info	Log level (debug, info, warn, error)

API Reference

Authentication

# Login
curl -X POST http://localhost:8082/api/login \
  -H "Content-Type: application/json" \
  -d '{"username": "<username>", "password": "<password>"}'

Tasks

# Create task
curl -X POST http://localhost:8082/api/tasks \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "task_id": "task-1",
    "runtime": "managed-function-v1",
    "task_source": "fn sum(values) {\n  return get(values, \"a\") + get(values, \"b\");\n}\nsum(input);\n",
    "torrent": "{\"a\": 1, \"b\": 2}",
    "memory_gb": 4,
    "cpu_score": 100,
    "storage_gb": 10,
    "max_cpt": 1000
  }'

# List tasks
curl http://localhost:8082/api/tasks \
  -H "Authorization: Bearer <token>"

Admin Observability

# Cache alert (with thresholds)
curl "http://localhost:8082/api/admin/scheduling/cache-alert?low=0.5&high=2.0" \
  -H "Authorization: Bearer <admin-token>"

# Cache anomaly history (persisted low/high alerts)
curl "http://localhost:8082/api/admin/scheduling/cache-anomalies?limit=100" \
  -H "Authorization: Bearer <admin-token>"

# Admin audit logs (trust-control / artifact cleanup / etc.)
curl "http://localhost:8082/api/admin/audit/logs?limit=100" \
  -H "Authorization: Bearer <admin-token>"

Health Check

curl http://localhost:8082/health

License

MIT