Agent Overview
Agents are the on-premises component of InfraScout. You install them on the hosts you want to assess — Windows servers, Linux systems, or macOS machines — and InfraScout coordinates them from the cloud. Each agent holds a persistent encrypted connection to the server and does three things: it runs commands on demand during assessments, it collects host inventory on a schedule, and it keeps itself current by renewing its own certificate and updating to new releases.
What Agents Do
During an assessment, an agent executes commands on its host and streams the results back to InfraScout. The decisions — what to run and how to interpret the output into Insights — are made by an AI client. That client is either the built-in Chat in the InfraScout portal, where you pick a playbook and tool groups and watch the assessment run, or an external MCP client such as Claude Desktop connected to InfraScout's MCP server. Either way, the agent itself is stateless: it makes no assessment decisions and only executes what it is asked.
Agents also work in the background. On a schedule you control, each agent collects a baseline inventory of its host and reports it to InfraScout, so the platform always has a current picture without having to re-scan during every conversation.
Capabilities
Agents automatically detect and report what they can do based on the platform they run on and how they are configured. Capabilities determine which tools InfraScout can use against that agent.
| Capability | Platforms | What it enables |
|---|---|---|
shell | Windows, Linux, macOS | Run shell commands (Command Prompt on Windows, /bin/sh on Linux and macOS) |
powershell | Windows | Run PowerShell scripts and cmdlets |
wmi | Windows | Execute WMI queries |
eventlog | Windows | Enumerate Event Log channels with wildcard filters and per-channel metadata, and run structured event queries filtered server-side by event ID, level, provider, time window, and event-data fields — no Get-WinEvent needed |
ldap | Windows, Linux, macOS | Search Active Directory via LDAP (requires configuration) |
daemon_start | Linux | Start a long-running background process that keeps running after the command finishes |
LDAP is available on all platforms but only activates when you provide LDAP credentials in the agent config — useful for Linux or macOS hosts that need to query Active Directory. The wmi capability is advertised on Windows only when the host's WMI service is reachable at startup, and daemon_start only on Linux hosts managed by systemd.
Agent Groups
You rarely act on a single agent in isolation. Agents are organized into groups, which let you scope an assessment to a set of hosts, control who can see which agents, and target a whole category of host without naming individual agents. Every agent can belong to several groups at once.
A group is either static — a member list you curate by hand — or dynamic, where membership is derived from a rule evaluated against agent properties such as operating system, architecture, hostname, or reported capabilities. Dynamic groups stay current on their own as you enroll, update, or retire hosts.
Groups are also how central configuration reaches an agent: both inventory collection and self-update behavior are attached to groups, and an agent inherits them through every group it belongs to. Every tenant has a system-owned All Hosts group that matches every registered agent, so each agent always falls under the default policies even if you never add it to another group. See Agent Groups for the rule model, and Manage agent groups for working with them in the portal.
Continuous Inventory
Beyond on-demand assessments, agents gather a low-overhead baseline of host facts on a recurring sweep across four categories: system (host identity and hardware), software (installed applications), services (services and daemons), and certificates (certificates in the machine trust stores). Each sweep is shipped back to InfraScout over the agent's encrypted connection, where it powers the inventory views, change tracking, and the inventory tools an AI client can query directly.
Collection is scheduled, not constant. Each agent collects only when its policy interval has elapsed since the last successful sweep — every six hours by default. A freshly installed agent, or one that has been offline longer than its interval, runs a single catch-up collection when it reconnects; a healthy agent that just rebooted within its interval does not re-collect. The sweep is resilient: if one category fails or times out, the rest of the snapshot still ships, and the missing category is flagged so you can see why it is absent rather than reading an empty result as "nothing found."
To build the change-tracking timeline, InfraScout compares each new snapshot against the previous one and records what was added, removed, or modified per category; an agent's first snapshot is simply the baseline. What each agent collects and how often is governed by inventory policies you define centrally — there is nothing to configure on the host itself. See Inventory Policies for how to scope categories and intervals across the fleet.
Enrollment
Before an agent can connect, you must enroll it. Enrollment is a one-time process that establishes the agent's identity, and there are two ways to get through it.
The one-command path is enroll auto. It signs you in to Microsoft Entra ID with a device code, provisions the agent, enrolls it, and installs and starts the service — one elevated command on the target host, with the InfraScout API address as its only argument. There is no token to create, nothing to copy between the dashboard and the host, and no chance of pasting the wrong tenant ID. The account you sign in with must hold the InfraScout Admin role, which is checked server-side.
The token path is the original enroll subcommand, for cases where a browser-driven sign-in is impractical: unattended image builds, tightly locked-down hosts, or a deployment where whoever runs the installer does not hold the Admin role. Create a token in the dashboard, then pass it along with your tenant and agent IDs and the server addresses shown on the token page. Tokens are single-use — generate a fresh one per agent.
Either way, the mechanics underneath are the same: the agent generates a cryptographic key pair locally, sends a certificate signing request to InfraScout, and stores the signed certificate, key, and CA chain alongside an agent-config.yaml file. Nothing leaves the host that would let anyone else assume its identity.
The platform-specific guides give the exact commands: Windows, Linux, macOS. The Agents page in the portal generates the download and enrollment commands for you, with your API address already filled in.
Secret Protection
The agent hardens its own credentials the first time it starts. It encrypts its private key at rest — using the operating system's machine-scoped key store on Windows, and strict owner-only file permissions on Linux and macOS — and locks down the config file the same way. If you add LDAP bind credentials, the agent encrypts the password in place on first run and removes the plaintext value from the config. All traffic between the agent and InfraScout runs over mutual TLS.
Self-Maintenance
Agents keep themselves healthy without manual intervention. Each agent renews its own certificate well before it expires, so connections never lapse and you never have to rotate certificates by hand. Renewal generates a fresh key every time, so old key material stops being usable once the new certificate is in place. If a renewal is blocked — for example, the agent cannot reach the server over the network — the agent keeps its existing certificate and retries, so a failed renewal never breaks the live connection.
Agents also update themselves to new releases, governed by the update policies you set centrally — schedule windows, delays, and target groups — so the fleet stays current without redeploying binaries. Updates download only from InfraScout's release host, are verified for integrity before they are applied, and roll back automatically if the new build fails to start or reconnect — leaving the previous, working version in place. Track rollouts from Agent Updates and shape them with Update Policies.
Running as a Service
The agent is designed to run as a system service so it starts automatically and restarts on failure. Each platform has a dedicated service manager: Windows Service Control Manager (SCM), systemd on Linux, and launchd on macOS. The infrascout-agent service subcommands install and control the service consistently across all three — see the platform-specific guides for exact steps: Windows, Linux, macOS.
Agent Identity
Each agent has a stable agent ID, assigned when you create its enrollment token. The signed certificate is issued to that ID, so identity is bound to the certificate rather than to the hostname. If you re-enroll the same agent — reusing its agent ID — InfraScout reconnects it to the existing record instead of creating a duplicate. The host's reported hostname and a human-readable display name you set in the dashboard are properties of the agent; you can use either to find and group agents, but neither is what identifies the agent to the server.