Plan your deployment
Read this once, then follow the guide for your MDM. Every MDM guide sets the same values; only the mechanism differs.
Prerequisites
- SSO and SCIM are connected. Identity resolves against employees synced by SCIM, and their access comes from their Groups. SSO is what makes the zero-touch identity path work. Set both up first and confirm your employees appear in Agent Handler
- You have an enrollment token. Generate one in Devices → Deployment. It is organization-scoped, so one token covers your whole fleet. The raw value is shown once, at creation, and carries an
mwf_enroll_prefix so a leaked one is easy to catch in secret scanning; treat it as a secret and distribute it only through MDM. You can set an expiry when you generate it (it never expires by default); an expired token stops new devices from enrolling but never affects devices already enrolled, so rotating is: generate a new token, update your MDM, then revoke the old one - Your MDM can deploy packages and configuration. macOS needs a configuration profile alongside the package. Windows needs registry values or MSI properties
- You know your EDR and network client. The client coexists with CrowdStrike, Defender for Endpoint, SentinelOne, Zscaler, Netskope, Cisco Secure Access, and Cloudflare WARP. If you run something else, deploy to a canary group first and confirm network behavior
Packages
Download both from Devices → Deployment, along with the macOS configuration profile, which is generated with your enrollment token, organization slug, and API URLs already filled in. Windows 10 reached end of support in October 2025, so Windows 10 devices need Extended Security Updates enrollment to keep receiving OS patches.
Which guide to follow
Jamf Pro and Mosyle manage Apple platforms only, so a mixed fleet needs two guides. Pick one per platform.
Whichever MDM you use, identity resolves the same way, explained under Assigning identity at deployment.
Configuration keys
The client reads its configuration from managed preferences on macOS and from policy registry values on Windows. It never prompts the employee for any of it. You rarely set the required keys by hand: the profile from Devices → Deployment downloads with EnrollmentToken, OrgSlug, ApiBaseUrl, and DashboardUrl already filled in, so editing is only needed for the optional keys below.
No key here sets employee identity, deliberately. See Assigning identity at deployment below.
macOS: preference domain com.merge.workforceclient, delivered as a managed preferences payload.
Windows: HKEY_LOCAL_MACHINE\SOFTWARE\Policies\Merge\WorkforceClient, one REG_SZ per key. The same names can be passed as uppercase MSI properties at install time, for example ENROLLMENTTOKEN.
Set PolicyMode to observe in your MDM for the first wave. It is a hard ceiling the dashboard cannot override, so it gives you a way to prove the client is safe on your fleet before any enforcement can take effect anywhere.
Assigning identity at deployment
Deploying the client binds the device to your organization. Identity, meaning which employee that device belongs to, is resolved separately, by Merge, and costs the employee at most one click.
Employee sign-in
After the client installs, it shows a one-time sign-in prompt in the menu bar. The employee completes the same OAuth flow the Merge CLI uses, once, and Merge binds the resulting verified identity to that device and operating system user. The sign-in is authenticated by your IdP, so it proves who the employee is rather than asserting it from an inventory record.
The signed-in employee has to match someone synced by SCIM. A sign-in that resolves to a person SCIM has never provisioned has no employee record to attach to.
Zero-touch identity is on the roadmap
Two silent mechanisms are planned so the employee does not even see the prompt: silent SSO (a token for the signed-in OS user, via Entra join on Windows or Platform SSO on macOS) and MDM-assigned identity (Merge reading the device-to-user assignment from your MDM’s API by serial number). Until they ship, the one-time sign-in is how every device resolves identity.
No configuration file can set identity, deliberately
A managed preferences plist and an HKLM policy value are both writable by root and by a local administrator. If identity came from a config file, any employee with local admin could claim to be a colleague. So the client has no configuration key that sets identity. ExpectedIdentity exists as an optional hint for mismatch alerting only, and is ignored as an identity source.
Until identity resolves
- No Gateway key and no MCP configuration are written for that operating system user
- With
gateway_onlyenforcement enabled, direct model provider endpoints are blocked, so there is no ungoverned path either - The device appears as unattributed in Devices
- Discovery still runs, attributed to the device, and re-attributes once identity resolves
A resolved identity survives outages
A device with a resolved identity that cannot reach Merge keeps working from its cached signed policy for up to 14 days, so an API or IdP outage never becomes a fleet-wide AI outage. A device that has never resolved one is blocked.
Identity is per operating system user, so shared machines need no extra configuration. Revoking an employee in your IdP invalidates their session and the client blocks at its next check-in, within minutes.
Identity integrity
Employees cannot impersonate each other, and this is enforced structurally rather than by policy.
- No identity input on the endpoint. Identity is an IdP-issued token whose signature Merge verifies. There is no file, registry value, or setting an employee can edit to become someone else. Editing anything the client reads changes nothing about who it is
- The device credential is hardware-bound. At enrollment the client generates a keypair in the Secure Enclave on macOS or the TPM on Windows and registers the public key. The private key is non-exportable, so it cannot be copied to another machine even by a local administrator. Every request is signed with it
- The hardware identifier is verified, not accepted. A device claiming another machine’s serial number does not inherit that machine’s identity: the serial is checked against the registered device key. A second enrollment on an existing serial raises an alert
- Usage attribution does not depend on the endpoint. Governed AI usage is attributed by the Gateway key at Gateway, not on the device. Even a fully compromised endpoint cannot make one employee’s requests appear as another’s
Hiding usage
An employee cannot quietly disable the client either:
- Stopping or removing it requires administrator rights, and doing so is reported. The client heartbeats every five minutes, and a device that stops reporting appears in the fleet view as non-reporting with the time it went quiet
- Blocking the Merge endpoint does not help. A client that cannot reach Merge keeps working for the 14-day grace window and then fails closed, so with enforcement enabled the AI access stops. Hiding from Merge costs the employee the AI, which is the intended incentive
- Your MDM reinstalls it. Every supported MDM re-evaluates required software, so a removed client comes back at the next check-in
Local administrator is the honest limit
On a machine where the employee is a local administrator, no user-mode software can be tamper-proof, and this guide does not claim otherwise. The guarantee is that identity cannot be forged and tampering cannot be hidden. If you need enforcement you can fully rely on, remove local admin rights on that fleet.
Tool access is granted by your organization
Once identity resolves, Merge connects that employee’s approved tools automatically, from the Groups you configured, with no employee consent prompt. That is what makes the deployment genuinely zero-touch: a laptop arrives set up rather than arriving with a checklist.
If you operate in a region that expects individual notice before an employer connects tools on someone’s behalf, share the privacy reference and the employee FAQ as part of your rollout communication.
macOS permissions
macOS blocks the client’s network visibility, process visibility, and file access behind user prompts unless your MDM pre-approves them. The configuration profile from the dashboard contains all four payloads:
There is no separate Endpoint Security payload; ES access comes from the system extension approval plus full disk access. Deploy the profile before the package. If the package installs first, the employee sees the extension activation prompt; the profile still approves the extension when it lands, but only after the prompt has been shown.
Stage the rollout
Stage the rollout with your MDM’s own scoping, there is no separate mechanism to configure. Assign the profile and package to a small canary group first, widen after a soak, then cover the fleet. Once installed, the client keeps itself current through its own signed update channel, so the install is the only step you stage.
You do not need to mirror rings as MDM smart groups. One package deployed to everyone is enough; the client asks Merge which version its ring should be on.
A staged rollout that works
- Deploy the profile and package to 5-10 machines in your own IT team, with
PolicyModeset toobserveand every module off except software provisioning - Confirm every device appears in the fleet view against the right employee, with the identity tier that resolved it, and that a provisioned employee can run Claude Code through Gateway with Agent Handler tools
- Turn on shadow AI logging. Let it run for a week and read the report
- Turn on enforcement modules in
observemode, organization-wide. Review what would have been reverted or blocked - Move enforcement to
revert, canary group first, then remove thePolicyModeceiling wave by wave - Move to
blockonly after a full week inrevertwith no unexplained drift