Getting Started

NFLTR runs AI coding agents where your infrastructure lives: Claude Code agents on the laptops, VMs and private servers you join, hosted at nfltr.xyz. This guide takes you from account creation to your first nfltr orch "<goal>": one Claude hub on your terminal (or in your own Claude Code session) that spawns agents on the machines you join—no servers to provision.

The whole path: install the CLI → sign in and save an API key → put credentials in the environment → join machines as nodes → give the hub a goal → watch, steer, stop → recover. The relay on nfltr.xyz carries messages between the hub and its agents and runs no model; every decision is made by the hub, which is Claude.

The short path: install, sign in, start

Three commands take a machine from nothing to an agent that ran on it, and to a change that ran only after you approved it. The machine needs Claude Code (claude) and its token in the environment (CLAUDE_CODE_OAUTH_TOKEN from claude setup-token, or ANTHROPIC_API_KEY; step 3 below says why).

$ curl -fsSL https://nfltr.xyz/install.sh | sh -s -- --with orch

$ nfltr config login

$ nfltr start

nfltr start first checks the machine: an account is saved, the relay answers and accepts its key, claude is installed and signed in, and the token agents read is in the environment. Each problem is one line with its fix, and nothing changes until every check passes. Then:

Your approval key. ~/.config/nfltr/approval.key is made once (mode 0600, never overwritten). It signs your approvals; its public half goes to the node.
The node policy. ~/.config/nfltr/node-policy.json is written once and is yours to edit. In it, agents read and search files freely; a shell command or a file change runs only in a turn whose exact prompt you approved; credentials (the nfltr config, the approval key, ~/.ssh, Claude's credentials) are never read, approved or not.
This machine as a node, with that policy and key, one agent at a time (--max-agents changes it), working in the directory where nfltr start ran. It keeps running in the background until nfltr orch nodes stop or a reboot; nfltr start again rejoins.
A first task. A Claude hub sends one agent to this machine, which describes the directory with read-only tools; its answer is printed, followed by the next steps.

No model or effort is chosen for you: the hub and its agents use Claude Code's own.

An approved change

A request for a change goes to the hub as usual, for example nfltr orch "add today's date to NOTES.md". The node refuses the agent's edit, and the hub asks for your approval of the exact prompt it would send, with that prompt's SHA-256. You sign it on your machine:

$ nfltr orch hub approve --key-file ~/.config/nfltr/approval.key \
    --node NODE_ID --prompt-file prompt.txt --ttl 15m

The printed grant goes back to the hub (nfltr orch "approved: <grant>", which resumes the same session), and the agent runs again with it. The node, not the prompt, checks the grant: it is valid for that prompt on that node, once, until it expires.

A second machine

The same commands there: install, nfltr config login, nfltr start. To approve with one key on every machine, nfltr start --approval-public-key takes the public key the first machine printed; without it, each machine has its own.

When something is not ready

nfltr orch doctor runs every check and prints one line with the fix for each problem.

$ nfltr orch doctor

This machine's node stops with:

$ nfltr orch nodes stop

The rest of this page is the same path piece by piece, for machines that need other settings: repositories, more agents, a description the hub routes by.

1. Install the nfltr CLI and Claude Code

On every machine that takes part (your laptop and any server), install the latest CLI (macOS and Linux, amd64 and arm64):

$ curl -fsSL https://nfltr.xyz/install.sh | sh -s -- --with orch
$ export PATH="$HOME/.local/bin:$PATH"     # the installer's directory, when it is not on PATH yet
$ nfltr version

--with orch also installs nfltr-orch, which nfltr orch, nfltr node and nfltr mcp run (nfltr finds it beside itself); a machine that only shares and tunnels needs just nfltr. nfltr update --apply keeps both current. The installer puts nfltr in ~/.local/bin (NFLTR_INSTALL_DIR changes it). When that directory is not on your PATH, it prints the export line and the shell startup file to add it to (~/.zshrc for zsh, ~/.bashrc or on macOS ~/.bash_profile for bash, else ~/.profile), so new shells find it too.

Agents run Claude Code, so install the claude CLI on each machine too: curl -fsSL https://claude.ai/install.sh | bash.

2. Create your account and an API key

Sign in with your Google account in the browser; the CLI receives a new API key on a 127.0.0.1 callback, saves it as the active key in ~/.config/nfltr/nfltr.json (mode 0600) and never prints it:

$ nfltr config login

On a machine without a browser, open nfltr.xyz/dashboard, sign in, create a key under Account → API keys (it is shown once), and save it with nfltr config add-api-key (prompts without echo). Treat keys like passwords—never commit them to git.

3. Put your credentials in the environment

Give each machine the nfltr key, either in the environment or saved once in the CLI config. Never pass it on the command line: argv is visible to other users.

$ export NFLTR_API_KEY=rpc_your_key_here   # or: nfltr config login / nfltr config add-api-key
$ export CLAUDE_CODE_OAUTH_TOKEN=...        # from `claude setup-token` (or ANTHROPIC_API_KEY)

Agents run with a clean Claude config (none of the machine's personal settings, hooks, memory or plugins), so a keychain-only claude login is not used: the Claude token must be in the environment where the node runs.

4. Join each machine as a node

A node is one long-running process per machine; it starts agents on demand when the hub needs them. Describe what only this machine has, so the hub can route work to it:

$ nfltr node join --max-agents 2 --allow-all-tools \
    --allow-repo 'github.com/your-org/*' \
    --machine-description "build box with the nightly dataset in /data" \
    --machine-resources dataset.nightly

--allow-all-tools lets agents run shell commands (tests, git push, reading files outside the task directory). Without it agents can only edit files: a command that needs approval is refused.
--allow-repo names the repositories a spawn may name here (it needs --allow-all-tools). The node keeps a mirror of each and git credentials that answer only for them; the agent clones and pushes itself. Without it, spawns naming a repository go to other nodes.

Leave it running, then check from any machine. All flags are in Join machines as nodes.

$ nfltr orch nodes list

5. Give the hub a goal

On your laptop, with the key saved or NFLTR_API_KEY set, nfltr orch talks to nfltr.xyz and its first line names the relay (with nothing configured it runs a zero-setup local hub on this machine instead). Check readiness, then state the outcome you want:

$ nfltr orch doctor

$ nfltr orch --hub-max-tokens 2000000 --hub-max-usd 5 \
    "On the machine with the nightly dataset, summarize it; then on my laptop add the numbers to README.md in github.com/your-org/app and push a branch"

The hub (Claude on your terminal) spawns agents on the right machines, collects their results, and prints the final answer with the delivered branch and the run's spend. Run nfltr orch with no goal for an interactive hub you can talk to while agents run. The budget flags cap what the hub's agents may spend; nothing is capped unless you set them. More in Give the hub a goal.

Prefer your own Claude Code session as the hub? Two commands: claude mcp add nfltr -- nfltr mcp --toolset hub and nfltr orch hub install-hook --prefer-agents. The hook wakes the session when an agent completes; --prefer-agents records your preference that code work goes to agents on your nodes. Without it, a session usually edits locally, and a non-interactive claude -p stops with "the edit tools were denied" instead of using an agent. --prefer-agents=false removes it. See Use nfltr from Claude Code.

6. Watch, steer, stop

Talk to the hub: ask it what is running, tell it to change an agent's course, or to stop one; it calls list_agents, send_message and stop_agent for you. From another terminal you can watch the same work read-only:

$ nfltr orch task list --active

On the hub's machine, nfltr orch hub runs lists its agents, running or stopped. Details in Many agents across machines.

An agent that edits a repository clones it into its own task directory, commits and pushes a branch: the branch and commit named in the agent's result are the ones to review and merge. Work it did not push is removed with its task directory. Want a particular branch name? Say so in the goal.

7. Recover

Agents keep running when the hub exits. Run nfltr orch again in the same project (or with the same --hub-id) and the hub reattaches and receives every completion it missed, exactly once. A node that dies mid-job reports its agents as node_lost, and the hub can re-issue the work when the machine rejoins. See Troubleshooting.