Fibscope Agent

Independent Node.js ESM agent for Fiber node owners.

It runs beside an existing Fiber node, collects local Fiber state, builds an observability report, and pushes that report to Fibscope.

Fiber RPC -> Agent -> Fibscope HTTPS endpoint

The agent is the only component that talks to local Fiber RPC. Fibscope never reaches into the node owner's machine; it only receives pushed reports from this agent.

Config

Local personal-development defaults live in agent/.env:

FIBKEY=raw-token-issued-by-platform
FIBSCOPE_AGENT_CHAIN=testnet
FIBSCOPE_AGENT_FIBER_RPC_URL=http://127.0.0.1:8247
FIBSCOPE_AGENT_PUSH_INTERVAL_MS=15000
FIBSCOPE_AGENT_PUBLIC_PROFILE=false
FIBSCOPE_AGENT_OVERWRITE_NODE_REGISTRATION=false
FIBGATE=https://fibscope.guffie.site/agent/v1/report

This file belongs to the node owner's machine. The hosted endpoint above is built into the published agent; set FIBGATE (or FIBSCOPE_AGENT_REPORT_URL) only to override it.

The agent also supports .fiber/agent.json:

{
  "agentToken": "raw-token-issued-by-platform",
  "chain": "testnet",
  "fiberRpcUrl": "http://127.0.0.1:8247",
  "pushIntervalMs": 15000,
  "publicProfileEnabled": true,
  "overwriteNodeRegistration": false,
  "publicFields": {
    "node": true,
    "peers": true,
    "channels": true,
    "liquidity": true,
    "diagnostics": true,
    "health": true,
    "metrics": true,
    "alerts": true
  }
}

The agent discovers its own public IPv4 through https://api.ipify.org, combines it with the local FNN P2P port, and includes both the IP and resulting public multiaddr in registration and report requests. Loopback, wildcard, private, and documentation addresses are never published. Set FIBSCOPE_AGENT_PUBLIC_IP only when intentionally overriding automatic discovery, or FIBSCOPE_AGENT_PUBLIC_IP_URL to use another compatible JSON or plain-text discovery endpoint.

Commands

npm run agent:init
npm run agent:start
npm run agent:once
npm run agent:status

Direct usage:

node packages/agent/index.mjs init
node packages/agent/index.mjs start
node packages/agent/index.mjs once
node packages/agent/index.mjs status

Push Payload

The agent pushes to POST /agent/v1/report with:

{
  "agentVersion": "0.1.6",
  "chain": "testnet",
  "collectedAt": 1710000000000,
  "publicIp": "54.179.226.154",
  "peerAddress": "/ip4/54.179.226.154/tcp/8228",
  "node": {},
  "peers": [],
  "channels": [],
  "liquidity": {},
  "diagnostics": [],
  "health": {},
  "metrics": {},
  "alerts": []
}

Fibscope authenticates this with x-agent-token. This is an agent key for local node reporting, not the external application API key that apps will use for quote and payment execution.

Before the first push, the agent registers the local Fiber node with POST /agent/v1/register. That saves the node owner, Fiber node id, display name, chain, public profile setting, and the latest local node details in the hosted database. If the agent key is already attached to a different registered Fiber node, set overwriteNodeRegistration to true only when you intentionally want this agent to replace that old node binding.

API Node Payment Lifecycle

For an API_NODE_PAYMENT, the agent confirms the sender deposit and checks for a viable existing Fiber route. When the quote permits provisioning and no route exists, it connects the receiving peer, opens a direct funded channel, waits for readiness, and sends the payment. A close-after-test policy applies only to the channel opened by that payment; existing channels are never closed automatically.

The command result includes provider and receiver balance views before payment, after payment, and at close. The receiver view reverses the provider-local and provider-remote balances so the receiving channel's credited local balance and remaining inbound capacity are explicit.

Owner N2N Test Lifecycle

N2N_PAYMENT is an owner-authorized test command. It never confirms or charges an API test-wallet deposit. The selected source node checks its own funding wallet and existing routes, connects the receiving peer, opens a private one-way direct channel when needed, sends over Fiber, and optionally closes only the channel created by that test. FNN v0.8.1 uses dual-funded CKB channel construction, so the receiving node wallet must still provide its configured reserved capacity (commonly about 99 CKB) when a new channel is opened.

When both FNN instances publish the same public IPv4 address, the agent dials the receiving P2P port through loopback so same-VPS nodes can complete the Fiber handshake. Command results include structured source selection, peer connection, channel creation, balance movement, Fiber transfer, optional close, and partial failure steps.

Resilience

Collection and transmission are independent loops:

• collection runs every pushIntervalMs
• transmission retries retained reports independently
• failed pushes stay in memory
• backoff doubles up to 5 minutes
• 409 Conflict is treated as a stale report response

The local status file is .fiber/agent-status.json.

Run FNN With PM2

Create the working directory, install setup and PM2, then run the setup process under PM2 with one command:

mkdir -p "$HOME/fibscope" && cd "$HOME/fibscope" && npm install -g pm2 @fibscope/setup && rm -f "$(npm prefix -g)/bin/fnn" && FIBER_SECRET_KEY_PASSWORD='<your-password>' pm2 start "$(command -v setup)" --name fiber-testnet --interpreter node -- --network testnet --rpc-host 127.0.0.1 --rpc-port 8227 --p2p-port 8228 && pm2 save

The Agent Setup page generates this command from a masked password field. The fnn link removal avoids confusing the package helper with the downloaded Fiber binary.

NPM Usage

npm install -g @fibscope/agent pm2 && agent init && pm2 start "$(command -v agent)" --name fibscope-agent --interpreter none -- start && pm2 save

Or run without a global install:

npx @fibscope/agent init
npx @fibscope/agent start

The package reads agent/.env, .env, or .fiber/agent.json from the directory where you run the command. Keep FNN RPC local, for example http://127.0.0.1:8227.