A machine becomes a viiwork node through viiwork init, the setup wizard. It finds the hardware and the model files, proposes a layout, and shows every file it will write before it changes anything. This post walks through a run of the wizard in viiwork v2.11.0; the install guide has the commands.
What the machine needs
The wizard supports three kinds of machine: Linux with Radeon VII, MI50 or MI60 cards (gfx906), Linux with NVIDIA cards, and Apple Silicon Macs. Other AMD cards are found too, but no image is verified for them yet, so on those the wizard writes the config only. On Linux the engine runs in Docker; on a Mac it runs natively under a LaunchAgent. Every machine needs GGUF model files in one directory, because the wizard downloads nothing, and ports 8086 and 7946 open between the machines of the mesh.
The wizard proposes a layout
After its preflight checks, the wizard lists the GPUs and asks for your models directory. It shows each model it finds with its architecture and size, and asks which ones to serve and under what name. Use the same name on every machine, so a request for it can run on any of them.
It then proposes which cards each model gets, the context per slot and the number of slots. You can accept the proposal, edit one model's line or drop a model, and a layout the node would refuse is shown together with the reason. On a Mac the plan is made against the memory that Metal can use, since the GPU shares it with everything else on the machine.
Joining or starting a mesh
Next the wizard looks for nodes nearby, on your tailnet and on the LAN, and offers three choices: join an existing mesh with a join code, start a new secured mesh, or start an open mesh without a secret. A join code carries the address of a node already in the mesh and the mesh secret, so the new machine must be able to reach that node, and the code has to be kept as private as the secret itself.
Before writing, the wizard shows every file with its content and the secret masked. On a yes it writes them, starts the node (on NVIDIA and on a Mac) and waits until every model has loaded, then runs its acceptance checks. On a gfx906 machine it stops after writing the configuration, because there is no published image for those cards; you build the image from the same release and start it with the example compose file.
Checking that it serves
Once the node runs, ask it what the mesh serves:
curl http://localhost:8086/v1/models
The dashboard on port 8086 shows the node, /mesh shows the whole mesh, and viiwork top shows the same in a terminal. When another machine joins, its models appear in that list on every node.
The setup page lists every file the wizard writes and covers updating and uninstalling.