Skip to content
Docs

Deploying Connect with Microsoft Intune

This page takes an Intune administrator from an empty group to computers whose AI traffic shows up in Usage Insights, with no per-device clicks. It is the Intune-specific companion to Endpoint Enrollment, which explains what Connect does and how a computer is tied to an employee. For JumpCloud, see Deploying Connect with JumpCloud.

On every operating system you push exactly two things, both downloaded from Agent Fleet → Deploy with an MDM:

  1. The installer — puts AgentWatch Connect on the computer.
  2. One settings file — tells Connect which AgentWatch server to use and which organization it belongs to (and, on macOS, carries your organization’s Connect certificate), from a place only an administrator or the MDM can write.

After that nothing is clicked on the computer — not by the employee and not by IT. Connect enrolls the signed-in employee, switches interception on and keeps it on by itself. The one exception is described in What does the employee see?

Linux is not covered by Intune here. Intune can enroll Ubuntu and RHEL desktops for compliance, but it does not deploy software to them. For Linux use the JumpCloud page (place the downloaded connect.json at /etc/agentwatch/connect.json, owned by root, then install the .deb), the one-line installer in Endpoint Enrollment, or your existing configuration-management tool (Ansible, Puppet, Salt) doing the same two steps.

What do I need before I start?

Section titled “What do I need before I start?”
Item Where to get it Used for
An enrollment token AgentWatch console → Agent Fleet → Agent Connect Settings → Enrollment Token. If the field is empty, click Regenerate token beside it. Sign in as an administrator of the organization the computers belong to Written into every settings file. Without one, the Settings downloads refuse and the console says so
Your employee email domain For example acme.com Typed into Deploy with an MDM → Employee email domain, the fallback <computer sign-in name>@acme.com
Employees in AgentWatch SSO/SCIM, CSV import, or Employee Management → Add Every computer is enrolled as an existing employee
Microsoft Entra groups A device group per OS is simplest: AgentWatch – Windows, AgentWatch – macOS Assignments
Microsoft Win32 Content Prep Tool IntuneWinAppUtil.exe, from Microsoft (linked in Sources) Packaging the Windows installer and settings

The enrollment token identifies your organization, not a person. Anyone who holds it can attempt to enroll a computer into your organization, so if it leaks click Regenerate token, download the settings files again and replace them in the package and profile below. Enrolled computers keep working; each received its employee’s own key at enrollment. No gateway ak_ key is needed.

Where do I download the two files?

Section titled “Where do I download the two files?”

In the AgentWatch console, open Agent Fleet → Deploy with an MDM, type your domain into Employee email domain, then click Installer and Settings for each operating system:

OS Installer Settings Where the settings land on the computer
Windows 10/11, x64 AgentWatch-Connect-Setup-<version>-windows-x64.exe (signed) agentwatch-connect.reg HKEY_LOCAL_MACHINE\SOFTWARE\Policies\AgentWatch\Connect — REG_SZ values ServerURL, EnrollmentToken, EmailDomain
macOS 12+, Apple silicon and Intel AgentWatch-Connect-<version>-macos-universal.pkg (signed and notarized) agentwatch-connect.mobileconfig a configuration profile; Connect reads /Library/Managed Preferences/ai.iterate.agentwatch-connect.plist

Each Settings download is recorded in Settings → Audit Logs as fleet.mdm_config_downloaded. The installers are also served directly by your server:

Terminal window
curl -fsS https://agentwatch.acme.com/agent/version
# "latestVersion":"1.0.148", "installers":{"windows-x64":"/agent/bundle/AgentWatch-Connect-Setup-1.0.148-windows-x64.exe",
#   "darwin-pkg":"/agent/bundle/AgentWatch-Connect-1.0.148-macos-universal.pkg", ...}

How is each computer tied to an employee without a sign-in?

Section titled “How is each computer tied to an employee without a sign-in?”

