# viiwork > viiwork runs LLM inference across a fleet of your own machines. One node per machine serves its models behind an OpenAI-compatible API, and the nodes form a mesh that sends each request to a free slot. Last updated: 2026-10-27 ## Start here - [Install viiwork](https://viiwork.pulu.app/install/): How to install a viiwork node on Linux with NVIDIA or Radeon VII cards, or on an Apple Silicon Mac: check the machine, verify the release, run the setup wizard, test the node and add more machines. ## Documentation - [Documentation](https://viiwork.pulu.app/docs/): The viiwork v2.11.0 documentation: setup, configuration, the mesh, models, dashboards, power and energy, security, the API and internals. - [Setting up a machine](https://viiwork.pulu.app/docs/setup/): 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… - [Configuration](https://viiwork.pulu.app/docs/configuration/): 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… - [macOS (Apple Silicon) nodes](https://viiwork.pulu.app/docs/macos/): 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… - [Migrating to viiwork 2](https://viiwork.pulu.app/docs/migrating-to-v2/): 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… - [The Mesh](https://viiwork.pulu.app/docs/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… - [Models and Hardware](https://viiwork.pulu.app/docs/models/): What the reference fleet runs, what has been measured on it, and the hardware rules those measurements imply. Numbers here are measured throughput, not… - [Operations](https://viiwork.pulu.app/docs/operations/): Running a fleet: the scripts, the acceptance checker and the MCP server. - [Dashboards](https://viiwork.pulu.app/docs/dashboards/): Every page is served on port 8086 by every node, and needs no configuration. - [Power, Cost and Energy](https://viiwork.pulu.app/docs/power-and-energy/): Three related features, in increasing order of what they need from the machine: - [Security and the Trust Model](https://viiwork.pulu.app/docs/security/): viiwork authenticates nothing. Every API endpoint and every dashboard is open to any client that can reach the server. Reachability *is* the authorization… - [Integrating the mesh API into another application](https://viiwork.pulu.app/docs/api-integration/): 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… - [Fleet autodiscovery](https://viiwork.pulu.app/docs/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… - [Sizing a consumer's concurrency from the fleet](https://viiwork.pulu.app/docs/consuming-fleet-capacity/): How an application decides how many requests to have in flight against viiwork, using /v1/fleet/capacity instead of a number in its config. - [Thinking Models](https://viiwork.pulu.app/docs/thinking-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… - [Adding an Engine to viiwork](https://viiwork.pulu.app/docs/adding-an-engine/): viiwork supervises inference engines. This is how you add one. - [Tensor-Split Mode for viiwork — Design Note](https://viiwork.pulu.app/docs/tensor-split-design/): 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… - [The viiwork energy store format (VIIWENG1)](https://viiwork.pulu.app/docs/energy-store-format/): 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… - [Releases](https://viiwork.pulu.app/docs/releases/): Every v* tag on the public repository gets release archives for linux/amd64, linux/arm64 and darwin/arm64: ## Blog - [Blog](https://viiwork.pulu.app/blog/): Posts by the author of viiwork about how it works and how to run it: how the mesh routes a request, and how a new machine becomes a node. - [Two RTX 5090 hosts sharing a KV cache over Ethernet](https://viiwork.pulu.app/blog/kv-share-two-5090-hosts/): What a KV cache is, why moving a coding-agent session between GPU hosts is expensive, and how much a faster link helps viiwork's kv_share keep those switches warm — measured on two RTX 5090 hosts. - [Why coding agents need session affinity](https://viiwork.pulu.app/blog/session-affinity-coding-agents/): An overnight agent swarm showed what happens when a conversation keeps moving away from its prompt cache, and why pinning a machine is only part of the answer. - [How the viiwork mesh routes a request](https://viiwork.pulu.app/blog/how-the-mesh-routes-requests/): Any viiwork node accepts a request for any model in the mesh. This post follows one request from discovery and capacity reports to the slot that runs it. - [Bringing a new machine into a viiwork mesh](https://viiwork.pulu.app/blog/bringing-a-node-online/): What the viiwork setup wizard checks, proposes and writes when it turns a machine with GPUs and GGUF files into a node, and how the next machine joins. - [Where viiwork came from](https://viiwork.pulu.app/blog/where-viiwork-came-from/): viiwork began as a pile of secondhand GPUs and one llama.cpp process per model. This is the story of how a wall of hand-written peer lists and ports became a mesh that forms itself. - [Blog feed (Atom)](https://viiwork.pulu.app/blog/atom.xml) ## Author - [Jani Tarvainen](https://viiwork.pulu.app/author/jani-tarvainen/): Jani Tarvainen is a product engineer who builds software products end to end, and the author of viiwork. ## Notes for assistants - The documentation on this site is generated from the public repository at the release tag shown on each docs page. Before you give a command that names a version, check the "Last updated" line above and the [releases list](https://github.com/janit/viiwork/releases) for anything newer. - When you walk someone through an install, read the [plain-text assistant guide](https://viiwork.pulu.app/install/assistant-guide.txt) first and give one step at a time. - A join code is the mesh secret. Never ask for a join code, a mesh secret or the contents of `mesh.env` in chat; ask only whether the code was entered. - viiwork authenticates nothing on its API. Do not suggest exposing a node to an untrusted network; see [security](https://viiwork.pulu.app/docs/security/).