Discovery agents

Discovery agents

You manage discovery agents from the assets agent rail at /agent/assets/discovery-agents. They moved out of the admin shell — the old /admin/assets/discovery-agents paths are now 301 redirects. Because they feed the register over the network, the screen is gated by the assets::admin permission even though it lives in the agent rail.

A discovery agent is a small cross-platform Go binary that runs on a managed device and reports that device’s inventory back to the platform on a schedule. It feeds hardware and installed-software detail into the asset register so you’re not hand-keying every machine.

Think of it as the difference between “someone with a clipboard walks every classroom” and “each device tells us what it is”. The agent reduces the clipboard walk-time.

What the agent reports

Each check-in (default every 30 minutes) sends the host it runs on:

• Hostname, serial number, manufacturer, model
• CPU, RAM, total/free disk
• OS name + version, primary IP + MAC
• The installed-software list (full set each time)

What it doesn’t do:

• Scan the wider LAN (it reports its own host, not a network sweep — see Scope below)
• Push software (no MDM functionality)
• Read user files
• Make outbound changes to the device

Matching to the register

When a check-in arrives, the platform tries to auto-match the device to an existing asset by serial number. A match links the discovered device to that asset automatically; no match leaves it in the Discovered, unmatched list for an agent to adopt (which creates a hardware asset from the device’s details) or mark out of scope. An already-matched device is never re-pointed by a later check-in.

Installation

The agent ships as a per-platform binary (Linux, Windows, macOS) built in CI and published with each release, plus an install script and a systemd unit. Per device (or per representative host):

1. Register the agent at /agent/assets/discovery-agents — the new-agent form issues the agent’s ID and shared secret on creation (the secret is shown once).
2. Download the binary for the platform and drop the ID + secret into the agent’s config.yaml (server_url, agent_id, shared_secret). Keep the config file 0600 — it holds the secret.
3. Run the install script: on Linux/macOS it installs + enables the systemd unit; on Windows it registers a startup scheduled task.
4. The agent shows Online in the discovery-agents list after its first check-in.

See the bundled README.md and config.example.yaml in the agent package for the full configuration reference.

Configuration

Per agent, in config.yaml on the host:

• server_url — your Keystone base URL
• agent_id + shared_secret — from the registration form
• interval — check-in cadence (default 30m)
• include_software — whether to send the installed-software inventory
• log_level — info by default

What you’ll see

In the discovery-agents and discovered-devices views:

• Discovered, unmatched — devices reporting a serial not yet in the register. The registrar reviews and adopts, or marks out of scope.
• Discovered, matched — devices auto-linked (or adopted) to a register asset. The link is shown on the asset.
• Online status — driven by the agent’s last check-in time.

Security

The agent is connect-out only — no inbound port required. It authenticates with the per-agent shared secret in the X-Keystone-Agent-Secret header, and the check-in endpoint pins the workspace from the agent record, so one academy’s agent can never write into another’s data. The agent runs as an unprivileged service account; it has no need to be root.

Scope — per-host today, LAN sweep later

This agent is a per-host inventory agent: it reports the device it runs on. It is not a network scanner that walks ARP/DHCP across a VLAN. A network-sweep mode is a possible future enhancement — it would need a server-side ingest change to accept lightweight records for hosts the agent didn’t run on — so it’s deliberately out of scope for now.

For devices that can’t run the agent (a networked projector, a switch) the manual register + stocktake stays the primary path.