Connect works out the employee’s email by itself, in this order:

  1. Email in the managed settings, if Intune substitutes a per-user value into it (an unsubstituted placeholder such as {{mail}} is ignored, never sent).
  2. On Windows, the signed-in user’s Microsoft Entra ID / Active Directory sign-in address (UPN), for example jdoe@acme.com. The Connect service reads it itself, so Entra-joined and hybrid-joined PCs need nothing more.
  3. <computer sign-in name>@EmailDomain, for example macOS short name jdoe → jdoe@acme.com.

If one of these is an employee in AgentWatch, the computer is enrolled as that employee and nobody is asked anything. Only when none of them produces a provisioned employee — or Agent Fleet → Agent Connect Settings → Require sign-in to approve each computer is on — does the employee see a one-time sign-in code. That is the only case in which anyone touches the computer.

The settings file from the console carries ServerURL, EnrollmentToken and EmailDomain. For reference, these are all the keys Connect accepts — every value is a string (on Windows REG_SZ; Connect ignores DWORD or multi-string values):

Key Value Required
ServerURL https://agentwatch.acme.com Yes
EnrollmentToken the token from Agent Fleet → Agent Connect Settings Yes (or apiKey)
Email the employee’s email, for example Intune’s {{mail}} token on macOS No
EmailDomain acme.com No, but recommended
apiKey one employee’s ak_ key instead of a token — only for a computer that belongs to one known person No

How do I deploy to Windows?

Section titled “How do I deploy to Windows?”

One Win32 app carries both files: the install script imports the settings, then runs Setup silently. Both happen in the same SYSTEM run, so they always arrive together.

Step 1 — build the package

Section titled “Step 1 — build the package”

Make a folder with the two downloaded files and an install script:

C:\AgentWatchPkg\
  AgentWatch-Connect-Setup-1.0.148-windows-x64.exe
  agentwatch-connect.reg
  Install-AgentWatchConnect.ps1

Install-AgentWatchConnect.ps1 (save as ASCII):

Terminal window
# Runs as SYSTEM from the Intune management extension.
$ErrorActionPreference = 'Stop'


# 1. Settings. /reg:64 writes the 64-bit view, where Connect reads, whichever host runs this.
& "$env:SystemRoot\System32\reg.exe" import "$PSScriptRoot\agentwatch-connect.reg" /reg:64
if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }


