Connect it to your organization

An installed agent knows nothing yet: not which organization it belongs to, nor which board to draw on. Two values tell it — an API key and, optionally, a board id.

1. Create an API key

In the dashboard, open your organization’s API keys section and create one. Only admins can, unless the organization’s policy restricts it to owners. The key (nk_…) is shown once — copy it now. It is bound to the first agent that registers with it, which is what you want for one machine. See API keys.

2. Find the board

Open the board the agent should draw on. Its id is in the address: https://app.infrality.io/<board-id>/edit. It must be a board of the same organization as the key, not in the trash.

You can also leave this out and choose the board later in the agent’s settings on the dashboard.

3. Write the configuration

Linux

The installer and the packages put the file at /etc/infrality-agent/config.yaml, readable by the service account only.

sudo infrality-agent config                     # if the file does not exist yet
sudo nano /etc/infrality-agent/config.yaml

macOS

sudo infrality-agent config                     # writes /etc/infrality-agent/config.yaml
sudo nano /etc/infrality-agent/config.yaml

Windows

On Windows the agent reads config.yaml from the folder it is started in, or from the path given with --config. Keep it somewhere only administrators can read:

New-Item -ItemType Directory -Force C:\ProgramData\infrality-agent
cd C:\ProgramData\infrality-agent
infrality-agent config                          # writes .\config.yaml
notepad config.yaml

The two lines that matter:

config.yaml

ingestor:
  api_key: "nk_your_key_here"
  base_url: "https://api.infrality.io"
  project_id: "the-board-id"          # optional: can be chosen on the dashboard

The range defaults to the network the machine is on. Set scan.cidr and scan.mask only to sweep something else. Every other key is in the configuration reference.

4. Start it

Linux

sudo systemctl enable --now infrality-agent
journalctl -u infrality-agent -f               # watch it register

macOS

sudo infrality-agent daemon

Windows

From an Administrator terminal:

infrality-agent --config C:\ProgramData\infrality-agent\config.yaml daemon

It registers, connects, and appears online in the organization’s Agents within a few seconds.

5. Sweep

Press Scan on the agent in the dashboard. Hosts appear on its board as each is identified, and the run is listed with its progress and outcome.

Check that it is attributed

If the board stays empty after a sweep, the agent may not be attributed to it. The API refuses a board the key does not entitle the agent to — another organization’s, a personal board, one in the trash, or an id that names nothing — and says so. The agent logs it at start-up, before anything else:

WARN the API refused part of this agent's configuration warning="The board … named in this agent's config was refused: …. Nothing this agent finds will be attributed to it."

Fix the id, or choose the board in the agent’s settings on the dashboard. Once a board has been chosen there, the dashboard decides and the project_id in the file is ignored — the agent logs that too. See troubleshooting.

One key per machine

A key created as single-agent (the default) belongs to the first agent that registers with it. Copying the same config.yaml to a second machine gets that machine refused with That API key is bound to a different agent. Create a key per agent.

Environment variables instead of a file

Any key can come from the environment: INFRALITY_ plus the key in capitals, with . as _. Useful in a container or with a secret manager, so the API key is never written to disk:

INFRALITY_INGESTOR_API_KEY=nk_… INFRALITY_INGESTOR_PROJECT_ID=… infrality-agent daemon