Skip to content

Team Flocks

A single-node flock is one machine. You deploy it, install the client, and that machine serves inference.

A Team Flock flock is several machines that serve one model together. You own the flock. Your machine is the master. Other people join as workers with a join code you approve. Flockadoo sends traffic to the master. Workers help that master run the model.

Use Team Flock when one GPU is not enough for the model you want to serve. For example, a large Qwen/Qwen2.5-7B-Instruct build can need more VRAM than one card has. The flock page tells you how many nodes that model needs once you set the model and the VRAM on each node.

Warning

Workers run part of the same workload as your master. Only accept people you trust. A join code lets that person’s machine into the flock.

Team Flock setup runs on Linux with an NVIDIA GPU. A Solo Flock can still be Linux, macOS, or Windows. See Software and hardware requirements.

Master and worker

Master Worker
Who You, the flock owner Someone you accept
What they install with The flock’s provider API key A join code (join-…)
What they run The model Flockadoo dials The same model, as part of that flock
Their own flock This one No. They do not get a separate flock

The master has to be healthy before you can run Test flock on the Nodes tab.

What you set on the flock

Open My Flocks (under Inference), select the flock, and open Nodes.

  • Intended model — the catalog model setup installs. Save it before anyone runs setup. The page treats it as a reminder: it does not stop other models the client might register later.
  • VRAM per node — the minimum VRAM you expect on every machine. The page uses this, with the model, to say how many nodes you need.
  • vLLM version — optional, and 0.30.0 or newer; an older release is refused. Setup installs this release on every Linux machine, with its own Python 3.12 through uv, so machines on different Linux releases can join the same flock. The NVIDIA driver on each machine is the only host requirement. Leave it empty and the master's setup writes the release it installed. Workers then install that release. A machine that already has another release asks before it reinstalls. Workers install the pinned release without that question. A worker that runs setup before the master has reported a release stops and tells you to run the master first. Changing the pin does not reinstall a machine that already finished setup. Run setup again on that machine.
  • Commission — your cut of each payout. See Flock earnings.

Explore → GPU flocks lists Team Flocks as cards. Open a flock to see the model, the GPU on the master, the vLLM version, the VRAM minimum, open slots (for example 1/2), and your commission. People request an invite on that page, not on the list. Share the page link so someone can read the requirements before they ask to join.

GPUs across nodes

Flockadoo tests flocks where every machine has the same GPU model. Mixing GPUs is possible, and you can try it. We have not tested that, and the flock may not start.

Setup on a worker reads this machine with nvidia-smi and compares it to the GPU the master reported. When they differ, setup prints a warning and continues. For example:

This machine has NVIDIA GeForce RTX 5090. The master has NVIDIA GeForce RTX 4090. Mixed GPUs are untested on Flockadoo and the flock may not start.

The master's GPU is sent when the master runs setup, before vLLM starts. Until that setup finishes, the flock page says the GPU is not reported yet, and a worker setup stays quiet. Nodes shows each machine's GPU and the vLLM release it has. A release that does not match the pin, or a GPU that does not match the master, is marked on that row.

How the machines connect

Setup joins each machine to a private network so the nodes can reach each other. The program is winglink. It works like Tailscale and uses WireGuard. Each machine opens the tunnel outbound, so you do not install Tailscale, open firewall ports, or paste a network key. A join code or the master API key is enough. Flockadoo still reaches the master through the outbound connection the client already opens.

On Linux, setup may ask for your password. It prints:

winglink needs root to create winglink0

That creates the network device. Enter the password for sudo. If sudo is not installed, setup stops with winglink needs root to create winglink0, and sudo is not installed.

While it joins, the wizard prints Downloading winglink, Starting winglink, and Joining Winglink. When this machine is on the network, it prints Winglink address: and an address.

A worker does not serve HTTP. Its engine joins the master. Only the master answers /v1/models and takes inference.

On a Team Flock, vLLM must listen on 8000 and llama.cpp must listen on 8081. Do not change --port. Other machines in the flock can reach only those ports. A different port stays on this machine. See Team Flock networking.

