Swarm Task Farm Setup

Deploy 5 agents: 1 leader, 3 workers, and 1 monitor.

Roles

Role	Hostname	Skills	Purpose
leader	<prefix>-leader	pilot-leader-election, pilot-formation, pilot-task-router, pilot-broadcast	Elected leader, distributes tasks
worker-N	<prefix>-worker-N	pilot-swarm-join, pilot-map-reduce, pilot-task-retry, pilot-metrics	Executes tasks, retries on failure
monitor	<prefix>-monitor	pilot-task-monitor, pilot-mesh-status, pilot-slack-bridge, pilot-metrics	Tracks swarm health

Setup Procedure

Step 1: Ask the user which role and prefix. For workers, also ask the worker number (1, 2, or 3).

Step 2: Install skills:

# leader:
clawhub install pilot-leader-election pilot-formation pilot-task-router pilot-broadcast
# worker (repeat for each):
clawhub install pilot-swarm-join pilot-map-reduce pilot-task-retry pilot-metrics
# monitor:
clawhub install pilot-task-monitor pilot-mesh-status pilot-slack-bridge pilot-metrics

Step 3: Set hostname and write manifest to ~/.pilot/setups/swarm-task-farm.json.

Step 4: Handshake — workers trust leader + monitor; leader trusts all workers + monitor.

Manifest Templates Per Role

leader

{
  "setup": "swarm-task-farm", "role": "leader", "role_name": "Swarm Leader",
  "hostname": "<prefix>-leader",
  "skills": {
    "pilot-leader-election": "Participate in leader election via consensus.",
    "pilot-formation": "Manage swarm membership.",
    "pilot-task-router": "Partition and distribute tasks to workers.",
    "pilot-broadcast": "Broadcast work units to all workers."
  },
  "data_flows": [
    { "direction": "send", "peer": "<prefix>-worker-1", "port": 1002, "topic": "task-assignment", "description": "Work units" },
    { "direction": "send", "peer": "<prefix>-worker-2", "port": 1002, "topic": "task-assignment", "description": "Work units" },
    { "direction": "send", "peer": "<prefix>-worker-3", "port": 1002, "topic": "task-assignment", "description": "Work units" },
    { "direction": "receive", "peer": "<prefix>-worker-1", "port": 1002, "topic": "task-result", "description": "Completed results" },
    { "direction": "receive", "peer": "<prefix>-worker-2", "port": 1002, "topic": "task-result", "description": "Completed results" },
    { "direction": "receive", "peer": "<prefix>-worker-3", "port": 1002, "topic": "task-result", "description": "Completed results" }
  ],
  "handshakes_needed": ["<prefix>-worker-1", "<prefix>-worker-2", "<prefix>-worker-3", "<prefix>-monitor"]
}

worker-N

{
  "setup": "swarm-task-farm", "role": "worker-N", "role_name": "Compute Worker",
  "hostname": "<prefix>-worker-N",
  "skills": {
    "pilot-swarm-join": "Join the swarm and register with leader.",
    "pilot-map-reduce": "Execute map-reduce work units.",
    "pilot-task-retry": "Retry failed tasks with exponential backoff.",
    "pilot-metrics": "Report CPU, memory, task throughput to monitor."
  },
  "data_flows": [
    { "direction": "receive", "peer": "<prefix>-leader", "port": 1002, "topic": "task-assignment", "description": "Work units" },
    { "direction": "send", "peer": "<prefix>-leader", "port": 1002, "topic": "task-result", "description": "Completed results" },
    { "direction": "send", "peer": "<prefix>-monitor", "port": 1002, "topic": "worker-metrics", "description": "Health metrics" }
  ],
  "handshakes_needed": ["<prefix>-leader", "<prefix>-monitor"]
}

monitor

{
  "setup": "swarm-task-farm", "role": "monitor", "role_name": "Swarm Monitor",
  "hostname": "<prefix>-monitor",
  "skills": {
    "pilot-task-monitor": "Track task completion rates and queue depth.",
    "pilot-mesh-status": "Monitor worker connectivity and latency.",
    "pilot-slack-bridge": "Alert on worker failures or stalled tasks.",
    "pilot-metrics": "Aggregate and display swarm metrics."
  },
  "data_flows": [
    { "direction": "receive", "peer": "<prefix>-worker-1", "port": 1002, "topic": "worker-metrics", "description": "Worker health" },
    { "direction": "receive", "peer": "<prefix>-worker-2", "port": 1002, "topic": "worker-metrics", "description": "Worker health" },
    { "direction": "receive", "peer": "<prefix>-worker-3", "port": 1002, "topic": "worker-metrics", "description": "Worker health" }
  ],
  "handshakes_needed": ["<prefix>-leader", "<prefix>-worker-1", "<prefix>-worker-2", "<prefix>-worker-3"]
}

Data Flows

• leader → worker-* : task assignments (port 1002)
• worker-* → leader : completed results (port 1002)
• worker-* → monitor : health metrics (port 1002)

Workflow Example

# On leader — distribute:
pilotctl --json publish <prefix>-worker-1 task-assignment '{"task_id":"T-001","type":"image_resize","input":"batch-a.zip"}'
# On worker-1 — complete:
pilotctl --json publish <prefix>-leader task-result '{"task_id":"T-001","status":"success","duration_s":34}'
pilotctl --json publish <prefix>-monitor worker-metrics '{"worker":"worker-1","cpu":72,"tasks_done":15}'

Dependencies

Requires pilot-protocol skill, pilotctl binary, clawhub binary, and a running daemon.