# Join the pool

Two ways in. People install the desktop app. Agents (Claude Code, Codex,
Cursor or similar) and servers follow the command line steps below, each
of which is a shell command or a file to write. Neither way needs an
account, an email or a form: the node creates its identity key the first
time it runs.

## The desktop app

Hyverk for macOS (Apple silicon) and Windows (x64) is a menu bar or tray
app with the node and llama.cpp inside. Install it, open it, and pick
"Lend this computer" in its menu. Lending is off until then. The menu also
sets the share of memory lent (25 to 90%), opens this dashboard, shows the
node log and switches start at login on or off. Quitting the app stops the
engines and frees the memory.

## Command line

Run the steps on the machine that will lend. Commands are for macOS and
Linux shells; on Windows use PowerShell equivalents or the desktop app.

### 0. Check the machine

Lending needs one of:

- Apple silicon (M1 or later) with 16 GB of memory or more, macOS 13+.
- An NVIDIA GPU with 8 GB of VRAM or more (CUDA build), or an AMD or Intel
  GPU with a current Vulkan driver (Vulkan build).

A machine with neither can still run a node to use the pool, with lending
off.

Tools: `curl`, `tar`, Rust from <https://rustup.rs> and `protoc`
(`brew install protobuf`, `apt install protobuf-compiler`) to build the
node.
Disk: about 25 GB for the model the pool serves now, more for larger ones.

### 1. Get llama.cpp

All members of a split must run the same llama.cpp build: the RPC wire
format changes between versions. The pool pins release **b12606**. Use the
official build for the machine; do not build another version.

```bash
B=b12606
mkdir -p ~/.hyverk/engines && cd ~/.hyverk/engines
# Apple silicon:
curl -fL https://github.com/ggml-org/llama.cpp/releases/download/$B/llama-$B-bin-macos-arm64.tar.gz | tar -xz --strip-components 1
# Linux with NVIDIA, instead:
#   llama-$B-bin-ubuntu-cuda-12.8-x64.tar.gz
# Linux with AMD or Intel (Vulkan), instead:
#   llama-$B-bin-ubuntu-vulkan-x64.tar.gz
./llama-server --version
./llama-server --list-devices
```

`--version` must say `build 12606`. `--list-devices` must show a GPU
(`MTL0`, `CUDA0` or `Vulkan0`); the node lends the first one listed.

### 2. Build the node

```bash
git clone https://github.com/capitaharlock/hyverk-distributed-llm ~/.hyverk/src/hyverk
cd ~/.hyverk/src/hyverk
cargo build --release -p hyverk-node
```

The binary is `target/release/hyverk-node`.

### 3. Run it

```bash
~/.hyverk/src/hyverk/target/release/hyverk-node pool --engine-dir ~/.hyverk/engines --lend
```

That joins <https://llm.meshkore.com> under this machine's host name and
lends half of its memory. `hyverk-node pool --help` lists the options
(`--hub`, `--name`, `--state-dir`, `--api-port`). Without `--lend` the node
starts with lending off.

For settings that the flags do not cover, write `~/.hyverk/pool.toml`; the
`pool` command reads it first and flags override it:

```toml
[node]
name = "my-mac"                    # label on the dashboard, 1 to 48 characters

[node.pool]
memory_fraction = 0.5              # share of memory lent, 0.1 to 0.9
engine_dir = "~/.hyverk/engines"
```

Pick `memory_fraction` with the owner: 0.9 for a machine dedicated to the
pool, 0.5 for one in daily use, 0.25 to stay out of the way. Do not put
anything secret in the file. It holds no credential.

On first start the node writes its identity key to `~/.hyverk/identity.key`
(mode 0600). The public half, 64 hex characters, is the node id; the
dashboard shows its first 12. Keep the file: it is the node's identity for
anything earned later. Lose it and the node starts over as a new one.

### 4. Check it

```bash
curl -s http://127.0.0.1:17080/status
```

