Deploy on Linux ​

The InfraScout agent runs as a systemd service and connects back to the InfraScout server over an encrypted channel. Once enrolled, the agent accepts shell commands from AI-driven assessments and optionally queries Active Directory over LDAP.

Prerequisites ​

You need a Linux distribution with systemd (Ubuntu 18.04+, RHEL/CentOS 7+, Debian 10+, or equivalent) and root or sudo privileges on the host. Enrollment needs either an InfraScout Admin account to sign in with — the one-command path below — or an enrollment token from the dashboard. The host also needs outbound access to two endpoints on your InfraScout server: the enrollment service over HTTPS during setup, and the gRPC server (default port 50051) for its ongoing connection.

Download the Agent ​

Download the agent binary from the InfraScout dashboard under Settings → Downloads. Choose agent-linux-amd64 for x86-64 hardware or agent-linux-arm64 for ARM hardware.

Once downloaded, install the binary to /usr/local/bin/ under the name infrascout-agent, which is how every command in this guide refers to it:

bash
sudo install -m 755 agent-linux-amd64 /usr/local/bin/infrascout-agent

Enroll in One Command ​

Enrollment does not need a token. enroll auto 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, nothing to copy from the dashboard:

bash
sudo infrascout-agent enroll auto --api https://api.infrascout.cloud

The command prints a short code and a URL. Open the URL on any device, enter the code, and sign in with an account holding the InfraScout Admin role — the role is checked server-side, so a non-admin sign-in is refused rather than half-provisioning a host. The agent then resolves the enrollment and gRPC addresses from the server itself, which is why --api is the only value you have to supply.

The Agents page in the portal generates this command for you with your own API address already filled in, next to the matching download command for the platform and architecture you pick.

The access token and the enrollment material live only in memory — neither is written to disk or logged. If the service step fails after a successful enrollment, the enrollment is kept and the command prints the recovery commands to finish by hand.

Put the binary somewhere only root can write

Whichever path you use, install the binary to a root-owned location before enrolling. Service installation registers the binary at its current path and then runs it with full system privileges — enroll from a home directory or a downloads folder and you leave a privileged service executing a file any local user could replace.

enroll auto also accepts the optional configuration flags, so LDAP settings and other host options can be written at enroll time instead of edited afterward. See Configure LDAP below.

Enroll With a Token ​

Where device-code sign-in is not an option — an unattended build, a host that cannot reach a browser-driven sign-in, or a deployment where nobody holds the Admin role at install time — enroll with a token instead. The token page in the dashboard shows every value you need to fill in — the token itself, your tenant and agent IDs, the enrollment service URL, and the gRPC server address. Run the enrollment command as root:

bash
sudo infrascout-agent enroll \
    --token YOUR_ENROLLMENT_TOKEN \
    --tenant-id YOUR_TENANT_ID \
    --agent-id YOUR_AGENT_ID \
    --server https://YOUR_ENROLLMENT_URL \
    --grpc-addr YOUR_GRPC_HOST:50051 \
    --output-dir /etc/infrascout

The --server value is the HTTPS enrollment service URL used only during setup, while --grpc-addr is the address the agent connects to afterward for its ongoing session. The agent generates a key pair, performs a certificate exchange with the server, and writes its certificate, key, CA chain, and agent-config.yaml to the directory given by --output-dir — /etc/infrascout/ is the conventional location. When enrollment succeeds, the command prints a confirmation message that includes the agent's assigned ID.

INFO

The enrollment token is consumed on first use. Generate a new token from the dashboard if you need to re-enroll this host or enroll an additional host.

Install as a systemd Service ​

If you enrolled with the one-command path, the service is already installed and running — skip to the next section. After a token enrollment, install the agent as a managed systemd service so it starts automatically and restarts on failure. Pass the absolute path to the config file you just generated — the service bakes this path into its unit, so it must be absolute:

bash
sudo infrascout-agent service install --config /etc/infrascout/agent-config.yaml

Then start the service:

bash
sudo infrascout-agent service start

Verify it is running:

bash
sudo infrascout-agent service status

The install creates a systemd unit named InfraScoutAgent that runs as root and is enabled at boot. You can manage it with the usual systemd tooling if you prefer — for example sudo systemctl status InfraScoutAgent. The agent writes its log to /var/log/infrascout/agent-YYYYMMDD.log, rotating daily; follow it live with:

bash
sudo tail -f /var/log/infrascout/agent-*.log

Configure LDAP (Optional) ​

If this host can reach an Active Directory domain controller, you can enable LDAP queries so assessments can read directory data from this agent. Add an ldap block to /etc/infrascout/agent-config.yaml:

yaml
ldap:
  server: ldap://dc01.example.com
  base_dn: DC=example,DC=com
  bind_dn: CN=svc-infrascout,OU=Service Accounts,DC=example,DC=com
  bind_password: YourServiceAccountPassword

After saving the file, restart the service:

bash
sudo systemctl restart infrascout-agent

The agent encrypts bind_password in place on first startup, so the file will no longer contain the plaintext value after the service has run.

TIP

Use a read-only service account for the bind credentials. The agent only reads from Active Directory — it never writes to the directory.

Capabilities on Linux ​

After enrollment, this agent reports the shell capability to InfraScout, allowing assessments to run commands via /bin/sh. On systemd-managed hosts it also reports daemon_start, which lets an assessment launch a long-running background process that detaches from the command and keeps running on its own — it survives the agent restarting or updating, and journald, which lets assessments query the systemd journal with structured filters instead of shelling out to journalctl. Where the agent can read the kernel's metrics interface it reports perfmetrics, which powers Linux performance reads. If LDAP is configured and the service restarts successfully, the agent reports the ldap capability as well.

Windows-only capabilities — powershell, wmi, and eventlog — are not available on Linux hosts.

Capabilities are probed rather than assumed, so a host that cannot honor one simply does not advertise it and the matching tool fails fast with a clear not-supported error instead of returning something misleading.

Embedded and Non-systemd Hosts ​

Linux is not only servers. The agent ships a build for 32-bit little-endian MIPS alongside the usual x86-64 and ARM64 binaries, which covers the MediaTek and Ralink-class hardware behind OpenWrt routers, network appliances, and similar embedded devices. It appears as a download option in the portal once a release includes it.

Those hosts frequently do not run systemd, and the services inventory handles that. Rather than assuming systemctl exists, the agent probes for the service manager the host actually uses and collects accordingly — systemd, procd on OpenWrt, OpenRC on Alpine and Gentoo, or plain SysV and BusyBox init. Each is read through its own native interface, so the services inventory returns real data on an appliance rather than an error that flags the whole snapshot as partial. A host running no recognized service manager reports an empty service list and a clean snapshot, which is the honest answer.

INFO

Embedded hosts are stripped, so capability detection is done by probing for the binaries and directories a manager actually needs rather than reading a distribution identity file. That is why a minimal OpenWrt image resolves correctly where a distribution check would not.

The one-command enrollment path expects an interactive browser sign-in, which is often impractical on an embedded device. Enroll those hosts with a token instead.

Troubleshooting ​

Service fails to start — Check the most recent log file under /var/log/infrascout/ (or run sudo infrascout-agent service status). Missing config or certificate files under /etc/infrascout/ are the most common cause. Re-running enrollment usually resolves this.

Enrollment fails — Verify that the host has outbound connectivity to the enrollment service over HTTPS and to the gRPC server (default port 50051). If a TLS-inspecting proxy sits between this host and the server, add an exception for the InfraScout server endpoints — mTLS client certificates are incompatible with SSL inspection.

Agent appears offline in the dashboard — Confirm the service is running with sudo infrascout-agent service status (or systemctl is-active InfraScoutAgent). Also check that ntpd or systemd-timesyncd is keeping the system clock synchronized; clock skew beyond a small tolerance causes the mTLS handshake to fail.