Swarm operations

Experimental

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

Day-to-day commands for managing a running swarm. See Setup to create one. Commands that change membership are coordinator-only.

Inspect

gdc swarm status     # swarm name, this machine's role, member count
gdc swarm members    # the full member list

Remove a member

Drop a machine from the swarm's membership:

gdc swarm kick <agent-id> --reason "decommissioned"

Use gdc swarm members to find the id. Kicking removes the member from the local registry.

Revoke a member

Revoking goes further than kicking: it marks a machine's identity as no longer trusted, so messages signed by it are rejected.

gdc swarm revoke <agent-id> --reason "key compromised"

Reach for revoke when a machine's credentials may be compromised, not just when it's leaving cleanly.

Hand off the coordinator

Transfer coordinator authority to another member. This is irreversible on its own, so it requires explicit confirmation:

gdc swarm transfer-master <agent-id> --yes

After handing off, immediately revoke the previous coordinator's identity from the new coordinator to lock the old credentials out:

# run on the new coordinator
gdc swarm revoke <previous-coordinator-agent-id>

Dissolve the swarm

Disband the swarm entirely:

gdc swarm dissolve --yes --reason "project finished"

This records that the swarm is dissolved and clears the local member list.

Command summary

Command	Coordinator-only	Purpose
gdc swarm status		Show role and member count.
gdc swarm members		List members.
gdc swarm kick <id>	✅	Remove a member.
gdc swarm revoke <id>	✅	Distrust a member's identity.
gdc swarm transfer-master <id>	✅	Hand off coordination.
gdc swarm dissolve	✅	Disband the swarm.

Most commands accept --swarm-id (when a machine hosts more than one swarm) and --root (to point at a specific swarm directory).