Skip to content

Joining a flock

You can ask to join someone else’s Team Flock. You do not create that flock, and you do not get your own provider API key for it. You get a join code after the owner accepts. Paste that code into setup. Your machine becomes a worker.

You need a Flockadoo account with a verified email. Team Flock workers run on Linux with an NVIDIA GPU.

Set how the owner can reach you

The owner sees one contact method on your request. It defaults to your account email.

  1. Open Account Settings.
  2. Stay on Profile.
  3. Under How a flock owner can reach you, add Telegram and Discord if you want.
  4. Choose Preferred contact. Telegram and Discord stay off until that handle is filled in.
  5. Click Save contact.

This is not a second login. Flockadoo still emails your account address.

Ask to join

  1. Open the flock link the owner sent you, or go to Explore → GPU flocks and open a card.
  2. The list is only Team Flocks. It is not My Flocks under Inference (those are flocks you own or already joined).
  3. On the flock page, read the model, OS, engine, GPU on the master, vLLM version, VRAM minimum, open slots (for example 1/2), and the owner’s commission. Every machine uses the OS and engine shown on that page. Matching that GPU is what Flockadoo tests. A different GPU may work, but we have not tested it. See GPUs across nodes.
  4. Click Request invite. The list itself has no invite button.

You and the owner each get an email. The email does not include a join code. On the flock page the button changes to Cancel request.

Cancel request withdraws a pending ask. The owner no longer sees it. You can request again.

You cannot request to join a flock you own.

After the owner decides

Result What you see Email
Still waiting Cancel request “We sent your request…”
Accepted Show join code and Cancel invite on the flock page Tells you to open that flock page. The code is not in the email.
Rejected Request invite again The owner declined.

Show join code displays the code once. Copy it. A second visit does not show it.

Cancel invite withdraws an accepted code that setup has not used yet. You can Request invite again.

If you close the page before you copy the code, ask the owner for a New code. That replaces the old one. The new code shows once for the owner and once for you under Show join code. The old code stops working.

After setup has used the code, this flock shows In this flock. Only the owner can remove you. You can request again after that.

Run setup

On the worker machine:

flockadoo setup

When setup asks Provider API key or join code, paste the join code (join-…). You can paste it with quotes or a label. Setup keeps the join- token.

Setup prints Joining flock and the model name. It does not ask you to pick an engine or a model. It uses the model the owner saved. If vLLM is missing, setup installs it. It then joins the private network. Enter your password when it prints winglink needs root to create winglink0. See How the machines connect.

If the owner has not saved an intended model, setup stops with flock … has no model set. Choose one in the dashboard, then re-run setup.

The code is spent when this machine enrolls, not when the engine is healthy. Setup saves that result on this machine. Running setup again prints This machine is already in the flock. and does not ask for a code.

You need a new code when:

  • Setup never finished saving.
  • The owner removed this machine. The client says the owner removed this machine from the flock. Re-run setup and paste a new join code.
  • Setup says one-shot key was rejected or the one-shot key was already used.

For those last two, pass the new code yourself. A plain re-run will not ask:

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

Ask the owner for New code first. The old code stops working.

Start when the owner says

Setup does not start the engine. It prints the command for your machine and saves it. 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.

Do not run that command until the owner says the master is up. You have 60 minutes from then to join. If you are late, the engines stop and the owner starts the master again.

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. Keep the port the printed command already has. See Team Flock networking.

After the command is running, start the client:

flockadoo

If the engine is not running, the client prints the command again. It does not start the engine for you.

Your engine starting does not mean the flock is live. The owner waits until vLLM on the master prints Application startup complete., /v1/models lists a model, and the next health sync lands. See Wait for the flock to come live.

The long wait you may see during setup (up to 2 hours) is the model download. It is not the 60 minute start window.