`engine.connected` is `true` once the hub has admitted the node. The node
also appears on <https://llm.meshkore.com> within a few seconds. If the pool
is serving, this answers:

```bash
curl -s http://127.0.0.1:17080/v1/chat/completions \
  -H 'content-type: application/json' \
  -d '{"messages":[{"role":"user","content":"Say hello"}],"max_tokens":400}'
```

The current model reasons before it answers, so a small `max_tokens` can
end before any text. When the node is picked as a member, it may first
download the model file (sha256 checked; a GGUF already in Ollama's store
is reused) and then load its share. The dashboard shows `downloading`,
`starting`, then `ready`.

### 5. Change what is lent

```bash
curl -s http://127.0.0.1:17080/control/settings \
  -H 'content-type: application/json' \
  -d '{"lending": false}'

curl -s http://127.0.0.1:17080/control/settings \
  -H 'content-type: application/json' \
  -d '{"lending": true, "memory_fraction": 0.75}'
```

Settings persist in `~/.hyverk/pool_settings.json` and win over the config
and flags from then on. Pausing frees the memory at once; the pool replans
without this machine. `POST /control/shutdown` stops the engines and the
node.

### 6. Keep it running

macOS, as a user agent (`~/Library/LaunchAgents/com.hyverk.node.plist`):

```xml
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0"><dict>
  <key>Label</key><string>com.hyverk.node</string>
  <key>ProgramArguments</key><array>
    <string>/Users/YOU/.hyverk/src/hyverk/target/release/hyverk-node</string>
    <string>pool</string>
    <string>--engine-dir</string><string>/Users/YOU/.hyverk/engines</string>
  </array>
  <key>RunAtLoad</key><true/>
  <key>KeepAlive</key><true/>
  <key>StandardErrorPath</key><string>/Users/YOU/.hyverk/logs/node.log</string>
</dict></plist>
```

```bash
launchctl load ~/Library/LaunchAgents/com.hyverk.node.plist
```

Linux, as a user service (`~/.config/systemd/user/hyverk-node.service`):

```ini
[Unit]
Description=Hyverk pool node
After=network-online.target

[Service]
ExecStart=%h/.hyverk/src/hyverk/target/release/hyverk-node pool --engine-dir %h/.hyverk/engines
Restart=on-failure

[Install]
WantedBy=default.target
```

```bash
systemctl --user enable --now hyverk-node
```

The node stops its engines on SIGTERM and SIGINT. If it is killed outright,
the next start stops the engines the old run left behind.

### 7. Leave

Stop the process. To leave for good, delete `~/.hyverk/identity.key`,
`~/.hyverk/models/`, `~/.hyverk/engines/` and `~/.hyverk/src/`.

## Same building, faster

Machines on one trusted LAN can let the head reach their RPC server
directly instead of through the hub:

```toml
[node.pool]
transport = "direct"
advertise_host = "192.168.1.21"   # this machine's LAN address
rpc_port = 50052
```

llama.cpp RPC has no authentication or encryption, so anyone on that
network can use or read the engine. Only use it where every device on the
network is trusted. Both ends of a pair must opt in; otherwise the link
goes through the hub.

## Troubleshooting

- Logs: the node's stderr (the desktop app keeps it as `node.log`, "Show
  node log" in its menu), plus `~/.hyverk/logs/engine-head.log` and
  `engine-worker.log` from llama.cpp.
- `hub speaks protocol N, this node M` in the log: update the node
  (`git pull`, build again) or the app.
- `rejected: ...`: the hub refused the hello; the reason says why (name
  length, too many nodes from one address, pool full).
- `Engine binaries missing`: `--engine-dir` does not point at the folder
  with `llama-server` and `ggml-rpc-server`.
- `device="none"` in the start line: llama.cpp found no GPU. Check
  `llama-server --list-devices` and the GPU driver.
- A node that fails an assignment sits out for a few minutes before it is
  planned again.
