Running work on a swarm¶
Once a swarm is set up and the coordinator and workers are running, you give it work by submitting a goal. The coordinator plans the goal into subtasks, runs them across the workers, and returns a combined result. You can do this from the command line or the terminal app.
Topology
Submitting goals is designed for a dedicated coordinator
(gdc serve --role orchestrator) with separately-joined workers. A
single-host --role both node is fine for trying out setup and
membership, but not for submitting goals — its built-in worker
conflicts with the submitting connection.
Submit a goal¶
The coordinator accepts the goal and prints a workflow id. Behind the scenes it plans the goal into subtasks, dispatches them to workers, and combines their outputs.
To wait for the result inline, add --wait:
gdc swarm submit "..." --wait # block until done, print the result
gdc swarm submit "..." --wait --wait-timeout 600 # allow up to 600s (default 300)
Without --wait the command returns immediately with the id, and you
fetch the result later.
Check on a workflow¶
gdc swarm result <workflow-id> # current state; the combined result once finished
gdc swarm tasks # every subtask the coordinator is tracking
gdc swarm tasks --workflow-id <id> # just this workflow's subtasks
result prints the workflow's state (for example, running or completed)
and, once it finishes, the aggregated result. tasks shows the individual
subtasks and which worker each ran on.
How the work flows¶
Understanding what the coordinator does helps you write good goals and read the results:
- Planning. The goal is broken into a set of subtasks with dependencies between them.
- Data flow. When a subtask depends on earlier ones, those earlier results are fed into it as context, so a "step 2 uses the output of step 1" pipeline works automatically. Each piece of upstream context is size-limited, so very large outputs are truncated.
- Further breakdown. A worker running a subtask can break it down further and hand the pieces back to the coordinator.
- Retries. A subtask that fails for a temporary reason (a busy or briefly unreachable worker, a timeout) is automatically retried a few times. Failures that look permanent are not retried.
- Combining. When the subtasks finish, the coordinator combines their
outputs into one final result, which you retrieve with
--wait,gdc swarm result, or the terminal app.
The result is returned to you, not written to a fixed file.
From the terminal app¶
The interactive app has a built-in swarm screen. Open it with:
It shows three things:
- a status strip — the swarm, your connection, and the members;
- a tasks table — each subtask, its state (colour-coded), and the worker running it;
- a goal box and, after you submit, a workflow panel with the live state and final result.
Keys in this screen:
| Key | Action |
|---|---|
| Enter | Submit the typed goal. |
| r | Refresh the task list (when the goal box is empty). |
| w | Poll the active workflow for its latest state and result. |
| Esc | Leave the swarm screen. |
After you submit, the workflow panel appears and updates on its own every second or so; press w to force an immediate refresh.
Read-and-submit
The swarm screen lets you submit goals and watch progress. Managing members (inviting, removing, revoking) is done from the command line.
Giving the model to workers¶
Each worker needs a model to run its subtasks. A worker doesn't need a
[provider] block in its config — you can pass the model details when you
start it:
gdc serve --role worker \
--base-url http://localhost:11434/v1 \
--model qwen2.5-coder:14b-instruct \
--orchestrator-endpoint wss://coordinator-host:7777/...
Bounding what a worker can reach¶
You can restrict which outside domains a worker may contact while running a task, and which of its local profiles it offers to the swarm: