Skip to content
fleetd docs

Quick start

You’ll install fleetd, open a project in the desktop app, and tell its lead what you want.

Before you start, have these on the machine:

  • macOS or Linux x64.
  • The claude CLI on the machines that run agents. Its Claude account can be the hub’s API key, your subscription, or each machine’s own login; the setup steps below set it.
  • git. GitHub goes through the hub’s own GitHub App, set up in the steps below, or the gh CLI logged in on the hub.
  • A GitHub repo to work on. fleetd branches from its default branch and merges back into it; see Which branch fleetd works on.

  1. Install and run the setup wizard.

    Run this on the always-on machine that will be your hub, the machine that coordinates all the work:

    curl -fsSL https://fleetd.sh | sh

    The installer starts the wizard, fleetd init. Press Enter to take the default at each question. It walks through six parts:

    Part What it sets up
    1. This machine Makes this machine the hub and picks where it listens: your tailnet, your LAN, or this machine only.
    2. Logins Checks claude and gh, and picks the commit author for your agents.
    3. Hub Runs the hub as a background service.
    4. Workers Picks the workers: the machines that run agents. This machine can be one.
    5. Project Adds your first project: a git repo on a worker.
    6. App & setup Prints a pairing code for the desktop app, then lists the hub’s setup steps and runs fleetd doctor.

    Expected output ends like this:

    ◇  fleetd is ready ─────────────────────────────────────╮
    │                                                       │
    │  hub       http://hub.your-tailnet.ts.net:4790        │
    │  workers   homeserver                                 │
    │  project   ~/src/hello on homeserver                  │
    │  app       code K4QW-7RNP                             │
    │  PATH      add: export PATH="$HOME/.local/bin:$PATH"  │
    ├───────────────────────────────────────────────────────╯

    Note the pairing code it prints, such as K4QW-7RNP. A line starting with ✗ ends with the command that fixes it. Run fleetd init again at any time: it keeps what works and repairs the rest.

  2. Open the desktop app.

    On the hub machine, open the app: it pairs with the hub by itself.

    On another computer, install fleetd without the wizard, then open the app:

    curl -fsSL https://fleetd.sh | sh -s -- --no-init

    On macOS, open ~/Applications/fleetd.app. On Linux, open fleetd from your app menu. Enter the hub address and the pairing code from step 1. A code works once, for 15 minutes; run fleetd pair on the hub for a new one.

  3. Open your project.

    The sidebar lists your projects. Click the one the wizard added. It opens the chat with that project’s lead: the Claude session that plans the work and runs the agents. Each project has one.

  4. Tell the lead what you want.

    Type a message and press Enter:

    fix the typo in the README

    The lead answers in the chat and starts agents. A strip under its message shows who is working; pull requests and merges show up as one-line events.

  5. Reply when it asks.

    The lead asks only about product calls, money and irreversible steps, as numbered items with a recommendation each. A project with a question waiting shows a dot in the sidebar. Reply in plain words, or tersely:

    1 go, 2 rec

  6. Watch it land.

    Each pull request goes through review, then the merge train merges it once CI passes. The lead says in the chat when the work is done and checked.

Setup steps

Section titled “Setup steps”

Everything a hub admin sets up is one list of steps, the same in the terminal and the app. fleetd init lists them at its end, fleetd doctor lists them first, and fleetd init --step <id> opens one: why it matters, the values to paste (computed for your hub), the pages to open, then Test or Later. In the app, an admin’s first run opens on them, and Settings › Hub › Setup has them at any time. Each step’s status comes from the hub’s checks, so you can stop at any point and pick up again later, from any of them.

Step Id Needed
Where the hub listens address Required. Plain HTTP is fine on your tailnet.
Machines that run agents machines Required.
Claude claude Required. The hub’s API key on Settings › Hub accounts › Claude, your subscription in Settings › Your accounts › Claude, or each machine’s own claude auth login.
GitHub github Before the first PR: the hub’s GitHub App, made with one button on Settings › Hub accounts › GitHub, then each person connects theirs in Settings › Your accounts › GitHub; or gh auth login on the hub.
Invite people people Optional. Done once someone you invited has joined.
Google google Optional. The client is saved on Settings › Hub accounts › Google; see Google.
Notion notion Optional. Each person connects their own, on their Navi.

Optional steps never block anything; Later keeps a step in the list. Secrets are never typed in the terminal: a step that takes one names the page in the app that seals it on your device.

Without the app

Section titled “Without the app”

On a machine with no display, chat with the lead from a script:

  1. On the hub, create a key and keep it in a file only you can read:

    (umask 077; fleetd hub key create --human --name terminal > ~/.fleetd/human.key)

  2. Save the script from MCP clients as ~/mcp.sh, and find your project’s ids:

    fleetd project list

  3. Write to the lead, with the ids from project list (<machineId>/<projectId>):

    FLEETD_HUB=http://hub.your-tailnet.ts.net:4790 FLEETD_KEY_FILE=~/.fleetd/human.key sh ~/mcp.sh chat_send \
      '{"projectRef":{"machineId":"homeserver","projectId":"<id>"},"text":"fix the typo in the README","clientRequestId":"first"}'

  4. Read its replies:

    FLEETD_HUB=http://hub.your-tailnet.ts.net:4790 FLEETD_KEY_FILE=~/.fleetd/human.key sh ~/mcp.sh chat_history \
      '{"projectRef":{"machineId":"homeserver","projectId":"<id>"}}'

fleetd status shows where the project’s work is. Secrets need the app.

Next steps

Section titled “Next steps”