How to Deploy Employee Monitoring Software in 30 Minutes via Group Policy

This is a working IT admin's checklist for rolling out the Headx Windows agent across 25-2,000 PCs. The principles apply equally to other Windows monitoring agents that ship as an MSI.

The fastest deployment we have seen for a 50-PC team: 22 minutes, start to first dashboard report. The slowest: 4 hours, because the customer's antivirus policy blocked unsigned MSI installs and the installer had to be allow-listed first. Plan for an hour, but expect under 30 minutes if your environment is standard.

Prerequisites (5 minutes to verify)

Before you start, confirm these are in place:

• Active Directory with Group Policy Management Console (GPMC) — standard for any AD-joined environment
• An OU or Security Group containing the target machines (e.g., "Headx-Pilot-50PCs")
• A network share readable by Domain Computers — typically \\fileserver\Software\Headx\
• Your company's enrolment code — shown on the dashboard's Download Agent page
• Each employee's work email, created in Headx first — every PC is enrolled against one employee's email, and one email can be enrolled on one PC. Add employees (or import them) before the rollout, and know which email goes with which PC
• Antivirus exclusion approved — the installer is not yet code-signed, so Windows SmartScreen may warn on an interactive install and conservative AV policies (some banks, defence) will need pre-approval. Headx provides SHA-256 hashes of each release on request; add an exclusion for C:\Program Files\Headx\Agent\
• One pilot PC you have RDP access to — for a manual install first, before mass rollout

Path 1: Group Policy (recommended, 30 min)

Because each PC needs its own ENROLLEE_EMAIL, the cleanest GPO method is a computer start-up script that runs msiexec with the right properties, rather than plain Software Installation (which cannot pass per-machine properties). If you prefer Software Installation, assign the MSI without an email and let the agent prompt each user once at first login.

Step 1 — Copy the MSI to a network share (3 min)

Download Headx-Agent.msi from your dashboard's Download Agent page. Copy it to a share readable by Domain Computers, not just Domain Users — start-up scripts run as SYSTEM, which authenticates as the computer account.

mkdir \\fileserver\Software\Headx
copy Headx-Agent.msi \\fileserver\Software\Headx\
icacls \\fileserver\Software\Headx /grant "Domain Computers:R"

Step 2 — Write the start-up script (4 min)

Save this as headx-deploy.bat on the same share. It installs only if the service is missing, so it is safe to leave in place.

@echo off
sc query HeadxSvcCpp >nul 2>&1
if %ERRORLEVEL% == 0 exit /b 0
msiexec /i "\\fileserver\Software\Headx\Headx-Agent.msi" ^
  ENROLLMENT_TOKEN="<your enrolment code>" ^
  ENROLLEE_EMAIL="%USERNAME%@yourcompany.com" ^
  /qn /norestart /l*v "%TEMP%\headx-install.log"

%USERNAME% at start-up is the computer name, so use this form only if you have prepared the mapping another way — the simplest is a small lookup: keep a pcs.csv of COMPUTERNAME,email on the share and read the email with a for /f loop, or leave ENROLLEE_EMAIL out entirely and the agent will ask the user for their work email once at first login.

Step 3 — Create and link the GPO (3 min)

On a Domain Controller or a workstation with RSAT: gpmc.msc. Right-click your target OU → Create a GPO in this domain and Link it here → name it "Headx Agent Deployment - Pilot".

Edit the GPO: Computer Configuration → Policies → Windows Settings → Scripts (Startup/Shutdown) → Startup → Add → browse to \\fileserver\Software\Headx\headx-deploy.bat.

Step 4 — Make start-up wait for the network (2 min)

Computer Configuration → Policies → Administrative Templates → System → Logon → "Always wait for the network at computer startup and logon" → Enabled. Without this, laptops can run the script before the share is reachable.

Step 5 — Test on the pilot OU first (5 min)

Move 3-5 test PCs into the target OU. On each: gpupdate /force from an elevated prompt, then reboot. Check the install log at %TEMP%\headx-install.log (for a start-up script that is C:\Windows\Temp\headx-install.log), then verify the service:

Get-Service HeadxSvcCpp    # PowerShell
sc query HeadxSvcCpp       # cmd

Status should be Running within a minute of the install finishing.

Step 6 — Verify it is reporting to the dashboard (3 min)

Log in to your Headx dashboard → Agent Status. Each newly installed agent should appear as "Online" within a minute of the service starting. If you see your 5 PCs, the deployment is working — scale up.

Step 7 — Scale to the full fleet (5 min + rollout time)

Link the GPO to the parent OU containing the rest of the machines. The script runs at each PC's next restart. Most BPOs see 80-90% of their fleet online within 24 hours.

Path 2: Microsoft Intune (cloud-only environments, 25 min)

If your fleet is Intune-managed:

1. Intune admin centre → Apps → Windows → Add → "Line-of-business app"
2. Upload Headx-Agent.msi
3. App information: Name "Headx Agent", Publisher "Headx"
4. Command-line arguments: ENROLLMENT_TOKEN="<your enrolment code>" /qn /norestart. Leave out ENROLLEE_EMAIL; the agent asks each user for their work email once at first login
5. Assignment: Required → your target Entra ID group
6. Save. Intune distributes on the next device check-in (typically within 8 hours; users can force it with Sync in the Company Portal)

Validation is identical to the GPO path: check Agent Status in your dashboard.

Path 3: Manual / PowerShell (small deployments, 1 min per PC)

For under 10 PCs or ad-hoc installs, the manual MSI path is fastest:

