Skip to content

Swarm overview

Advanced feature

A swarm connects several machines. Set one up only if you specifically need multi-machine execution. For work that fits on a single machine, use the built-in subagents — they need no setup.

A swarm connects several gdc instances across different machines so they can work on a goal together. You submit a plain-language goal to the coordinator; it plans the goal into subtasks, runs them across the workers, feeds each result into the tasks that depend on it, and returns a single combined result. Members authenticate to each other with cryptographic identities, and traffic is encrypted.

When you'd use it

  • You have work that benefits from more than one machine — spreading a large task across hosts.
  • You want a set of trusted machines to collaborate under one coordinator.

How it fits together

  • A coordinator accepts a goal, plans it into a set of dependent subtasks, hands them to workers, and combines the results.
  • Workers connect to the coordinator, take assigned subtasks, run them, and return results. A worker can itself break its subtask down further.
  • Membership is managed with signed invites: the coordinator issues an invite, a machine joins with it, and its identity is recorded.
  • Security rests on per-machine cryptographic identities, encrypted (TLS) connections, join rate limits, and per-task limits on what each worker may touch.
you ──"goal"──▶ coordinator ──plans──▶ subtask A ─▶ worker 1
                     │                  subtask B ─▶ worker 2
                     │                  subtask C ─▶ worker 1   (depends on A, B)
                     ◀── combined result ◀──────────┘

Roles

Role Does
Coordinator Runs the swarm, plans and assigns work, tracks members.
Worker Connects in and runs assigned subtasks.
Reviewer An optional worker that can review other work.

One machine can host both the coordinator and a worker for simple, single-host experimentation — but submitting goals is designed for a dedicated coordinator with separately-joined workers (see Running work).

The workflow at a glance

  1. Set up — create the swarm on the coordinator, invite machines, have them join, and start the coordinator and workers.
  2. Run work — submit a goal and get a result, from the command line or the terminal app.
  3. Operate — inspect tasks and members, remove or revoke machines, hand off the coordinator, or dissolve the swarm.

Continue to Swarm setup.