Give the Hub a Goal

Orchestrate work by stating the outcome: nfltr orch "<goal>" starts a Claude hub on your terminal that spawns agents on the machines joined to your hosted nfltr.xyz account and reports back.

This guide assumes the Getting Started setup: an API key saved or in NFLTR_API_KEY, and at least one node joined. The hub is Claude; the goal is the whole prompt, and nfltr adds no policy of its own.

Check readiness

nfltr orch doctor checks that claude is installed and authenticated, which relay the CLI resolves, and that at least one node or worker is connected.

$ nfltr orch doctor

One goal, one command

With a goal, the hub runs non-interactively: it spawns agents, waits for their completions, and prints the final answer on stdout. Quote the goal; flags and goal may come in any order.

$ nfltr orch "fix the flaky cache test in github.com/your-org/app and push a branch with the fix"

While it runs, each hub action prints one progress line on stderr (for example hub → spawn_agent machine=<m>: "…", hub → wait_for_agents), and each agent completion is announced. The session stays open while agents run, so a hub that has spawned work never abandons it. At the end one line reports the hub's own spend and the tokens and USD its agents reported.

An interactive hub

With no goal (in a terminal), you get an interactive Claude session with the hub tools. Talk to it while agents run: ask what is running, change an agent's course, stop one. Agent completions wake the session by themselves.

$ nfltr orch

Budgets and models

Nothing is capped or chosen for you. Caps cover every agent of the hub; once passed, running turns are stopped (budget_exceeded) and new spawns and messages are refused. A USD cap needs a token cap too, because a stopped turn's cost is not always reported.

$ nfltr orch --hub-max-tokens 2000000 --hub-max-usd 5 \
    --hub-agent-model <model> --hub-model <model> \
    "review every package under internal/ for goroutine leaks and report the findings"

--hub-agent-model: the model of every agent whose spawn names none, on nodes whose harness offers it (elsewhere, and unset, the node's harness decides; a spawn's own model wins).
--hub-model: the hub session's own model.
The hub can also give one agent its own budget when it spawns it; see Hub tools.

Hub ids and reattach

Each project directory has its own hub id, so running nfltr orch again in the same directory reattaches that hub. Agents keep running when the hub exits (Ctrl-C, closed terminal, a crash); the reattached hub receives every completion it missed, exactly once. Name the id when you run from elsewhere, or use a fresh one for an unrelated goal (earlier agents of the same id count as pending):

$ nfltr orch --hub-id release-check "check that the release branch builds on every node"

Only one live process may hold a hub id; a second one fails naming the holder's pid.

Zero setup on one machine

With no account or relay configured at all, nfltr orch runs a local hub: it starts a relay on this machine's loopback and a local node, then the hub session. Its first line says zero-setup local hub. --max-agents sizes the local node when it must be started. The local node needs the Claude token in the environment like any node (CLAUDE_CODE_OAUTH_TOKEN from claude setup-token, or ANTHROPIC_API_KEY); tools stay off unless you pass --allow-all-tools.

$ nfltr orch --max-agents 2 --allow-all-tools "add a CHANGELOG entry for the last three commits"

Stop the local node with nfltr orch nodes stop. To use nodes on other machines, save your nfltr.xyz key (nfltr config add-api-key) and the same command uses the hosted relay.

What you get back

The final answer is the hub's summary of its agents' results: their text, plus the branch and commit of any agent that changed a repository. The hub can continue a finished agent in the same session (send_message) or spawn the next step. To look at one agent's task directly:

$ nfltr orch task list --active
$ nfltr orch task result --task TASK_ID

Next: Many agents across machines.