Plan your deployment
Read this once, then follow the guide for your MDM. Every guide sets the same values in a different way. In the dashboard, Devices → Deployment walks through the same work in three steps: Configure your desktop client, Deploy to your team, and Verify deployment.
Prerequisites
- SSO and SCIM are connected. Identity resolves against employees synced by SCIM, and access comes from their Groups. The one-time employee sign-in authenticates through SSO. Confirm your employees appear in Merge
- You have an enrollment token. Generate one in Devices → Deployment. One token covers your whole fleet. Its value is shown once, and its
mwf_enroll_prefix makes a leak easy to catch in secret scanning. Treat it as a secret and distribute it only through MDM.- Expiry: 30, 60, 90, or 180 days, or never (the default)
- An expired token stops new enrollments but never affects enrolled devices
- To rotate: 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 works alongside CrowdStrike, Defender for Endpoint, SentinelOne, Zscaler, Netskope, Cisco Secure Access, and Cloudflare WARP. For anything else, deploy to a canary group first and check network behavior
Packages
Both installers have fixed names and always point to the latest release, so no version appears in a filename or install command.
Download both from Devices → Deployment. macOS also needs the configuration profile from the same page, pre-filled with your enrollment token, organization id, and API URLs. The profile and the Windows install properties include your token only while a newly generated one is on screen, so generate the token in the same visit. Windows 10 reached end of support in October 2025, so those devices need Extended Security Updates to keep getting OS patches.
The Windows install properties
The MSI installs a background service and a tray app. It takes its configuration as MSI properties, and Devices → Deployment generates them as one line with your values filled in:
Paste that line wherever your MDM takes MSI properties, such as the Command-line arguments field of an Intune line-of-business app. If your MDM wants a full install command, append it to the silent install:
Copy the properties instead of retyping them, since they carry your enrollment token. The dashboard refuses to generate them if a value contains a quote or control character that 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 employee’s system tray within a minute of install, and at every sign-in after. The employee clicks Sign in there once to bind their identity to the device.
- Microsoft Edge WebView2: the MSI downloads it if it is missing and rolls back if that fails, so on a restricted network deploy it through your MDM first
- A non-elevated session: browser sign-in fails on images with UAC turned off and in built-in Administrator sessions
- Service configuration: a policy that stops the MSI configuring its service rolls the install back
Which guide to follow
Jamf Pro and Mosyle manage Apple platforms only, so a mixed fleet needs two guides. Pick one per platform.
The dashboard’s Choose your MDM step lists Microsoft Intune, Jamf Pro, Iru, and Other. For Mosyle, Configuration Manager, and Workspace ONE, pick Other and follow the guide here.
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, and never prompts the employee. The generated profile already fills in EnrollmentToken, OrgSlug, ApiBaseUrl, DashboardUrl, and PolicyMode, and the Windows properties carry the first four, so you only edit the optional keys.
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. The installer stores them under HKEY_LOCAL_MACHINE\SOFTWARE\Merge\WorkforceClient\Deployment, readable only by SYSTEM and Administrators. The optional keys are macOS-only. On Windows, enforcement mode comes from the dashboard.
On macOS, set PolicyMode to observe for the first wave. The dashboard cannot override it, so you can prove the client is safe before any enforcement takes effect.
Assigning identity at deployment
Deploying the client binds the device to your organization. Merge resolves which employee it belongs to separately, at a cost of one click for the employee.
Employee sign-in
After install, the client shows a one-time sign-in prompt in the menu bar. The employee completes the same OAuth flow the Merge CLI uses, and Merge binds the verified identity to that device and operating system user. Your IdP authenticates the sign-in, so it proves who the employee is instead of trusting an inventory record.
The employee must be synced by SCIM. A sign-in for someone SCIM never provisioned has no employee record to attach to.
Two planned mechanisms will remove the prompt: silent SSO (via Entra join on Windows or Platform SSO on macOS) and MDM-assigned identity (Merge reads the device’s assigned user from your MDM’s API by serial number). Until they ship, every device resolves identity through the one-time sign-in.
A local administrator can edit a managed preferences plist or an HKLM value. If identity came from a config file, any employee with local admin could pose as a colleague, so no configuration key sets identity. ExpectedIdentity is only a hint for mismatch alerts.
Until identity resolves
- The client writes no Gateway key or MCP configuration for that operating system user
- The device appears as Unattributed in Devices. The fleet summary’s Unattributed tile filters the table to those devices
- Discovery still runs against the device, and moves to the employee once identity resolves
A device with a resolved identity that cannot reach Merge keeps working from its cached policy for up to 14 days, so an API or IdP outage does not cut off AI across the fleet. A device that never resolved an identity is blocked.
Identity is per operating system user, so shared machines need no extra setup. Revoking an employee in your IdP ends their session, and the client blocks them at its next check-in, within minutes.
Identity integrity
Employees cannot impersonate each other. This is built into the design, not a policy setting.
- No identity input on the laptop. Identity is an IdP-issued token whose signature Merge verifies. No file, registry value, or setting changes who the client says the employee is
- Merge issues the device credential. At enrollment Merge generates a 32-byte credential and stores only its hash. The client keeps its copy in the macOS Keychain or Windows TPM. It authenticates one machine under its own
Authorization: Devicescheme, carries no user identity, and is rejected anywhere a user or organization key is expected - The hardware identifier is derived, not claimed. The serial is stored as an organization-salted SHA-256 and identifies the device across enrollments. Re-enrolling the same serial clears its employee, so a reassigned or reimaged laptop stays unattributed until someone signs in
- Usage is attributed at Gateway, not on the laptop, by the employee’s Gateway key. Even a compromised laptop cannot make one employee’s requests look like another’s
Hiding usage
An employee cannot quietly disable the client:
- Stopping or removing it needs administrator rights, and is reported. The client heartbeats every five minutes, and a device silent for 30 minutes shows as not reporting, with the time it went quiet
- Blocking Merge does not help. A client that cannot reach Merge works for 14 days, then fails closed, so with enforcement on, AI access stops
- Your MDM reinstalls it at the next check-in
If the employee is a local administrator, no user-mode software is tamper-proof. The guarantee is that identity cannot be forged and tampering cannot be hidden. For enforcement you can fully rely on, remove local admin rights.
Tool access is granted by your organization
Once identity resolves, Merge connects the employee’s approved tools from the Groups you configured. The sign-in consent screen asks for identification only: it grants no access to tools, skills, or knowledge, and its token is refused at the MCP endpoint. Nobody picks tools from a list, so the laptop arrives set up.
If your region expects individual notice before an employer connects tools for someone, include the privacy reference and employee FAQ in your rollout communication.
macOS permissions
macOS puts network visibility, process visibility, and file access behind user prompts unless your MDM pre-approves them. The dashboard’s configuration profile contains all four payloads:
Deploy the profile before the package. Without it, the client cannot enroll and discovery finds nothing.
Stage the rollout
Use your MDM’s own scoping. Assign the profile and package to a small canary group, 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. On Windows, an employee signed in during the upgrade keeps the old tray app until their next logon.
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, and that a provisioned employee can run Claude Code through Gateway with Agent Handler tools
- Let discovery run for a week and review what it found
- Decide the panel sections your employees should see, under Devices → Deployment → Configure your desktop client
- Set enforcement to Enforce when ready. The organization-wide setting is saved now and takes effect once policy signing ships. Then lift the
PolicyModeceiling wave by wave