Install the agent

Choose the machine

The agent maps the network it stands in, so put it inside the network you want on the board, on a machine that stays on: a server, a VM, a spare mini PC, a Raspberry Pi. One agent per segment is the rule of thumb — see several networks for routed ranges and VLANs.

It is light: a sweep of a /24 holds at most a few hundred sockets for a minute or two, and between sweeps the agent only heartbeats.

Install

The installer verifies the signed release manifest, then the archive’s SHA-256, installs the binary to /usr/local/bin, creates an unprivileged infrality-agent account and, on systemd hosts, writes a hardened service unit that holds CAP_NET_RAW and nothing else.

curl -fsSL https://www.infrality.io/agent/install.sh | sudo bash

Read it first if you prefer: install.sh. It needs curl and openssl, which are on essentially every distribution.

The same installer: it verifies the manifest and the checksum and installs to /usr/local/bin. macOS has no systemd, so no service is installed.

curl -fsSL https://www.infrality.io/agent/install.sh | sudo bash

Or download the native .pkg for your architecture (Apple silicon arm64, Intel amd64) from the releases and open it.

From PowerShell run as Administrator. The installer verifies the signed manifest and the SHA-256 the same way, using the cryptography built into Windows, installs infrality-agent.exe to %ProgramFiles%\Infrality and adds that folder to the system PATH.

irm https://www.infrality.io/agent/install.ps1 | iex

Read it first if you prefer: install.ps1. It runs on the Windows PowerShell 5.1 every machine ships with. Open a new terminal afterwards so the updated PATH applies.

Packages

Every release also carries packages, for when the agent should be installed the way the rest of the machine is.

Package	For	Installs
`.deb`	Debian, Ubuntu, Raspberry Pi OS	`/usr/bin/infrality-agent`, `/etc/infrality-agent/config.yaml` (mode `0600`, kept on upgrade), the systemd unit, enabled
`.rpm`	Fedora, RHEL, Rocky Linux, AlmaLinux	The same
`.pkg`	macOS, `amd64` and `arm64`	The binary
`.tar.gz`	Linux and macOS, by hand	The binary and `config.yaml.example`
`.zip`	Windows, by hand	`infrality-agent.exe` and `config.yaml.example`

Files are named infrality-agent_<version>_<os>_<arch>.<ext>, with linux, macos or windows and amd64 or arm64. They are published at https://www.infrality.io/releases/<version>/; latest.json names the current version and lists every file with its checksum. To check a download by hand, see verify a release.

sudo apt install ./infrality-agent_<version>_linux_amd64.deb

sudo dnf install ./infrality-agent_<version>_linux_amd64.rpm

The packages create the same infrality-agent account and grant the same single capability as the installer. They do not start the service: it would start with no API key. Configure it first.

Without installing anything

The binary is self-contained. On Linux, give it the one capability it needs and run it as any user:

tar -xzf infrality-agent_<version>_linux_amd64.tar.gz
sudo setcap cap_net_raw+ep ./infrality-agent
./infrality-agent config        # writes ./config.yaml
./infrality-agent run

That is also the way to run it in a container: grant the container NET_RAW and use host networking, so the agent sees the segment rather than a bridge.

Connect it to your organization — an API key, a board, a range.
Run it as a service — and what the service is allowed to do.