NFLTR›Docs›Tutorials

Diagnose Connection Problems

Four checks, from the network up. Run them in this order and stop at the first one that fails: it names the layer to fix.

OrderCommandAnswers
1nfltr diagnoseCan this machine reach nfltr.xyz at all? (DNS, TLS, the gRPC channel)
2nfltr statusIs the service up, how fast, and which of your machines are online?
3nfltr orch doctorIs orchestration ready: Claude, the relay, at least one node?
4nfltr orch diagnose relayService health and version, when orchestration calls fail although 1 to 3 pass.

Prerequisites

1. nfltr diagnose: the network path

$ nfltr diagnose
nfltr v1.0.532 — connection diagnostics

  ✓  DNS resolution (grpc.nfltr.xyz)          <address>
  ✓  TLS handshake (grpc.nfltr.xyz:443)       42ms (TLS 1.3)
  ✓  gRPC channel (grpc.nfltr.xyz:443)        0s

3/3 tests passed
All connectivity tests passed.

It exits 0 when every stage passes and 2 otherwise. The first ✗ tells you where to look: DNS (resolver, VPN split DNS), TLS (a proxy that intercepts HTTPS, a wrong system clock), gRPC (a firewall that blocks outbound port 443 or HTTP/2). It does not check your API key; step 2 does. --json prints the same for scripts.

2. nfltr status: the service and your machines

$ nfltr status
Server:  https://nfltr.xyz
Status:  online
Latency: 41ms
Agents:  2 connected
         - you.build-box              (a2a, node, a2a-e2ee)  [nfltr.agent.claude=available, nfltr.machine_id=build-box, nfltr.node.harnesses=claude-code, nfltr.node.id=build-box, nfltr.node.max_agents=2, nfltr.node.monitors=allowed, nfltr.runtime=node]
         - you.home-lan               (a2a, a2a-e2ee)

Agents lists what your account has online right now, on any of its keys: nodes, shares, tunnels, listeners, each with its capabilities in ( ) and its labels in [ ]. If a machine you expect is missing, the problem is on that machine: run nfltr diagnose there. Agents: 0 connected with machines you know are running can also mean the key is wrong; --require-api-key makes the command fail when no key is set at all.

3. nfltr orch doctor: orchestration readiness

With nothing joined yet, it tells you exactly that:

$ nfltr orch doctor
nfltr orch doctor — first-run readiness
  ✓  hub (claude)            claude CLI installed and authenticated
  ✓  relay                   configured: grpc.nfltr.xyz:443 (from saved config)
  ✗  agent hosts             no node or worker on the relay — on a machine: NFLTR_API_KEY=... nfltr node join --max-agents N

✗ resolve the ✗ items above, then re-run `nfltr orch doctor`

Join a machine (here, this one) and check again:

$ nfltr node join --max-agents 1
level=INFO msg="node joined the relay" node_id=node-laptop
$ nfltr orch doctor
nfltr orch doctor — first-run readiness
  ✓  hub (claude)            claude CLI installed and authenticated
  ✓  relay                   configured: grpc.nfltr.xyz:443 (from saved config)
  ✓  agent hosts             1 node(s), 0 worker(s)

✓ ready — run `nfltr orch "<goal>"`
LineWhen it is ✗
hub (claude)The claude CLI is missing or not signed in on this machine. Install it and set CLAUDE_CODE_OAUTH_TOKEN (or ANTHROPIC_API_KEY).
relayNo API key and no relay configured. Save your key: nfltr config add-api-key rpc_….
agent hostsno node or worker on the relay: join a machine with nfltr node join. relay unreachable: …/api/v1/my/agents: HTTP 401: the API key is missing or wrong.

4. nfltr orch diagnose relay: the service itself

When orchestration commands fail or hang although steps 1 to 3 pass, check the service's health endpoint and version:

$ nfltr orch diagnose relay
Relay diagnostic:
  proxy_url: https://nfltr.xyz
  health: status=ok http=200 latency_ms=38
  version: status=available version=v1.0.532 git_sha=4368b2d44fa3 built=2026-09-29T13:58:39Z latency_ms=41
  local: git_sha=4368b2d44fa3d8b0b8ef5f97da884690e5e1d52f source=build_metadata
  freshness: stale=false
  automation_origin: status=proxied url=https://api-origin.nfltr.xyz http=200 latency_ms=120 cloudflare_proxied=true
  verdict: automation_origin_proxied
  action: if you run this relay, move orchestration automation to a verified Cloudflare-bypassing origin: DNS-only api-origin, private/VPN endpoint, or local port-forward via NFLTR_PROXY_URL; on a relay you do not run there is nothing to change: orchestration calls go through Cloudflare, and the health and version lines show whether the relay is up

On nfltr.xyz this is the normal result: health: status=ok and version: status=available mean the service is up.

VerdictMeaning
relay_readyThe service is healthy. Look at your machines (steps 2 and 3) or the task itself (nfltr orch task status).
automation_origin_proxiedThe service's direct API address (api-origin.nfltr.xyz) is behind Cloudflare too, like nfltr.xyz. Nothing for you to do: orchestration calls go through Cloudflare, and the action advice is for whoever runs the relay. It is reported even when the service is down, so read the health and version lines: unavailable there means the service is having trouble (last row).
stale_relayYour CLI is newer than the service. Usually harmless; if a command you just learned about fails, the service has not caught up yet.
edge_or_origin_unhealthy, version_endpoint_unavailable, relay_unavailableThe service is having trouble. Wait and retry; your nodes and running agents reconnect on their own when it is back.

--json prints every field, for scripts and for a support request.

Clean up

Stop the node from step 3 with Ctrl+C.

# Ctrl+C in the nfltr node join terminal

Next