Use nfltr from Claude Code

Orchestrate agents on the machines joined to your hosted nfltr.xyz account from your own interactive Claude Code session: your session becomes the hub, with the same spawn, message, stop and wait tools that nfltr orch uses.

Prerequisites are the same as in Getting Started: a saved API key (or NFLTR_API_KEY) on this machine, and at least one machine joined as a node.

The two commands

$ nfltr config add-api-key rpc_your_key_here     # once per machine
$ nfltr node join --max-agents 2 --allow-all-tools  # on every machine that runs agents

Then, in your project:

$ cd ~/src/my-project
$ claude mcp add nfltr -- nfltr mcp --toolset hub
$ nfltr orch hub install-hook    # optional: agent completions wake the session
$ claude

Ask for work in plain words ("fix these three issues in parallel on the laptop and the build server, one branch each"). The session reads its hub tools from the server's instructions, spawns agents on your nodes, and reports their results. Tool inputs and results are in the Hub tools reference.

What the server resolves by itself

• Relay and key: from NFLTR_SERVER / NFLTR_API_KEY in the environment, else the saved account (nfltr.xyz by default). The key is never in argv or in the MCP config.
• Hub id: one per project directory. Reopening the project reattaches its hub, and the session receives every completion it missed while closed; two projects never share one.
• A second session in the same project fails closed on the hub lock (naming the holder's pid). Give it its own id: claude mcp add nfltr-review -- nfltr mcp --toolset hub --hub-id review.
• Nothing else is defaulted. Add --hub-agent-model <model>, --hub-max-tokens N or --hub-max-usd X (needs a token cap) to the nfltr mcp command if you want them.

Permissions

Claude Code asks before each hub tool call. Allow them all with /permissions (add mcp__nfltr) or start with claude --allowedTools mcp__nfltr. These permissions are for your session's calls to the hub; what agents may do on a machine is set by that node's --allow-all-tools.

Receiving completions

• Without the hook: the session calls wait_for_agents, which blocks until a completion lands and returns it (exactly once, across restarts).
• With the hook: nfltr orch hub install-hook adds a Stop hook to .claude/settings.local.json (this machine only; --print shows it instead). After a turn that leaves agents running, it waits in the background and wakes the session with nfltr orch: agent completion(s) arrived when one completes. If you named a --hub-id on the server, pass the same one to install-hook.

$ nfltr orch hub install-hook --print

Steer and stop

Say it in the session: "tell the agent on the VM to skip the archived rows", "stop the parser agent", "ask the finished agent to add a test". The session calls send_message or stop_agent. From another terminal you can watch the same agents read-only; see Many agents across machines.

$ nfltr orch task list --active

No account: one machine

Without an account, this runs a local hub on this machine only: it starts a loopback relay and a local node, and serves the same tools.

$ claude mcp add nfltr -- nfltr orch hub --max-agents 2

Stop the local node with nfltr orch nodes stop. Save a key later to use nodes on other machines.

See it run

Two of the homepage demos are plain Claude Code sessions with exactly this setup: a backlog fixed by three agents across two machines, and an alert investigated and fixed on a remote VM.