> This page is for Workforce.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.merge.dev/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.merge.dev/_mcp/server.

# Roll out models

> Compare the Workforce desktop client and employee self-setup for rolling Merge Gateway out across a company, with per-client coverage for each supported AI client.

**Applies to:** Merge Gateway

Pointing one machine at Gateway takes two minutes: a base URL, an API key, and a model name. Pointing every machine at it means deciding how that configuration reaches each machine, and what happens when someone changes it back. There are two paths, and most companies run both: the desktop client for the fleet, and self-setup for everything the client does not reach.

Governance is why you do this: routing policies, spend caps, model restrictions, and a per-person request log. Employee experience is why it lasts. A rollout that takes tools away pushes the work to personal accounts, where you see none of it.

> **Your MDM deploys the client, not the configuration**
>
> Use your MDM to install the desktop client, and let the client write each AI tool's config. Pushing Gateway URLs and keys from your MDM instead means a script per client, drift between check-ins, and no per-employee attribution. See [Plan your deployment](/merge-workforce/devices/deployment-overview) for the Jamf, Intune, Mosyle, Workspace ONE, and Configuration Manager mechanics.

## Decide the inputs once

Every AI client asks for the same three values.

| Input          | Value                                                                                                                                                    | Fleet guidance                                                                                                                         |
| -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| **Base URL**   | `https://api-gateway.merge.dev/v1/openai` for OpenAI-compatible clients, `https://api-gateway.merge.dev/v1/anthropic` for Claude Code and Claude Desktop | Same for everyone. Sending an Anthropic client to the OpenAI prefix is the most common setup mistake                                   |
| **API key**    | Minted per employee by the desktop client, or a project API key from a project's **API keys** tab                                                        | See the key strategy below                                                                                                             |
| **Model name** | `provider/model`, or `default_routing`                                                                                                                   | Use `default_routing`, so model choice lives in your [routing policy](/merge-workforce/models/routing) instead of in every config file |

### Choose your key strategy first

The key decides who gets attributed and which budget applies.

* **Per-employee, provisioned automatically.** The best option. The desktop client and the [Workforce CLI](/merge-workforce/rollout/workforce-cli) both do it, spend attributes to the person, and there is no key to hand out. The client only mints a key once the device resolves to an employee.
* **Project key per team.** The [project](/merge-workforce/models/budget)'s routing policy and budget apply automatically. Use this for self-setup, where nothing mints keys for you.
* **Shared organization key.** No per-person attribution and no per-team budget. Fine for a pilot, not for a fleet.

Anyone can read a key that lands on their laptop. A leaked project key is limited to one budget and policy and rotates without touching the fleet, which is why project keys beat an organization key. Never hand out an organization key that also has Management API access.

## Compare the two paths

|                                           | Desktop client                                                                   | Self-setup                                  |
| ----------------------------------------- | -------------------------------------------------------------------------------- | ------------------------------------------- |
| **Who configures the machine**            | The Merge client                                                                 | The employee                                |
| **Prerequisite**                          | MDM-managed fleet, SSO and SCIM connected                                        | None                                        |
| **Clients covered**                       | Claude Code and Codex CLI                                                        | All nine, Cursor partially                  |
| **Per-employee attribution**              | Yes, automatic                                                                   | Yes through the Workforce CLI, otherwise no |
| **Survives an employee changing it back** | Not yet: enforcement is not in force, and employees can disconnect from the tray | No                                          |
| **Shadow AI visibility**                  | Yes                                                                              | No                                          |
| **Effort to stand up**                    | Higher, once                                                                     | Lowest, per employee                        |

A good default: the desktop client for Claude Code and Codex CLI, and self-setup for every other client and anyone the client has not reached yet.

## Path 1: the Merge desktop client

The client is a background service you deploy through your MDM. It mints each employee's Gateway key, routes their AI clients, and reports what AI tooling is installed. It needs an MDM-managed fleet, because some of the macOS permissions it uses can only be granted by a configuration profile.

#### Connect SSO and SCIM

Identity resolves against [SCIM](/merge-workforce/provisioning/scim)-synced employees, and access follows their Groups. Confirm your employees appear in Merge first.

#### Generate an enrollment token and download the artifacts

In **Devices → Deployment**. One token covers the whole organization, and its value is shown once. Download the macOS package, the Windows installer, and the configuration profile, which comes pre-filled with your token, organization slug, and API URLs. [Plan your deployment](/merge-workforce/devices/deployment-overview) has the full key reference.

#### Deploy to a canary group in observe mode

Five to ten machines in your own IT team. `PolicyMode: observe` in your MDM is a device-level ceiling the dashboard cannot override, so nothing is enforced while you prove the client is safe.

