Skip to content

Swarm setup

Experimental

Distributed swarm is an advanced, evolving capability; details may change.

This walks through creating a swarm, adding machines, and starting the coordinator and workers. See Overview for the concepts and Operations for day-to-day management.

1. Create the swarm (on the coordinator)

On the machine that will coordinate, initialise a swarm. This generates its identity and keys and makes this machine the coordinator.

gdc swarm init --bind 0.0.0.0:7777
Flag Default Description
--swarm-id <id> random A stable name for the swarm.
--bind <addr> 0.0.0.0:7777 Public address workers will reach. Must be reachable from them.

2. Invite a machine

Create an invite for each machine you want to add. The invite is a URL you pass to that machine.

gdc swarm invite --expires 24h --max-uses 1 --role worker
Flag Default Description
--expires <duration> 24h How long the invite is valid (e.g. 30m, 2d).
--max-uses <n> 1 How many machines may join with it.
--role <role> worker Role(s) the joiner may take. Repeat for several.

The command prints an invite URL. Treat it like a secret — anyone with it (before it expires or is used up) can join.

3. Join (on each worker)

On the joining machine, accept the invite. This creates the machine's own identity and registers it with the coordinator.

gdc swarm join "swarm://...@host:7777?token=..." --role worker

If the coordinator uses a self-signed certificate, pin it so the join connects securely:

gdc swarm join "swarm://..." --role worker --tls-ca /path/to/coordinator-cert.pem
# or set GDC_SWARM_TLS_CA in the environment

→ TLS

4. Start the coordinator and workers

A swarm role is activated when you run the server with --role.

gdc serve --bind 0.0.0.0:7777 --role orchestrator

gdc serve --role worker \
  --orchestrator-endpoint wss://coordinator-host:7777/... \
  --worker-max-concurrent 4

gdc serve --bind 0.0.0.0:7777 --role both
Flag Default Description
--role <role> — orchestrator, worker, or both.
--swarm-id <id> auto Which local swarm to use, if you have more than one.
--orchestrator-endpoint <url> recorded value The coordinator address a worker dials.
--worker-max-concurrent <n> 4 How many tasks a worker runs at once.

Workers can also advertise a review capability with --review-capable and one or more --reviewer-skill values, so the coordinator may pick them to review other work.

Verify

Check the coordinator sees the members you expect:

gdc swarm status
gdc swarm members

Continue to Operations.