The master has to finish setup before workers can be useful. On Nodes, a machine stays Waiting to join until that setup completes. Test flock stays off until the master is healthy.

If the wizard still asks you to pick an engine and a model, it did not see this Team Flock. Look for could not read flock mode and run setup again. Do not start vLLM from that run.

These messages mean this machine is not on the network, and the one-shot network key is gone:

  • winglink is not connected and the one-shot key was already used
  • winglink up: one-shot key was rejected

On the master, run flockadoo setup again. Setup requests a new key.

On a worker, the join code is already spent. Ask the owner for a New code. A later flockadoo setup prints This machine is already in the flock. and does not ask again. Pass the new code yourself:

flockadoo setup --api-key "join-…"

If the owner removed the machine, the client says the owner removed this machine from the flock. Re-run setup and paste a new join code. The next setup asks for the code.

If setup stops with winglinkd did not answer, read ~/.local/state/flockadoo/log/winglinkd.log, then run setup again.

Start the master first

Start the master first. Once it is up, workers have 60 minutes to join. vLLM waits that long for the last worker. Every machine uses the OS and engine shown on the flock page. Do this:

  1. Deploy the flock and save the intended model and VRAM per node on Nodes. That sets how many machines the model needs.
  2. Copy the flock link from Nodes and send it to the people you want. They can also find it under Explore → GPU flocks.
  3. They open that page and click Request invite. You accept on Nodes. They run setup with the join code.
  4. Setup does not start the engine. It prints the command for that machine. The command uses the full path to the engine, so you do not have to activate a virtual environment first. Copy vLLM command on Nodes is different: it starts with vllm. If the shell says vllm: command not found, setup installed it in ~/.venv-vllm. Activate that folder, or replace vllm with ~/.venv-vllm/bin/vllm.
  5. Run the command on the master first. Wait until it is up and waiting for the other machines.
  6. Each worker then runs the command setup printed for them. They have 60 minutes from when the master is up.
  7. Then each person starts the client (flockadoo). If the engine is not running, the client prints the command again. It does not start the engine for you.

If a worker misses that window, the engines stop. Start the master again, then the workers. The 2 hour wait during setup is only the first model download. It is not this 60 minute window.

If vLLM crashes on any machine, stop it on every machine in the flock and start again in that order. See vLLM crashes at startup with "Could not find nvcc".

For example, flockadoo-flock1 needs 4 nodes. You start the master. When it is up, tell the three workers. They join within that hour. The flock is still not live. Wait for the steps below.

Wait for the flock to come live

Workers joining does not make the flock ready. vLLM still loads the model across every machine. That can take a while after the last worker connects. Test flock on Nodes stays off until the master is healthy.

On the master, watch the vLLM log. Loading is finished when you see:

INFO:     Application startup complete.

Then check the vLLM models API on the master. vLLM must be on 8000. llama.cpp must be on 8081. Do not change --port. It has to list at least one model:

curl http://127.0.0.1:8000/v1/models

An empty list is not ready. vLLM can answer that URL while weights are still loading.

Keep flockadoo running on each machine. The client status shows (awaiting health sync) until the next health report. That report runs about every 3 minutes. After it, the model name replaces that line and the flock can take traffic. See Health monitoring.

Read status on the machine

Open http://localhost:8080/ or look at the terminal where flockadoo is running. FLOCK STATUS shows:

Label What it means
Flock master, worker, or single
Engine Terminal only. Master: not started, waiting for workers (0/3), loading, or ready. Worker: running or not started.
Nodes This machine plus other machines that are online, out of the flock size. For example, 1/4 means only this machine is on the network.
Winglink IP This machine's address on the private network.
Peers How many other machines are online. For example, 3 online.

Nodes includes this machine. waiting for workers counts the other machines only. For example, a 4-node flock with only the master up shows Nodes 1/4 and Engine waiting for workers (0/3). The client also prints Waiting for workers to join (0/3).

Starting the client before vLLM prints the saved command and Start it in another terminal. This client keeps running. When the worker engine is up, the client prints Worker is running. It joins the master and does not serve HTTP. On the master, once vLLM is serving, it prints vLLM is ready at the local URL.

The next client start reconnects winglink when that address is offline.