DOCUMENTATION
Documentation
Documentation for viiwork v2.11.0
GETTING STARTED
Setting up a machine
viiwork init turns a machine with GPUs and some GGUF model files into a running node. It asks a few questions and shows every file it will write. It…
Read pageConfiguration
One file per machine. viiwork --config /etc/viiwork/viiwork.yaml (the default path; on a Mac, ~/.config/viiwork/viiwork.yaml) is the only input — there…
Read pagemacOS (Apple Silicon) nodes
A Mac is just another node. One native viiwork process runs llama-server through the ordinary llamacpp engine. On a Mac that engine uses Metal. The node…
Read pageMigrating to viiwork 2
viiwork 2 refuses a v1 viiwork.yaml at startup with v1 config: see docs/migrating-to-v2.md. This page is where that points: what changed, how several v1…
Read pageRUNNING A FLEET
The Mesh
Nodes form one mesh without peer lists. Switch a machine on and its models are usable from every node within seconds; switch it off and routing stops…
Read pageModels and Hardware
What the reference fleet runs, what has been measured on it, and the hardware rules those measurements imply. Numbers here are measured throughput, not…
Read pageOperations
Running a fleet: the scripts, the acceptance checker and the MCP server.
Read pageDashboards
Every page is served on port 8086 by every node, and needs no configuration.
Read pagePower, Cost and Energy
Three related features, in increasing order of what they need from the machine:
Read pageSecurity and the Trust Model
viiwork authenticates nothing. Every API endpoint and every dashboard is open to any client that can reach the server. Reachability *is* the authorization…
Read pageCLIENTS AND APIS
Integrating the mesh API into another application
How to surface a viiwork fleet — models, live jobs, per-GPU load, and the prompt/output history — inside an application you already run, rather than…
Read pageFleet autodiscovery
Point a coding client at any node and the fleet describes itself: which models it serves, and how large a prompt each one will actually take. No model…
Read pageSizing a consumer's concurrency from the fleet
How an application decides how many requests to have in flight against viiwork, using /v1/fleet/capacity instead of a number in its config.
Read pageThinking Models
Some models (e.g. Gemma 4, Qwen3, DeepSeek-R1) produce a reasoning phase before the final answer. The backend (llama-server) may return all output in…
Read pageINTERNALS
Adding an Engine to viiwork
viiwork supervises inference engines. This is how you add one.
Read pageTensor-Split Mode for viiwork — Design Note
Historical. This note records how tensor-split was designed and argued for in April 2026, against viiwork 1.x. The feature shipped and is now ordinary…
Read pageThe viiwork energy store format (VIIWENG1)
This is the on-disk contract for github.com/janit/viiwork/energy. It is specified here rather than left to the Go source because the format has more than…
Read pageReleases
Every v* tag on the public repository gets release archives for linux/amd64, linux/arm64 and darwin/arm64:
Read page