# 2. Installer: silent, no reboot, no tray in the SYSTEM session, log for troubleshooting.
$setup = Get-ChildItem -Path $PSScriptRoot -Filter 'AgentWatch-Connect-Setup-*-windows-x64.exe' | Select-Object -First 1
$p = Start-Process -FilePath $setup.FullName -Wait -PassThru -ArgumentList `
  '/VERYSILENT','/SUPPRESSMSGBOXES','/NORESTART','/NOTRAY=1','/LOG="C:\Windows\Temp\AgentWatch-Setup.log"'
exit $p.ExitCode

Package it:

Terminal window
IntuneWinAppUtil.exe -c C:\AgentWatchPkg -s C:\AgentWatchPkg\AgentWatch-Connect-Setup-1.0.148-windows-x64.exe -o C:\AgentWatchOut -q

The result is C:\AgentWatchOut\AgentWatch-Connect-Setup-1.0.148-windows-x64.intunewin. Keep the prep tool itself outside C:\AgentWatchPkg, because everything in that folder is packaged.

Alternative — settings as a platform script. If you would rather keep the settings separate from the app (for example to rotate the token without repackaging), use Devices → Scripts and remediations → Platform scripts → Add → Windows 10 and later, with Run this script using the logged on credentials No and Run script in 64 bit PowerShell Host Yes. A platform script cannot carry a file, so paste the contents of the downloaded .reg into it:

Terminal window
$reg = @'
<paste the full contents of agentwatch-connect.reg here>
'@
$f = "$env:TEMP\agentwatch-connect.reg"
Set-Content -Path $f -Value $reg -Encoding Unicode
& "$env:SystemRoot\System32\reg.exe" import $f /reg:64
exit $LASTEXITCODE

Then drop the reg.exe import lines from the Win32 install script. Intune runs platform scripts before Win32 apps, but the order does not matter anyway: the Connect service checks for its settings every minute.

Step 2 — add the Win32 app

Section titled “Step 2 — add the Win32 app”

  1. In the Microsoft Intune admin center, go to Apps → All Apps → Create, choose Windows app (Win32), and Select.

  2. App information: Select app package file, choose the .intunewin. Name: AgentWatch Connect. Publisher: Iterate Studio Inc.

  3. Program:

    Field Value
    Installer type Command line
    Install command %SystemRoot%\Sysnative\WindowsPowerShell\v1.0\powershell.exe -ExecutionPolicy Bypass -NoProfile -File .\Install-AgentWatchConnect.ps1
    Uninstall command "C:\Program Files\AgentWatch Connect\unins000.exe" /VERYSILENT /SUPPRESSMSGBOXES /NORESTART
    Install behavior System
    Device restart behavior No specific action
    Allow available uninstall No

    The Sysnative path starts 64-bit PowerShell from the Intune management extension; together with /reg:64 it guarantees the values land in HKLM\SOFTWARE\Policies\AgentWatch\Connect and not under WOW6432Node, where Connect does not look. If your tenant offers Installer type → PowerShell script, you can upload Install-AgentWatchConnect.ps1 there instead.

  4. Requirements: Operating system architecture x64; Minimum operating system Windows 10 1809 (Setup refuses older builds).

  5. Detection rules: Manually configure detection rules → Add → Registry:

    • Key path: HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Uninstall\{8C7A4F0E-5C2A-4A9D-9E8B-2F4C5D3E1A6B}_is1
    • Detection method: Key exists

    That is the installer’s fixed product ID, so detection survives upgrades. If you will upgrade through Intune rather than AgentWatch (see How do upgrades work?), use Value name DisplayVersion, Detection method version comparison, greater than or equal to the version you packaged — so a computer that already updated itself is not “repaired” back to an older version.

  6. Assignments: Required, group AgentWatch – Windows. Assign to a device group: the install needs administrator rights, and Microsoft notes that a user-targeted Win32 app that needs them fails for standard users.

  7. Review + create.

Setup runs under SYSTEM, so nobody sees a UAC prompt. In that one run it installs Connect under C:\Program Files\AgentWatch Connect, trusts the Connect certificate for the whole computer and registers the AgentWatchConnect service, which starts immediately and at every boot. /NOTRAY=1 stops Setup from starting a tray in the SYSTEM session; the tray icon appears at the employee’s next sign-in and only shows status.

Keep employees as standard users: uninstalling needs administrator rights. With a Required assignment, if an administrator removes Connect, the detection rule stops matching and Intune installs it again.

How do I deploy to macOS?

Section titled “How do I deploy to macOS?”

Two pushes to the same device group, in either order. Connect waits for the profile and redirects nothing until macOS trusts the certificate, so browsing is never broken in between.

Step 1 — push the profile

Section titled “Step 1 — push the profile”

Upload the agentwatch-connect.mobileconfig you downloaded from Deploy with an MDM unchanged. It carries:

  • your organization’s AgentWatch Connect root certificate (com.apple.security.root). This is why a profile is needed at all: since macOS 11, a certificate is trusted silently only when an MDM installs it in a profile — no installer, script or root process can do it;
  • the Connect settings (ServerURL, EnrollmentToken, EmailDomain);
  • Chrome, Edge and Brave policies: DNS-over-HTTPS off, the built-in DNS client off, QUIC off — so browsers use the system resolver Connect steers;
  • a Firefox policy: trust enterprise roots (ImportEnterpriseRoots), DNS-over-HTTPS off;
  • not removable by the user.

In the Intune admin center:

  1. Devices → macOS → Configuration → Create → New policy.
  2. Profile type: Templates → Custom. Create.
  3. Basics: name AgentWatch Connect.
  4. Configuration settings: Custom configuration profile name AgentWatch Connect; Deployment channel Device channel; Configuration profile file — upload agentwatch-connect.mobileconfig.
  5. Assignments: group AgentWatch – macOS. Review + create.

The deployment channel cannot be changed after saving. Device channel is required: it installs the certificate for the whole Mac and produces /Library/Managed Preferences/ai.iterate.agentwatch-connect.plist, the file Connect reads.

The profile must be pushed by Intune. A profile a user installs by double-clicking it does not make the certificate trusted silently, and Agent Fleet will keep showing that Mac with CA trusted off.

Optional: if macOS short names do not match email addresses, add <key>Email</key><string>{{mail}}</string> to the ai.iterate.agentwatch-connect payload before uploading (check the file with plutil -lint agentwatch-connect.mobileconfig). Intune tokens are case-sensitive, and a Mac with no primary user leaves the token unsubstituted, which Connect ignores safely.

Step 2 — push the installer package

Section titled “Step 2 — push the installer package”
  1. Apps → macOS → Create (or Apps → All Apps → Create, platform macOS), macOS app (PKG), Select.
  2. Select app package file → AgentWatch-Connect-<version>-macos-universal.pkg. Name AgentWatch Connect, publisher Iterate Studio Inc.
  3. Requirements: Minimum Operating System macOS 12.
  4. Detection rules: Ignore app version Yes if you will update through AgentWatch (Connect updates itself in place), No if you will update through Intune. Included apps: bundle ID ai.iterate.agentwatch-connect, version as shown (for example 1.0.148).
  5. Assignments: Required, group AgentWatch – macOS. Review + create.

The package is signed with Iterate’s Developer ID Installer certificate and notarized by Apple. It installs AgentWatch Connect.app into /Applications and, as root and with no prompt, a LaunchDaemon that runs Connect for the whole Mac (“machine mode”) plus a login item that starts the menu-bar app for each user. Nobody opens the app and nobody enters an administrator password.

Use the .pkg from Connect 1.0.148 or later. The .dmg is for installing by hand: it still asks for an administrator the first time interception switches on, so it is not an MDM install.

What happens after the push?

Section titled “What happens after the push?”
  1. The Connect service enrolls by itself. It retries every minute, so a profile that arrives after the installer, a network that is not up at boot, or an employee who signs in later all work without anyone stepping in.
  2. Interception switches on by itself within about a minute of enrollment, and stays on.
  3. The tray / menu-bar icon appears and shows Connected. On managed computers it only shows status — it does not open a setup window.

No computer restart is needed: Setup runs with /NORESTART and the Win32 app is set to No specific action. Browsers: anything opened after interception starts is covered; tabs that were already open pick it up within about a minute; Firefox picks it up at its next restart. There is nothing for anyone to click.

What does the employee see?

Section titled “What does the employee see?”
OS What happens Clicks needed
Windows The tray icon appears and shows Connected None
macOS The menu-bar icon appears and shows Connected None
Linux The tray icon appears in the top bar and shows Connected None

The only exception — a one-time sign-in code. If Connect could not derive an email that belongs to a provisioned employee (see How is each computer tied to an employee?), or the organization turned on Require sign-in to approve each computer, Connect shows a short code such as KQ7M-3XTP and opens the sign-in page in the default browser. The employee signs in with your normal sign-in (Microsoft Entra SSO if that is how your workspace signs in), checks the code and computer name, and clicks Approve — once per computer. The tray’s Open sign-in page reopens it.

Can an employee turn it off or remove it?

Section titled “Can an employee turn it off or remove it?”
  • Turning interception off: no. On a computer with managed settings the tray hides the off switch, and Connect refuses any request to turn interception off — from the app, a script or another program — with 403 managed by your organization. If something removes the redirection anyway, it is switched back on at the next check-in.
  • Uninstalling: needs administrator rights, and a Required assignment reinstalls it. Set Allow available uninstall to No so the Company Portal does not offer it.

How do I verify the rollout?

Section titled “How do I verify the rollout?”

  1. On one test computer:

    Terminal window
    # Windows - 64-bit PowerShell
    reg query "HKLM\SOFTWARE\Policies\AgentWatch\Connect"      # ServerURL, EnrollmentToken, EmailDomain as REG_SZ
    Get-Service AgentWatchConnect                               # Running
    & 'C:\Program Files\AgentWatch Connect\agentwatch-connect.exe' status
    Terminal window
    # macOS
    sudo profiles list | grep -i agentwatch                                        # the profile is installed
    plutil -p "/Library/Managed Preferences/ai.iterate.agentwatch-connect.plist"   # ServerURL, EnrollmentToken, EmailDomain
    sudo launchctl print system/ai.iterate.agentwatch-connect | grep state         # state = running
    tail -n 20 /Library/Logs/AgentWatch/connect.log

    In Intune, the app’s Device install status should read Installed and the profile’s status Succeeded.

  2. In AgentWatch, open Agent Fleet. The computer appears within about a minute, Online, with its employee, platform, Connect version and the proxy, certificate (CA trusted) and redirection columns active.

  3. Send a harmless prompt. In a new browser tab on the test computer, ask a public AI assistant something like What is the capital of France?. Within a few seconds it appears in Usage Insights under that employee.

Then widen the group in steps.

How do upgrades work?

Section titled “How do upgrades work?”

Two ways; both work. Pick one per group of computers.

From AgentWatch (no repackaging). Agent Fleet → Fleet controls → Connect updates:

Policy Effect
Automatic — everyone Every computer takes the new version the server offers
Selected users only Only the employee emails in the Selected users list receive updates — try a new version on a few people first
Paused — no updates No computer updates

Check for updates now makes computers check immediately: Connect 1.0.148 or later within about 30 seconds, older versions once a day. Updates download in the background and install when the computer is idle, so a response in progress is not cut off:

  • macOS and Linux swap in the new Connect binary, and roll back automatically if the new version cannot reach the server within 90 seconds.
  • Windows (Connect 1.0.148 or later) runs the signed Setup installer silently from the Connect service — no prompt for the employee — and only if the installer is validly signed by the same publisher as the Connect already installed.
  • Windows computers on Connect 1.0.147 or earlier make one automatic step to 1.0.148 using the signed Connect binary, and update through the installer from then on.

The policy governs automatic updates. An employee with administrator rights can still run a newer installer by hand.

Keep the Intune detection rules version-tolerant (registry Key exists on Windows, Ignore app version Yes on macOS) so Intune does not fight the update.

From Intune (change control). Windows: package the new Setup .exe (with the same .reg and script) the same way and add it as a new Win32 app that supersedes the old one, with Uninstall previous version off (Setup upgrades in place). macOS: edit the PKG app and upload the new .pkg.

Which to choose. Use Intune when IT wants every software change to go through its own change process and reporting; otherwise use the AgentWatch policy, which needs no repackaging, supports a canary group and rolls back by itself. Do not use both on the same computers without a reason: if you upgrade through Intune, set Connect updates to Paused — no updates for those users.

How do I pause interception?

Section titled “How do I pause interception?”
Scope Control Effect
Everyone Agent Fleet → Fleet controls → Interception for everyone → Pause for everyone Interception switches off on every computer in the organization within about 30 seconds. The button becomes Resume interception
One person the Monitored toggle on their row in the Agent Fleet table Exempts that user; click again to resume
One computer, permanently Remove it from the profile/app assignment (or assign Uninstall) Connect is no longer managed there

Pausing switches off redirection; it does not uninstall anything, and resuming needs no Intune action.

How do I uninstall Connect?

Section titled “How do I uninstall Connect?”
Computer Intune
Windows Change the Win32 app’s assignment from Required to Uninstall for the device group. Intune runs the app’s uninstall command, "C:\Program Files\AgentWatch Connect\unins000.exe" /VERYSILENT /SUPPRESSMSGBOXES /NORESTART
macOS Devices → macOS → Shell scripts → Add, run as root (Run script as signed-in user: No): "/Applications/AgentWatch Connect.app/Contents/Resources/uninstall.sh". Then remove the PKG app’s assignment (Intune does not uninstall PKG apps by itself)
Linux Intune does not deploy Linux software; run sudo apt remove agentwatch-connect (or sudo agentwatch-connect uninstall for the one-liner install)

To also remove every employee’s personal settings, add --purge on macOS (uninstall.sh --purge) and on Linux use apt purge. On Windows, package a script that runs & "C:\Program Files\AgentWatch Connect\agentwatch-connect.exe" uninstall --purge before unins000.exe, and use it as the app’s uninstall command.

What stays, on purpose. The uninstall removes everything Connect installed — the service, the hosts-file redirection, the Connect certificate, the browser DNS-over-HTTPS policies, its helpers — and prints what it leaves:

  • the settings you pushed (HKLM\SOFTWARE\Policies\AgentWatch\Connect and the legacy ...\Iterate\AgentWatchConnect, the macOS profile and its Managed Preferences, /etc/agentwatch/connect.json). They belong to the MDM: remove the profile / unbind the policy, or the next install enrolls by itself again. The organization certificate in the macOS profile is removed with the profile.
  • each employee’s own settings (~/.agentwatch-connect), so a reinstall keeps them. To remove those too, use --purge (Linux apt purge).

Windows computers uninstalled with Connect older than 1.0.150 kept the hosts-file entries and the certificate, which breaks ChatGPT and Claude in the browser. See How do I uninstall Connect? for the one-time cleanup.

Troubleshooting

Section titled “Troubleshooting”
Symptom Cause Fix
Settings download fails; the console says to generate an enrollment token The organization has no enrollment token yet Agent Fleet → Agent Connect Settings → Regenerate token, then download again
Computer never appears in Agent Fleet The settings are missing: written to the 32-bit hive HKLM\SOFTWARE\WOW6432Node\Policies\… (32-bit reg.exe / PowerShell writes there), the .reg was not in the package, or there is no enrollment token / the token was regenerated Use the Sysnative install command and reg.exe import … /reg:64; check with reg query "HKLM\SOFTWARE\Policies\AgentWatch\Connect" from 64-bit PowerShell; download fresh settings if the token changed
Windows values present but ignored Created as DWORD/multi-string, or under HKEY_CURRENT_USER Import the downloaded .reg, which writes REG_SZ under HKLM\SOFTWARE\Policies\AgentWatch\Connect
Win32 app fails with a non-zero exit code Script error (see C:\ProgramData\Microsoft\IntuneManagementExtension\Logs\AppWorkload.log) or Setup failed (C:\Windows\Temp\AgentWatch-Setup.log) Fix the reported cause; an antivirus block on Connect’s browser-compatibility helper is the most common — allow C:\Program Files\AgentWatch Connect\curl-impersonate\curl-impersonate.exe
Win32 app shows Failed for standard users Assigned to a user group Assign to a device group
Mac shows CA trusted = No in Agent Fleet The profile is not installed, was installed by hand (double-clicked), or went to the User channel Push the profile from Intune with Device channel; Connect redirects nothing until macOS trusts the certificate
Mac asks for an administrator password It was installed from the .dmg, or with a .pkg older than 1.0.148 Push the 1.0.148+ .pkg as a macOS app (PKG)
Employee sees a sign-in code Connect could not derive an email that is a provisioned employee ({{mail}} not substituted, no EmailDomain, or the address is not an employee), or Require sign-in to approve each computer is on Set Employee email domain before downloading the settings (or add Email), or provision the employee in Employee Management; the employee can also just approve once
Computer Online but no prompts in Usage Insights The tab was open before interception started (Firefox: not restarted since) Wait a minute and resend from a new tab; Firefox picks it up at its next restart
Interception off on every computer Pause for everyone is on Agent Fleet → Fleet controls → Resume interception
A new version never arrives Connect updates is Paused, or the user is not in Selected users Change the policy, then Check for updates now
Intune keeps reinstalling an older version A version-exact detection rule after Connect updated itself Use Key exists (Windows) or Ignore app version: Yes (macOS), or upgrade only through Intune
unable to get local issuer certificate, computer never appears A TLS-inspecting proxy re-signs the connection to AgentWatch Connect 1.0.147 or later trusts the OS roots; or exempt the AgentWatch address from inspection

Connect logs: Windows C:\ProgramData\AgentWatch\logs\service.log; macOS /Library/Logs/AgentWatch/connect.log. Every enrollment is in Settings → Audit Logs as agent.device_enrolled.

Sources and references

Section titled “Sources and references”