# Hyverk pool

Machines lend a share of their memory. The hub picks the strongest
open-weights model that fits in the memory being lent, splits it across
those machines by layers, and keeps it serving as machines come and go.
Anyone running a node can send requests to that model from their own
machine.

## Parts

- **Node** (`hyverk-node`): runs on each machine. Measures the hardware,
  lends the share its owner chose (10% to 90% of unified memory on Apple
  Silicon, of VRAM on NVIDIA), runs llama.cpp when assigned, and serves an
  OpenAI-compatible endpoint on `127.0.0.1:17080`.
- **Hub** (`hyverk-pool-hub`, at `llm.meshkore.com`): admits nodes, plans
  the split, hands out roles, relays traffic between nodes, and publishes
  the live stats on this site. It runs no model.
- **Head**: the node holding the first layers. Runs `llama-server`, which
  drives the other members' `ggml-rpc-server` processes, and answers every
  request of the current generation.
- **Worker**: any other member. Holds its share of the layers in memory.

## A request, end to end

1. A program on your machine calls `http://127.0.0.1:17080/v1/chat/completions`.
2. Your node asks the hub (signed request) which node is head.
3. Your node opens a link to the head: a signed WebSocket to the hub, which
   checks that the link is allowed and pairs it with one the head opens back.
4. The head checks the request, caps its length, and passes it to its
   `llama-server` on loopback. llama.cpp runs the layers on the head and on
   each worker, over the same kind of links.
5. Tokens stream back the same way.

Engines listen on `127.0.0.1` only. Nothing on a member's machine accepts
connections from the internet: all traffic between nodes goes out to the
hub over TLS and is relayed there. That is what lets machines on different
networks, behind NAT, form one split.

## Generations

Each plan is a generation: a model, a head, a list of workers and their
shares. When a machine joins, leaves, or changes what it lends, the hub
plans again. A better plan replaces the running one after it has been
stable for a while; a plan that no longer fits is replaced at once.

## Pages

- [Join](join.md): run a node
- [Use](use.md): call the model
- [Security](security.md)
- [Credits](credits.md)
- [Protocol](protocol.md)
