macOS - Software - Install FreshService Agent

What the Freshservice agent deployment Worklet does

This Automox Worklet™ deploys the Freshservice Discovery Agent to macOS endpoints and registers each Mac with your Freshservice ITSM instance. The Worklet expects the vendor-supplied FS-Agent.pkg file attached as a payload, plus two values you set inside the remediation script: ACCOUNT_URI (your Freshservice domain, for example https://yourcompany.freshservice.com/) and REGISTRATION_KEY (the agent registration token issued from your Freshservice admin console).

The remediation script runs the macOS installer against FS-Agent.pkg, verifies the LaunchDaemon plist was created at /Library/LaunchDaemons/freshservice.agent.daemon.plist, and writes Configuration.json with your accountUri and registrationKey at /Library/Freshservice-Agent/Freshservice-Discovery-Agent/conf/Configuration.json when that file is absent. The script then runs launchctl unload and launchctl load against the daemon plist and greps launchctl list for freshservice to confirm the service is running before exiting.

Because the script handles installation and registration in a single execution, you avoid the common failure mode of installed-but-unregistered agents that never appear in the Freshservice asset console. Policy logs surface installer output, the Configuration.json write step, and launchctl status output, so a failed enrollment is visible in Automox activity rather than requiring an SSH session to the affected Mac.

Why deploy the Freshservice agent through Automox

Freshservice asset inventory is only as accurate as the agents reporting into it. Macs that ship from a reseller, get re-imaged through Jamf, or join the fleet through a BYOD enrollment often miss the Discovery Agent entirely. The result is ITSM tickets opened against hostnames that do not exist in the asset console, hardware refresh cycles based on stale spreadsheet data, and software license reconciliation that lags the actual fleet by weeks. Each missing agent is a separate manual fix that does not scale past a few dozen Macs.

Driving the install from Automox closes that gap. This Worklet installs the signed PKG on every Mac under Automox management, writes the configuration file with the agent endpoint token, and verifies the LaunchDaemon is loaded and running. The next Freshservice sync reflects the live fleet rather than the snapshot taken the last time IT walked the office.

How Freshservice agent deployment works

1. Evaluation phase: The Worklet checks for the freshservice.agent.daemon LaunchDaemon at /Library/LaunchDaemons/freshservice.agent.daemon.plist. If the path is found, the endpoint reports compliant and remediation is skipped. If the path is missing, the script exits with code 2 and Automox queues the remediation phase on the next policy window.

2. Remediation phase: The script runs sudo installer -pkg FS-Agent.pkg -target / to install the agent, verifies that /Library/LaunchDaemons/freshservice.agent.daemon.plist exists, creates /Library/Freshservice-Agent/Freshservice-Discovery-Agent/conf if needed, writes Configuration.json with the configured accountUri and registrationKey when the file is absent, runs sudo launchctl unload then sudo launchctl load against the plist, and greps sudo launchctl list for freshservice to confirm the service is running. A non-zero exit code at any step is logged in Automox activity for triage.

Freshservice agent deployment requirements

• macOS endpoint with the Automox agent installed and LaunchDaemon support, Intel or Apple Silicon

• FS-Agent.pkg attached to the Worklet as a payload file; download the current PKG from your Freshservice admin console under Admin, Discovery, Agent Settings

• ACCOUNT_URI set in the remediation script to your Freshservice domain (for example https://yourcompany.freshservice.com/), including the trailing slash

• REGISTRATION_KEY set in the remediation script to the agent registration token from your Freshservice admin console

• Outbound HTTPS reachability from the endpoint to your Freshservice instance

• Root execution context (the default Automox agent context already satisfies this)

Expected state after Freshservice agent deployment

On successful remediation, /Library/LaunchDaemons/freshservice.agent.daemon.plist is present, /Library/Freshservice-Agent/Freshservice-Discovery-Agent/conf/Configuration.json contains your accountUri and registrationKey, and sudo launchctl list | grep freshservice returns a running daemon entry. The agent begins reporting hardware specifications, installed application inventory, and macOS build metadata to your Freshservice instance, and the endpoint appears in the Freshservice asset console after the first telemetry push.

To validate after deployment, run sudo launchctl list | grep freshservice on the endpoint and confirm the daemon shows a numeric PID rather than a dash. Inspect the configuration file with sudo cat /Library/Freshservice-Agent/Freshservice-Discovery-Agent/conf/Configuration.json to confirm accountUri and registrationKey match what you set in the script. From the Freshservice console, navigate to Assets, then Discovery, and filter by the endpoint hostname; the first inventory record should appear shortly after the daemon starts. Subsequent policy runs report compliant without re-executing remediation, because the evaluation phase finds the LaunchDaemon plist already present and exits 0.