# Run as Administrator on each PC
msiexec /i \\fileserver\Software\Headx\Headx-Agent.msi /qn /norestart ^
  ENROLLMENT_TOKEN="<your enrolment code>" ENROLLEE_EMAIL="employee@yourcompany.com"

# Verify
Get-Service HeadxSvcCpp | Select-Object Name, Status

To push to a list of PCs without GPO, keep a CSV of computer names and emails:

Import-Csv C:\temp\pcs.csv | ForEach-Object {
    Invoke-Command -ComputerName $_.Computer -ArgumentList $_.Email -ScriptBlock {
        param($Email)
        Start-Process msiexec -ArgumentList '/i', '\\fileserver\Software\Headx\Headx-Agent.msi', `
            '/qn', '/norestart', 'ENROLLMENT_TOKEN="<your enrolment code>"', "ENROLLEE_EMAIL=`"$Email`"" `
            -Wait -NoNewWindow
    }
}

Requires WinRM enabled on each target PC (usually on for AD-joined Windows 10/11) and an account that is an administrator on them.

Validation: how to know it actually worked

Three checks, in order:

Check 1 — Service status (per PC)

Get-Service HeadxSvcCpp

Expected: Running. If Stopped, see the troubleshooting section below.

Check 2 — Local install log

type C:\Windows\Temp\headx-install.log | findstr /i "error fail return value 3"

Expected: no matches. "Error 1603" or "return value 3" usually means permissions, an antivirus block, or a rejected enrolment (wrong code, email not found, or email already enrolled on another PC) — the log names which.

Check 3 — Dashboard online status

Headx dashboard → Agent Status. All agents should show "Online". If some show "Offline" while the service is running locally, the path to the dashboard is blocked — check firewall rules for outbound HTTPS (port 443) to headx.in (Cloud) or your self-hosted dashboard host.

Five common failure modes and fixes

1. "Enrolment rejected"

Symptom: Install log shows the enrolment step failing.
Fix: Three causes. The enrolment code is wrong or expired (copy it again from Download Agent); the email is not an employee in Headx (add the employee first); or that email is already enrolled on another PC (remove the old agent from the dashboard, or use the right email for this PC).

2. "Service installed but not running"

Symptom: Get-Service HeadxSvcCpp shows Stopped.
Fix: Start-Service HeadxSvcCpp. If it fails to start, check the Windows Event Log → Application for "Headx" entries and the agent's own log under C:\ProgramData\Headx\. The most common cause is an antivirus quarantining HeadxSvc.exe.

3. "GPO not applying to target PCs"

Symptom: gpresult /r on a target PC does not list the Headx GPO.
Fix: Two common causes. (1) The PC is in the wrong OU — move it. (2) A WMI or security filter on the GPO is excluding it — open the GPO → Scope tab → check Security Filtering and WMI Filters.

4. "Antivirus blocking install"

Symptom: Install log shows MSI extraction blocked, or the service is installed then immediately killed.
Fix: Add an AV exclusion for C:\Program Files\Headx\Agent\ and for HeadxSvc.exe and HeadxHelper.exe. Headx provides SHA-256 hashes of each release on request for allow-listing in Windows Defender, CrowdStrike, Trend Micro, Symantec, McAfee, Kaspersky and SentinelOne.

5. "Agents online locally but not appearing in dashboard"

Symptom: Service running, install log clean, but Agent Status shows no entries.
Fix: Outbound HTTPS connectivity. From the PC: Test-NetConnection headx.in -Port 443. If TcpTestSucceeded is False, a firewall or proxy is blocking. Allow headx.in for Cloud deployments, or your self-hosted dashboard hostname.

Rollback procedure

The agent is protected against casual removal: msiexec /x refuses unless the uninstall password set in the dashboard is supplied, or the removal is triggered from the dashboard. To undo a deployment in a hurry:

1. In the Headx dashboard → Agent Status, select the affected PCs and choose Uninstall. Each agent removes itself at its next check-in (within a minute while online).
2. Unlink the deployment GPO so the start-up script does not reinstall it.
3. For a PC that cannot reach the dashboard, run "C:\Program Files\Headx\Agent\HeadxUninstaller.exe" locally with the uninstall password.

For Intune: change the assignment from "Required" to "Uninstall" on the same group, and remove the agents from the dashboard first so the uninstall is allowed.

FAQ

Can I deploy to PCs that are not joined to AD?

Yes, via Intune (if Entra-joined), manual MSI install, or PowerShell remoting. GPO requires AD membership.

Does the install require a reboot?

No. The service starts immediately after the MSI finishes. A GPO start-up script runs at the next restart, so the PC has to restart once for the deployment to reach it. Later agent updates install themselves in the background without a reboot.

How big is the MSI?

About 60 MB. Stage it on a local file server rather than a WAN link for large sites.

Can the agent run on Windows Server (RDS / Citrix environments)?

Not today. The agent supports Windows 10 and Windows 11 desktops and laptops. Multi-user session hosts (Remote Desktop Services, Citrix) are not supported.

What about Mac and Linux endpoints?

The Headx Windows agent does not run on Mac or Linux. Mac and Linux agents are on the Headx roadmap.

How does the agent handle laptops that go offline (WFH, travel)?

Activity is captured locally and queued on the PC. When the PC reconnects, the queue uploads to the dashboard, so nothing is lost during offline periods.

Can users see they are being monitored?

By default, yes — the first run displays a notice listing what can be recorded, and the employee's response is stored. This is the recommended legal posture under the IT Act 2000. Admins can choose stealth mode per installation, but transparency is strongly advised. See our consent form template for the legal framing.