How the agent works

infrality-agent is the network discovery daemon of Infrality. It runs on a machine inside the network being mapped, sweeps the local segment, works out what each host is, and streams what it finds to the Infrality API, where it is drawn on a board.

It is a single statically linked Go binary for Linux, macOS and Windows (amd64 and arm64; Windows amd64 only).

From start-up to a finished sweep

1. It reads its configuration — config.yaml, then INFRALITY_* environment variables. See the configuration reference.
2. It registers with the API over HTTPS, presenting its API key. Registration happens on every start: it refreshes the name, address, operating system and version the dashboard shows, and the answer carries the settings chosen for it on the dashboard, which take precedence over the file.
3. It connects to the live channel — one WebSocket to wss://api.infrality.io/api/ws — and heartbeats every 20 seconds. This is what shows it as online. Then it waits.
4. When asked to sweep — by somebody pressing Scan, or by its repeat interval — it:
   1. surveys the segment once: an ARP pass, one mDNS browse and one SSDP search shared by every host, the default route, and whether the network reaches the internet;
   2. pings every address in the range, and keeps hosts that answered ARP but not ping;
   3. identifies each host that answered — reverse DNS, mDNS, NetBIOS, LLMNR, SNMP, SSDP, the TLS certificate, the HTTP title, the SSH greeting and a short list of TCP ports;
   4. streams each host to the board the moment it is classified, with progress a few times a second;
   5. files the router, from the routing table, whether or not it answered anything;
   6. reports the sweep complete, and writes a local topology.json for whoever is standing at the machine.
5. It goes back to waiting, connection held open.

If the live connection drops mid-sweep, the sweep carries on and its results are posted over HTTPS at the end — into the same scan run, not as a second board.

What it never does

• It never accepts a connection. Every connection is outbound, to api.infrality.io on port 443. Nothing listens on the network; the only listener is the optional metrics endpoint, on loopback by default.
• It never scans on its own after installation. With the default configuration it connects and waits until somebody presses Scan.
• It never logs in to anything. No credentials are tried, no authentication is attempted. The SSH probe reads the greeting a server sends unprompted and hangs up.
• It never changes configuration, captures traffic or installs anything on other machines.
• It is not a port scanner. Twenty TCP ports, a connect and nothing more, used to say what a host is.
• It never deletes anything from a board. A host missing from a sweep is marked as missed, never removed. Names and positions your team chose are kept.

The full list of packets it sends is in network footprint.

What runs it

Command	Use
infrality-agent daemon	What the installed service runs: connect, stay online, sweep only when asked.
infrality-agent run	Connect, and sweep on scan.interval if one is set. For running it by hand.
infrality-agent run --once	One sweep, then exit. For cron or a quick test.
infrality-agent config	Write a starting config.yaml.

All flags are in the command reference.

What it needs

• A machine on the network, on all the time if you want the board kept current.
• Outbound HTTPS to api.infrality.io. No inbound rule.
• CAP_NET_RAW on Linux for the ping sweep and the active ARP sweep — nothing else. The installer runs it as an unprivileged infrality-agent account holding exactly that. See privileges.
• An API key from your organization. See connect it.