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 the one-time employee sign-in authenticates against. 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. Expiry is 30, 60, 90, or 180 days, or never, which is the 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 an install command that can carry MSI properties, or a separate field for them
- 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
Both installers carry a fixed name and always resolve to the latest published release, so no version appears in a filename or an install command.
Download both from Devices → Deployment. The download buttons there point at the latest release, and All builds on GitHub beside them lists every release if you need to pin one. macOS also needs the configuration profile from the same page, which is generated with your enrollment token, organization id, 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.
The Windows install properties
The MSI installs a background service and a tray app. It takes its configuration as MSI properties rather than from a profile, so Devices → Deployment generates the properties as one line with your values already in it:
Paste that line wherever your MDM takes MSI properties. In Intune it is the line-of-business app’s Command-line arguments field. For an MDM that wants a complete install command, append it to the silent install:
Copy the properties rather than retyping them: they carry your enrollment token, and the dashboard refuses to generate them at all when a value holds a quote or a control character, instead of emitting a line msiexec would misparse. All four are required. Without them the MSI still installs, but the client runs local-only and the device never appears in Devices.
The Merge icon appears in the signed-in employee’s system tray within a minute of the install completing, and at every sign-in after that. The employee clicks Sign in there once to bind their identity to the device.
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 the MSI install properties 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, DashboardUrl, and PolicyMode already filled in, and the Windows install properties carry the first four, 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: the four MSI properties ENROLLMENTTOKEN, APIBASEURL, ORGSLUG, and DASHBOARDURL, passed at install time. The installer stores them under HKEY_LOCAL_MACHINE\SOFTWARE\Merge\WorkforceClient\Deployment, readable only by SYSTEM and Administrators. The optional keys in this table apply to macOS only; on Windows, enforcement mode comes from the dashboard.
On macOS, 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.
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.
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. The client refuses to mint until the device resolves to an employee
- The device appears as Unattributed in Devices, and the fleet summary’s Unattributed tile filters the table to exactly those devices. Not reporting and Exposed keys are the other two tiles that filter this way
- Discovery still runs, attributed to the device, and re-attributes once identity resolves
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 issued by Merge, not chosen on the device. At enrollment Merge generates a 32-byte credential and stores only its hash; the client keeps its copy in the macOS Keychain or the Windows TPM and never writes it anywhere an employee would look. It authenticates one machine under its own
Authorization: Devicescheme, carries no user identity, and is rejected by every endpoint that expects a user or an organization key - The hardware identifier is a derived key, not a claim. The serial is stored as an organization-salted SHA-256 and is what identifies the device across enrollments. A second enrollment on an existing serial drops the device’s attribution rather than inheriting it, so a reassigned or reimaged laptop starts unattributed until someone signs in
- 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 silent for 30 minutes appears in the fleet view as not 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
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. The one-time sign-in asks the employee to authorize identification only, and says so on the consent screen: it grants no access to tools, skills, or knowledge, and the token it issues is refused at the MCP endpoint. Nobody picks tools from a list, so 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:
Deploy the profile before the package. A Mac that gets the package first has no configuration and no file access, so the client cannot enroll and discovery finds nothing until the profile lands.
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. The client does not update itself yet. To upgrade, publish the newer package through the same assignment and stage it the same way.
A staged rollout that works
- Deploy the profile and package to 5-10 machines in your own IT team, with
PolicyModeset toobserveon macOS - 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
- Let discovery run for a week and read what it found. It needs no configuration and reports from the moment a device enrolls
- Decide the panel sections your employees should see, on Devices → Desktop client preview
- Set enforcement to Enforce when you are ready. The setting is organization-wide, is recorded now, and takes effect on the fleet once policy signing ships. Remove the
PolicyModeceiling wave by wave after that