Join Machines as Nodes

Orchestration runs agents on your machines. A machine joins your hosted nfltr.xyz account once, as a node; the node starts Claude Code agents on demand when a hub spawns work there, and stops them when the work ends.

Join a machine

Run this on the machine, with NFLTR_API_KEY in the environment or a key saved with nfltr config add-api-key (never on the command line), and the Claude token in the environment (see Credentials):

$ nfltr node join --max-agents 4 --allow-all-tools \
    --workspace ~/src/app \
    --allow-repo 'github.com/your-org/*' \
    --machine-description "GPU box on the corp VPN; has the eval dataset in /data" \
    --machine-resources gpu.a100,vpn.corp,dataset.eval

Leave it running (a service manager, tmux or screen). --max-agents is required: the most agent processes this node runs at once, a number or cores.

Or join one over SSH

From your terminal, nfltr orch nodes add ssh starts a node on a remote host over ssh; it copies this nfltr binary when the remote OS and architecture match (or use --remote-bin). Node flags go after --.

$ nfltr orch nodes add ssh --max-agents 2 user@build-host -- --workspace /srv/app --allow-all-tools
$ nfltr orch nodes list
$ nfltr orch nodes stop

nodes list shows every node, its bound and its running agents. nodes stop stops the local node the zero-setup hub started on this machine; stop a joined node by ending its nfltr node join process. --ssh-command "ssh -p 2222" passes ssh options; --wait bounds how long to wait for the node to join.

`nfltr node join` flags

Flag	Meaning
`--max-agents N\|cores`	Required. Most agent processes at once.
`--allow-all-tools`	Let agents run commands without approval (shell, tests, git push, files outside the task checkout). Off: agents only edit files.
`--workspace DIR`	The checkout agents work in (default: the current directory).
`--allow-repo GLOB`	Repositories agents may clone when a spawn names one that is not the workspace checkout; repeatable. None: never clone.
`--machine-description TEXT`	What this machine gives access to (hosts, VPNs, GPUs, datasets). The hub reads it.
`--machine-resources a,b`	Resource tokens, e.g. `gpu.a100,vpn.corp`.
`--labels k=v,…`	Labels the launched agents carry; spawns can require them.
`--harness claude-code\|codex`	Offer only this harness (repeatable). Default: every harness CLI found on PATH, and spawns then name one.
`--agent-linger D`	Keep an agent process after its task so a continuation reuses it (default 0: it exits).
`--agent-claim-timeout D`	Exit a launched agent no task reached (default 2m).
`--hub-absence-bound D`	An agent whose results no hub collected for D frees its slot and waits to deliver them (default 10m; 0 = never).
`--inherit-host-claude-config`	Opt in: agents use this machine's own Claude Code setup.
`--allow-cross-session-messaging`	Opt in: agents may reach this machine's other Claude sessions.
`--name ID`	Node id on the relay (default `node-<machine id>`).
`--state-dir DIR`	Where the node keeps its agent registry and logs.

Tools are opt-in

Without --allow-all-tools, agents can edit files in their checkout but every command that needs approval is refused, and the turn completes as tools_not_allowed, naming the node and the flag. Join with --allow-all-tools only on machines where you want agents to run commands.

Repositories

A spawn can name a repository and ref. A node whose --workspace checkout is that repository works in a fresh worktree of it. Otherwise the node takes it only if it matches an --allow-repo glob (matched on the normalized URL, so git@, ssh:// and https:// spellings of one remote match); it clones once into its cache and fetches refs on demand, using the machine's own git credentials. Changes come back as a branch and commit.

Describe the machine

The hub routes by what you tell it. Put what is only on this machine in --machine-description and --machine-resources: "has the production logs", "on the staging VPN", "runs the exporter service". A goal can then say "on the machine with the logs" without naming it.

Credentials and a clean Claude config

Agents run with a clean Claude config: none of the machine's user settings, hooks, CLAUDE.md, memory, plugins or MCP servers load (the task repository's own project settings still apply). So a keychain-only claude login is not read; put CLAUDE_CODE_OAUTH_TOKEN (from claude setup-token) or ANTHROPIC_API_KEY in the node's environment. The node checks this before joining and refuses with clean Claude config not established otherwise. --inherit-host-claude-config opts into the machine's own setup.

Session isolation

Agents cannot reach the machine's other Claude Code sessions (yours included): the node verifies this before any task and refuses to join if it cannot. --allow-cross-session-messaging opts out, only for machines where agents must talk to those sessions.

Agent lifetime and continuations

By default an agent process exits when its task ends. Continuing a finished agent (send_message) starts a new process on the same machine, in the same worktree and session, with its uncommitted edits restored. --agent-linger 10m keeps the process around for faster continuations. A session cannot move between machines.

When a node dies

The node owns its agents; if it is killed, its running agents end as node_lost, which the hub receives as a completion. Task worktrees the agents held are removed; branches they pushed stay. Run the same nfltr node join to bring the machine back: a spawn waiting for that machine then runs there. If the hub itself goes away instead, agents keep running and deliver their results when it reattaches.

$ nfltr orch nodes list