ShardHive

Verifiable inference from a swarm of expert shards.

ShardHive is a Vaulta/WharfKit dApp and Python inference prototype for a decentralized LLM network. Contributors run a narrow worker daemon on their hardware, the orchestrator exposes an OpenAI-compatible API, and each stage returns signed activation commitments for audit and settlement.

What Works In V1

• Harness-governed SvelteKit dashboard with WharfKit/Vaulta wiring.
• Contributor CLI for init, config checks, daemon serving, and status checks.
• FastAPI orchestrator with GET /v1/models, POST /v1/chat/completions, GET /healthz, GET /metrics, and job receipt lookup.
• Worker daemon with a stage execution API, deterministic fake runner for CI, and an optional MLX runner for Apple Silicon.
• Shared protocol package for tensors, Merkle roots, signed receipts, and job response models.
• Vaulta/Antelope contract stubs for workers, models, jobs, stage commits, reveals, settlement, slashing, and claims.
• Qwen3 MoE manifests for 30B-A3B and 235B-A22B.

Layout

services/orchestrator/     OpenAI-compatible coordinator API
services/worker/           Contributor daemon and shard runners
packages/protocol/         Pydantic protocol, tensor hashing, receipts
proto/shardhive/v1/        Worker gRPC contract
smart-contract/            Vaulta/Antelope commitment and rewards contract
src/                       SvelteKit + WharfKit dashboard
configs/                   Model, pipeline, and worker manifests
docs/                      Architecture, setup, security, verification roadmap
tests/                     Python protocol and orchestrator tests

Setup

/Users/danielfugere/.bun/bin/bun install
python3 -m venv .venv
.venv/bin/python -m pip install --upgrade pip
.venv/bin/python -m pip install -e ".[dev]"

Install MLX support on Apple Silicon when running real local model shards:

.venv/bin/python -m pip install -e ".[mlx]"

Run The Prototype

Start the credits and settlement dashboard:

/Users/danielfugere/.bun/bin/bun run dev

Run the orchestrator with the in-process three-stage fake pipeline:

.venv/bin/python -m shardhive_orchestrator.main

Call the OpenAI-compatible endpoint:

curl -s http://127.0.0.1:8080/v1/chat/completions \
  -H 'content-type: application/json' \
  -d '{"model":"tiny-mlx-debug","messages":[{"role":"user","content":"hello hive"}]}'

Participate From The CLI

Contributors should join and operate inference workers from the terminal, not from the web dashboard.

The shortest path uses the npm wrapper. It creates a managed Python environment under ~/.shardhive, installs ShardHive into it, initializes a worker config if needed, and starts the worker daemon:

npx shardhive start

For an MLX-backed Apple Silicon worker:

npx shardhive start --runner mlx

Use SHARDHIVE_HOME to choose a different managed directory, or SHARDHIVE_PYTHON to force a specific Python interpreter.

Manual venv setup is still supported:

.venv/bin/shardhive init \
  --config .shardhive/worker.json \
  --worker-id local-worker-1 \
  --role embed \
  --stage-index 0

.venv/bin/shardhive doctor --config .shardhive/worker.json
.venv/bin/shardhive serve --config .shardhive/worker.json

Check the orchestrator and a worker:

.venv/bin/shardhive status \
  --orchestrator http://127.0.0.1:8080 \
  --worker http://127.0.0.1:9101

shardhive-worker remains available as a compatibility alias.

The npm package exposes the same shardhive wrapper:

npm install -g shardhive
shardhive --help

The wrapper uses SHARDHIVE_PYTHON, a local .venv/bin/python, or a managed ~/.shardhive/venv to run the Python worker CLI.

Verification

/Users/danielfugere/.bun/bin/bun run check
.venv/bin/python -m pytest tests packages services
cd smart-contract && /Users/danielfugere/.bun/bin/bun install && make compile && /Users/danielfugere/.bun/bin/bun test

The optional MLX integration test is gated:

SHARDHIVE_RUN_MLX=1 .venv/bin/python -m pytest services/worker

Contributor Safety

Workers expose only the narrow stage API described in proto/shardhive/v1/inference.proto. The orchestrator never receives SSH, shell, file browser, or broad device control. Production workers should run under a limited macOS user or sandbox profile with model-cache-only filesystem access.

Chain Direction

V1 uses Vaulta/WharfKit because it matches Daniel's local dApp stack. Solana micro-payments are documented as a future bridge in docs/roadmap.md.