Overview
The Huntress app template in Swif deploys the Huntress agent to your managed Macs in one step. It installs Huntress silently, and also creates the Huntress System Extension Profile, which approves Huntress's system extension, so users don't see any security prompts.
Why the profile matters. macOS doesn't run a system extension until it's approved, by the user or by MDM. Without the Huntress System Extension Profile, Huntress's extension waits for someone to approve it on each Mac, and the agent reports as inactive.
Prerequisites
Item | Details |
Macs | macOS 11 or later, enrolled in Swif (company-owned or BYOD). Supervision isn't required. Not supported on Macs enrolled as BYOD with Enrollment SSO (account-driven User Enrollment). |
Huntress Account Key | A unique 32-character key for your Huntress account, from your Huntress portal |
Organization Key | The key for the Huntress organization you're deploying to, such as |
Huntress installer | The Huntress macOS installer package, downloaded from your Huntress portal |
Set up Huntress with the app template
In Swif, go to Device Management > Applications, and select the macOS tab.
Click View All Templates, or scroll through the template carousel, and find Huntress. Click Configure, and select for macOS.
The template opens as a four-step wizard: Basic information, Validation rules, Device assignments, and Review.
Step 1: Basic information
A banner at the top confirms: "On completion, this template automatically creates a Huntress System Extension configuration profile (.mobileconfig) and assigns it to the selected devices along with the app package."
Most fields are already filled in, such as Name, Description, Version, and Tags. Complete these:
Installer File: upload the Huntress macOS installer package, downloaded from your Huntress portal. Until you do, the template shows Missing installer package.
Post-Install Command Script: two yellow banners ask you to replace the placeholders with your keys:
In
ACCOUNT_KEY="REPLACE_WITH_32_CHARACTER_ACCOUNT_KEY", replaceREPLACE_WITH_32_CHARACTER_ACCOUNT_KEYwith your Huntress Account Key.In
ORGANIZATION_KEY="REPLACE_WITH_EXACT_ORGANIZATION_KEY", replaceREPLACE_WITH_EXACT_ORGANIZATION_KEYwith your Organization Key.
The banners disappear once you've entered valid values.
Click Continue.
Installed App Name can stay empty for now. Fill it in after Huntress first installs on a Mac, so Swif can detect its version. See How to Find the Installed App Name for Custom Applications.
Step 2: Validation rules
The rules Swif uses to check that Huntress is installed are already set up. Review them, then click Continue.
Step 3: Device assignments
Select the Macs or device groups to deploy Huntress to, then click Continue.
Step 4: Review
Check your settings, and click Finish.
Swif adds Huntress to your macOS Applications list. It also creates the Huntress System Extension Profile policy, and assigns it to the same Macs. You can find the policy in Device Management > Policies.
What the Huntress System Extension Profile includes
Part | What it does |
System extension approval | Approves Huntress's system extension ( |
Content filter | Allows Huntress to inspect network traffic |
Privacy permissions | Gives the Huntress agent and its background process Full Disk Access |
Login items | Makes sure Huntress's background services start automatically. macOS 13 or later. On macOS 11 and 12, system extension approval and Full Disk Access still apply. |
How it works
The profile is installed first, so Huntress has the approvals and permissions it needs before it runs.
The post-install script installs Huntress silently in the background.
Reinstalls are skipped. If Huntress is already installed and running correctly on a Mac, the script reports success, without reinstalling it.
Verify the installation
In Swif, Huntress reports as installed once Swif's install check finds the Huntress app at /Applications/Huntress.app/Contents/MacOS/Huntress.
On the Mac, check the system extension:
systemextensionsctl list
The Huntress line should end with [activated enabled]:
enabled active teamID: 7W6HQ9J9XA bundleID: com.huntress.sysext Huntress System Extension [activated enabled]
If it shows [activated waiting for user] instead, see Troubleshooting below.
To check Huntress's status:
sudo /Applications/Huntress.app/Contents/MacOS/Huntress status
The output should show Extension Status: installed, EDR status: enabled, and Full Disk Access set to true for both the agent and the extension.
Troubleshooting
The extension shows "activated waiting for user"
The Mac doesn't have the Huntress System Extension Profile. This can happen on Macs that got Huntress from a deployment made before the template added the profile. Existing deployments aren't updated automatically.
To fix it, do one of these:
Assign the existing profile. If you've already run the updated template, go to Device Management > Policies, open Huntress System Extension Profile, and assign it to the affected Macs or device groups.
Run the template again for the affected Macs or device groups. Swif creates the Huntress System Extension Profile, and assigns it to them.
The new profile replaces any older Huntress profile, and macOS approves the waiting extension, with no action from the user.
A BYOD Mac enrolled with Enrollment SSO doesn't get Huntress
This is expected. Macs enrolled as BYOD with Enrollment SSO use Apple's account-driven User Enrollment. Apple doesn't allow the Huntress System Extension Profile's settings there, and the Swif agent can't be installed. To deploy Huntress to a personal Mac, enroll it with Swif's standard BYOD enrollment instead. See Set up Enrollment SSO for Apple devices.
Huntress reports as inactive after an update
A Huntress update can install a new version of its system extension, which needs approval again. Check systemextensionsctl list. If it shows [activated waiting for user], follow the steps above.
The template's yellow banners don't disappear
The script still contains REPLACE_WITH_32_CHARACTER_ACCOUNT_KEY or REPLACE_WITH_EXACT_ORGANIZATION_KEY, or the values aren't valid. Check that you replaced both, inside the quotation marks.
The template shows "Missing installer package"
Download the Huntress macOS installer package from your Huntress portal, and upload it in Installer File. It's required.
Full Disk Access shows false in the Huntress status
In Swif, go to Device Management > Policies, and check that Huntress System Extension Profile is assigned to the Mac. On the Mac, go to System Settings > General > Device Management, and check that the Huntress profile is installed.