Fleet

Distribute agentic work across multiple machines. One primary, multiple workers, connected over Tailscale.

Overview

Fleet lets a single Fawx agent coordinate work across machines on your network. The primary instance receives tasks and routes them to workers based on capability and availability. All communication happens over your Tailscale network with no external servers.

When to use fleet

• Long builds: Route compilation to a beefier machine while your laptop stays responsive.
• Parallel tasks: Run tests on one worker, lint on another, deploy on a third.
• Specialized hardware: Route GPU tasks to a machine with a GPU, or iOS builds to a Mac.
• Always-on agent: Keep a VPS worker running 24/7 while you close your laptop.

Setup

Prerequisites

• Tailscale installed and authenticated on all machines.
• Fawx installed on each machine.
• All machines on the same Tailscale network (tailnet).

Configure the primary

On your main machine, add worker nodes to the config:

[fleet]
role = "primary"

[[fleet.workers]]
name = "vps"
address = "100.x.x.x"

[[fleet.workers]]
name = "mac-mini"
address = "100.x.x.x"

Configure workers

On each worker machine:

[fleet]
role = "worker"
primary = "100.x.x.x"

Start Fawx in worker mode:

fawx serve --fleet-worker

Task routing

When the agent spawns a subtask, the fleet orchestrator decides where to run it based on:

• Capability tags: Workers declare what they can do (e.g. gpu, macos, docker).
• Current load: Tasks prefer idle workers.
• Locality: Tasks that need specific files prefer the machine where those files exist.

Capability tags

[fleet]
role = "worker"
capabilities = ["macos", "xcode", "gpu"]

Node commands

Run commands on remote workers from the primary:

fawx node run mac-mini "cargo build --release"
fawx node run vps "docker compose up -d"

Commands execute over SSH (auto-detected) or the Fawx fleet protocol. Output streams back in real time.

Dashboard

Monitor fleet status through the HTTP API or the native app:

# List workers and their status
curl localhost:8400/v1/fleet/workers

# View active tasks
curl localhost:8400/v1/fleet/tasks

The native app includes a fleet dashboard showing worker status, active tasks, and resource utilization.