#### Have those employees sign in once from the menu bar

Sign-in resolves identity and provisions their Gateway key. Claude Code and Codex CLI then each show a **Connect Gateway** button in the tray panel that switches them over in one click.

#### Confirm traffic is arriving

A provisioned employee runs Claude Code, and the request appears in the [Gateway dashboard](https://gateway.merge.dev) within a few seconds, attributed to them.

#### Expand in rings

Widen the deployment, then lift the `PolicyMode` ceiling wave by wave.

The client routes Claude Code and Codex CLI, the two clients whose Gateway settings it writes today. Route the rest, including Claude Desktop, Zed, OpenCode, and Factory Droid, with self-setup.

> **Enforcement is not in force yet**
>
> You can turn on automatic install and re-install, and the settings page records the choice, but the client does not act on it until production signing keys exist. Until then, **Connect Gateway** is what routes a client, and employees can undo it with **Disconnect** in the same row.

**Connect Gateway** also tags each request with the tool that sent it, in an `X-Merge-Harness` header (`claude_code` or `codex_cli`). [LLM calls](/merge-workforce/logs/gateway) shows it as **Harness** in the request detail. Tools connected on an older client version get the tag the next time **Connect Gateway** runs. The client reports the value itself, so treat it as a strong hint, not proof.

**Disconnect** removes the Gateway settings the client wrote, including that tag, so the tool calls its AI provider directly again. It keeps any personal API key the employee added since, and it does not revoke the Gateway key. That key stays valid until it expires, and the next **Connect Gateway** mints a new one.

## Path 2: self-setup

Employees configure their own tools. Use this for every client beyond Claude Code and Codex CLI, and for any machine the desktop client has not reached yet. Two things make it work:

1. **Credentials they do not have to ask for.** Terminal users can use the [Workforce CLI](/merge-workforce/rollout/workforce-cli): they sign in with your identity provider, get a per-device credential, and spend still attributes to them. Everyone else gets their team's project API key, posted where that team already looks.
2. **One link, not a wiki page.** Every client has a [setup guide](/merge-gateway/coding-agents/overview) that takes about five minutes.

Then check the Gateway dashboard to see who is actually routing. A team still flat after two weeks needs the desktop client, not another reminder.

Self-setup gives you coverage, not control. Anyone can stop routing by editing their config, and you will not know: a client that is not routing sends no telemetry, so no traffic looks the same as no work.

## Client coverage

* **Desktop client:** Claude Code and Codex CLI
* **Self-setup:** all nine clients with a [setup guide](/merge-gateway/coding-agents/overview): Claude Code, Codex, Claude Desktop, Zed, Continue.dev, OpenCode, Pi, Factory Droid, and Cursor in part
* **Neither:** Cursor. It stores its base URL and API key in encrypted app state entered through its GUI, so neither path can write them. Its agent mode does not accept a custom API key at all, so even a hand-configured Cursor routes only Ask and Plan traffic, and Tab autocomplete never routes. Restrict it through Cursor Business or Enterprise admin settings, or block the provider endpoints at your network

## Verify the rollout

Pushed configuration is not routed traffic. Check all three:

1. **The [Gateway dashboard](https://gateway.merge.dev).** Requests appear within a few seconds. It is the only proof that traffic is flowing.
2. **The client's own check.** Claude Code's `/status` should show `Auth token: ANTHROPIC_AUTH_TOKEN` and the Gateway base URL. Claude Desktop's **Test connection** runs discovery and a real inference request.
3. **Coverage.** Compare who is routing against your employee list. The fleet view does this for you, including devices that enrolled but never resolved an identity.

Finish all three on a canary group before widening. Configuration that landed everywhere but shows traffic from four people is being bypassed.

## Limits to tell your security team

* **Everything short of network blocking is client-side.** Anyone can edit their config, and **Disconnect** does it in one click. Until enforcement is in force, the client does not revert changes, so treat routing as opt-in today.
* **Only server-side controls cannot be bypassed from the laptop:** Gateway's authentication and your network egress policy. An unmanaged config cannot mint a Merge key.
* **Cursor never routes on a managed path,** and its agent mode and Tab never route at all.
* **Coverage is not enforcement.** Until direct provider endpoints are blocked, a routed client is one currently choosing to route.

## Next steps

#### [Plan your deployment](/merge-workforce/devices/deployment-overview)

The MDM mechanics for getting the desktop client onto the fleet

#### [Per-client setup guides](/merge-gateway/coding-agents/overview)

The exact configuration for each of the nine supported AI clients

#### [Roll out tools](/merge-workforce/rollout/tools)

The same question for tools, where some clients can make your endpoint the only one