NFLTR›Docs›Guides

Observe Orchestration from Anywhere

Use this guide when a hub is orchestrating agents and you want to follow the work. Runs stay with the hub on its own machine, end to end encrypted; nfltr.xyz never sees a run, and the dashboard's Runs view only points here. You read them in the hub session, on the hub's machine (running or stopped), or from any machine of your account while the hub runs.

Typical flow: give the hub a goal from your laptop, let the agents run on your nodes, then check on them from the hub session or another terminal. Agents keep running when the hub session closes; a reattached hub receives every completion it missed.

Before You Look

Start work the way you already do: nfltr orch "<goal>" in a terminal, or the hub tools in your own Claude Code session (see Use nfltr from Claude Code). Once agents are running, everything below works from a terminal.

$ nfltr orch "update the install docs and open a branch"
$ nfltr orch hub runs
The hub keeps the runs; the hub decides

A hub keeps its agents, turns and their tasks' events on its own machine and sends the relay no summary or status of them. To steer, continue, or stop a hub agent, ask its hub in the session; it calls send_message or stop_agent.

See What the relay sees.

Where You See Runs

💬 The hub session

Ask the hub. list_agents lists its agents with their state, machine and fleet capacity; wait_for_agents returns each completion exactly once, with its answer, branch and usage.

🗂️ Hub runs

nfltr orch hub runs lists every hub on this machine, running or stopped, with its agents (status, turns, machine, latest task, brief) and the command that reattaches it. --hub-id narrows it to one hub; --json prints it as JSON.

🧠 Turn history

nfltr orch hub show --hub-id <id> <agent-id> prints one agent's turns: each message, state, worker and machine, usage, error, branch and sha, the answer and structured result, and the last events of the turn's task.

🔗 Task commands

While the hub runs, nfltr orch task list|status|events|result read its tasks from any machine of your account, end to end encrypted through the relay; steer, cancel and answer act on them.

🔁 Reattach

nfltr orch --hub-id <id> reopens a stopped hub. Its agents kept running on their machines; the hub receives every completion it missed, exactly once.

📱 Paired devices

A hub run with --remote-messages=answers asks its owner questions and approvals on a device paired with nfltr orch hub pair, on the dashboard's Hubs page, end to end encrypted and decrypted on that device.

Walkthrough: Laptop → Anywhere

  1. Start on laptop — Give the hub a goal; note the agent ids it reports.
  2. List the runs — nfltr orch hub runs on the hub's machine shows each hub, whether it is running, and its agents.
  3. Read an agent's turns — nfltr orch hub show --hub-id HUB_ID AGENT_ID prints each turn's message, state, answer, branch and sha, and its task's last events.
  4. Check from another machine — While the hub runs, nfltr orch task list --active and nfltr orch task status --task TASK_ID --events 20 work from any machine of your account.
  5. Follow events — nfltr orch task events --task TASK_ID --tail 50 --since SEQ resumes from the last sequence number you saw.
  6. Reattach — After the hub session closes, nfltr orch --hub-id HUB_ID brings it back with every completion it missed.

Turn Detail (Quick Reference)

What nfltr orch hub show prints for each turn:

FieldWhat it tells you
MessageWhat the hub asked the agent in this turn
StateThe turn's lifecycle state
WorkerThe worker and machine that ran it
UsageTokens and cost the agent reported
ErrorWhy a failed turn failed
Branch / shaWhat a mutating agent pushed
Answer / resultThe agent's answer and its structured result
EventsThe last events of the turn's task (--events N, default 20; -1 all, 0 none)

Tips

Related Docs