Many Agents Across Machines

Multi-agent orchestration on hosted nfltr.xyz: one hub runs many agents in parallel on the machines you joined, routes each to the machine that has what it needs, and lets you watch, steer, continue and stop them.

How the hub picks a machine

The hub reads the joined nodes (list_nodes) and the connected agents (list_worker_peers) before it spawns. Each node advertises its machine id, what you wrote in --machine-description, its --machine-resources tokens, the repositories it may clone and its free agent slots. The hub then names a machine or labels on the spawn; nfltr only enforces the filter and places the agent on a free slot. So describe what is only on each machine:

$ nfltr node join --max-agents 2 --allow-all-tools \
    --machine-description "staging VM: runs the thermo-exporter service, has /data/readings.csv" \
    --machine-resources dataset.readings,service.thermo-exporter

A goal can then say "on the machine with the readings" and the hub finds it. To see what the hub sees:

$ nfltr orch nodes list

Parallel work

Ask for independent pieces in one goal; the hub spawns them at once, across machines, up to the free slots of each node. When every slot is busy a spawn waits for one to free rather than failing.

$ nfltr orch --hub-max-tokens 4000000 --hub-max-usd 5 \
    "In github.com/your-org/app, fix these three issues in parallel, one agent each, one branch each: #12, #15, #19"

Each agent that changes a repository returns its branch and commit; the hub reports them together.

Watch from any terminal

Every agent turn is a task on the relay, so you can watch from a second terminal or another machine with the same account:

$ nfltr orch task list --active
$ nfltr orch task watch --task TASK_ID
$ nfltr orch task status --task TASK_ID --events 10
$ nfltr orch task result --task TASK_ID

For a hub agent's task, task status shows a Hub: line instead of recovery advice: the hub that spawned the agent owns it and receives its outcome, and decides what follows. On the hub's machine, nfltr orch hub runs and nfltr orch hub show show the same agents and their turns, running or stopped.

Steer, continue, stop: through the hub

You talk to the hub; the hub talks to its agents. In an interactive nfltr orch (or your own Claude Code session), just say what you want:

• Steer a running agent ("tell the agent on the VM to skip the archived rows"): the hub calls send_message and the message reaches the live session between its tool calls.
• Continue a finished or stopped agent ("ask it to also add a test"): send_message starts a new turn in the same session and workspace, on the same machine.
• Stop an agent ("stop the parser agent"): stop_agent. Its uncommitted edits come back as a recovery patch the hub can hand to another agent.

nfltr orch task steer and task cancel do not apply to hub agents: the relay does not own them, so it answers 404 with a hint to go through the hub. Those commands are for tasks dispatched directly over the REST API.

When a machine goes away

If a node dies mid-job, its agents complete as node_lost. The hub sees that like any other completion and can re-issue the work; a spawn that names the machine waits (up to its timeout_ms) for the machine to rejoin, then runs there. See Troubleshooting.

Related: Hub tools reference · Join machines as nodes · Demos (one goal on two machines, a parallel backlog, a node killed mid-job).