# Helping someone install viiwork

This is the plain-text companion to https://viiwork.pulu.app/install/ for an AI assistant that is guiding a person through installing a viiwork node. It describes viiwork v2.11.1. The sources for that release are the setup page (https://viiwork.pulu.app/docs/setup/), the mesh page (https://viiwork.pulu.app/docs/mesh/), the releases page (https://viiwork.pulu.app/docs/releases/) and the security page (https://viiwork.pulu.app/docs/security/). Check https://github.com/janit/viiwork/releases for a newer release before giving commands that name a version; a newer release has its own documentation in the repository at its tag.

## Ask first

1. Which hardware path applies: NVIDIA on Linux, Radeon VII, MI50 or MI60 on Linux (gfx906), or an Apple Silicon Mac? Which archive matches the CPU: linux_amd64, linux_arm64 or darwin_arm64?
2. Are the GGUF model files already in one directory? The wizard does not download models.
3. On Linux: do Docker Engine and the Compose v2 plugin work (`docker compose version`)? On NVIDIA, does `nvidia-smi` work and is the NVIDIA Container Toolkit installed? On gfx906, does `/dev/kfd` exist?
4. On a Mac: is the person at the Mac, logged in, using Terminal? The wizard refuses an SSH session with nobody logged in.
5. Is this the first node, or is it joining an existing mesh? Are the machines on the same Tailscale tailnet or the same LAN?
6. Are ports 8086/tcp and 7946/tcp+udp free on the machine and open between the machines?

## Install sequence

1. Download and check the release. Set os to the archive that matches the machine:

       v=v2.11.1
       os=linux_amd64
       base=https://github.com/janit/viiwork/releases/download/$v
       curl -fLO "$base/viiwork_${v}_${os}.tar.gz" -fLO "$base/SHA256SUMS"
       sha256sum --check --ignore-missing SHA256SUMS      # Mac: shasum -a 256 --check --ignore-missing SHA256SUMS
       tar xzf "viiwork_${v}_${os}.tar.gz" && cd "viiwork_${v}_${os}"

   Continue only if the archive's line ends in OK. Verifying the signature as well is described at https://viiwork.pulu.app/docs/releases/#checking-a-download-by-hand.

2. Run the wizard: `sudo ./viiwork init` on Linux, `./viiwork init` on a Mac (no sudo). It asks for the models directory, the model names, the GPU layout, the mesh (join with a code, new secured mesh, or open mesh), mesh-wide updates and the node name, then shows every file before writing. Let the person read the proposed layout and files before they accept. Model names should match the names other machines in the mesh use for the same model.

3. On NVIDIA and on a Mac the wizard starts the node and runs its checks. On Radeon VII, MI50 or MI60 it writes /etc/viiwork and stops. Then build and start the image from the same release:

       git clone https://github.com/janit/viiwork && cd viiwork && git checkout v2.11.1
       make docker
       sudo cp configs/docker-compose.v2.example.yaml /etc/viiwork/docker-compose.yaml
       sudo sed -i 's#- /models:/models:ro#- /path/to/models:/models:ro#' /etc/viiwork/docker-compose.yaml
       sudo docker compose -f /etc/viiwork/docker-compose.yaml -p viiwork up -d

   /path/to/models must be replaced with the real models directory first. Use this path only for gfx906 cards; no image is verified for other AMD cards.

4. Check the node: `curl http://localhost:8086/v1/models`, then a chat completion with a model name from that list. The node's dashboard is http://localhost:8086/ and the mesh dashboard http://localhost:8086/mesh. `viiwork top` shows the mesh in a terminal; on a Mac, ~/.local/bin must be on PATH first.

5. To add a machine, print a join code on an existing node of a secured mesh:

       sudo sh -c 'set -a; . /etc/viiwork/mesh.env; /usr/local/bin/viiwork join-code'   # Linux
       ~/.local/bin/viiwork join-code                                                    # Mac

   The person pastes it into the new machine's wizard at the mesh question. The join code is the mesh secret. Never ask for its value, and never ask for the contents of mesh.env; ask only whether the wizard accepted the code. In an open mesh, `viiwork join-code --open` prints a code without a secret.

## When something fails

Read the actual error before changing anything. Logs: `sudo docker logs viiwork` on Linux, `tail -f ~/Library/Logs/viiwork/viiwork.log` on a Mac. The usual cause is a model that does not fit at its context; the fix is a lower `context` or more `gpus` in the config. After editing the config, reload with `sudo docker kill -s HUP viiwork` (Linux) or `launchctl kill HUP gui/$(id -u)/fi.viiwork.node` (Mac). More causes: https://viiwork.pulu.app/docs/setup/#when-the-node-does-not-come-up

## Working style

Give one step at a time and wait for the result. Say what a command will change before it writes files or starts services. Do not assume a version, a GPU, a model path or an image. viiwork authenticates nothing on its API, so never suggest exposing a node to an untrusted network; keep it on a tailnet or behind a firewall or reverse proxy.