Deploy on macOS ​

The InfraScout agent runs as a launchd 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 macOS 12 (Monterey) or later and administrator 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-darwin-arm64 for Apple Silicon Macs or agent-darwin-amd64 for Intel Macs.

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-darwin-arm64 /usr/local/bin/infrascout-agent

Adjust the filename to match your architecture.

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 launchd service — one elevated command:

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

The command prints a short code and a URL. Open the URL, enter the code, and sign in with an account holding the InfraScout Admin role. The agent resolves the enrollment and gRPC addresses from the server itself, so --api is the only value you supply.

The Agents page in the portal generates this command with your own API address filled in, alongside the matching download command for your Mac's architecture.

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 With a Token ​

Where device-code sign-in is not an option, 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 launchd 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 launchd service so it starts automatically on boot. Pass the absolute path to the config file you just generated — the service bakes this path into its registration, 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 launchd daemon named InfraScoutAgent that runs as root. The agent writes its log to /Library/Logs/InfraScout/agent-YYYYMMDD.log, rotating daily; follow it live with:

bash
sudo tail -f /Library/Logs/InfraScout/agent-*.log

To stop the service, run sudo infrascout-agent service stop.

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 so the agent picks up the new configuration:

bash
sudo infrascout-agent service restart

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 macOS ​

After enrollment, this agent reports the shell capability to InfraScout, allowing assessments to run commands via /bin/sh. If LDAP is configured and the service restarts successfully, the agent also reports the ldap capability.

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

Troubleshooting ​

Gatekeeper blocks the binary — If macOS prevents the binary from running, remove the quarantine attribute applied to downloaded files:

bash
sudo xattr -rd com.apple.quarantine /usr/local/bin/infrascout-agent

Service not starting — Check the most recent log file under /Library/Logs/InfraScout/, or run sudo infrascout-agent service status. A missing config file or a certificate path mismatch under /etc/infrascout/ is the most common cause. Re-running enrollment usually resolves this.

Agent appears offline in the dashboard — Confirm the service is running with sudo infrascout-agent service status. Also verify the host clock is synchronized, since clock skew beyond a small tolerance causes the mTLS handshake to fail:

bash
sntp -sS time.apple.com