> ## Documentation Index
> Fetch the complete documentation index at: https://docs.openwhispr.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Lock OpenWhispr with a managed device policy

> Use Jamf Pro or another MDM, the Windows registry, or root-owned files on Linux to keep OpenWhispr local-only, require sign-in, or turn off meeting recording.

A managed device policy is a setting you push to company computers so that people can't change it themselves. With one, you can:

* **keep OpenWhispr local-only**: speech-to-text and AI run on the computer itself, with no sign-in and no cloud
* **require sign-in**, so the app applies your OpenWhispr workspace's rules
* **turn off meeting recording**
* deploy a **full policy** that sets every control in one value

The device policy is free. It needs no OpenWhispr account, plan, or workspace. That includes the local-only lock.

> [!NOTE]
>
> Device policies need **OpenWhispr 1.12.0 or newer**. Older versions ignore them, so deploy 1.12.0 or newer before you deploy the policy.

## Where OpenWhispr reads the policy

Each operating system has its own place for it. The app reads only these places, so a person without admin rights can't create or change a policy.

| Platform | Where to deploy it | How |
| - | - | - |
| macOS | Preference domain `com.gizmolabs.openwhispr` | A configuration profile from Jamf Pro or another MDM |
| Windows | Registry key `HKLM\SOFTWARE\Policies\OpenWhispr` | Group Policy, Intune, or any tool that writes to the machine's registry |
| Linux | Folder `/etc/openwhispr` | Files owned by root, from your configuration tool |

On macOS, OpenWhispr reads only values that a configuration profile enforces. A value set with `defaults write` doesn't count. You can push the profile to the computer or to a user.

## The settings

| Setting | Type | What it does |
| - | - | - |
| `RequireSignIn` | true / false | `false` makes OpenWhispr local-only, with no sign-in. `true` means people must sign in before they can use the app. |
| `DisableMeetingRecording` | true / false | `true` turns off meeting recording. `false` on its own does nothing. |
| `Policy` | text | A full policy written as JSON. See [Full policy](#full-policy). |

Set only the ones you need. A setting you leave out is not enforced.

### `RequireSignIn` set to `false`: local-only

This is the lock most IT teams ask for. With it:

* speech-to-text and AI features can use only models that run on the computer
* people can't add their own cloud API keys or choose a cloud provider
* the app skips sign-in during setup, and sign-in is turned off on that computer
* web search, connectors, cloud backup, and share links are off
* the app blocks its own connections to OpenWhispr's servers and to every cloud AI provider

Two downloads still work: models, when someone picks a local model, and app updates. See [Local model downloads](https://docs.openwhispr.com/help/it/network-allowlist.md#local-model-downloads) for the hosts they use. To stop the app updating itself as well, deploy a [full policy](#full-policy) with `"updates": { "mode": "it_managed" }`.

If someone was signed in before you deployed the lock, they stay signed in, but the app makes no cloud requests for that account. The app tells them: *This device uses local processing only. Cloud features are unavailable, including for previously signed-in accounts.*

### `RequireSignIn` set to `true`: sign-in required

People must sign in before they can use OpenWhispr. After they sign in, the app combines your device policy with their workspace's policy, and the stricter of the two wins for each control. Use this with [single sign-on](https://docs.openwhispr.com/help/it/sso.md) to make sure every company computer follows your workspace's rules.

### `DisableMeetingRecording` set to `true`

This turns off meeting recording and leaves the rest of the app alone. You can combine it with either value of `RequireSignIn`.

## Deploy on macOS with Jamf Pro

You can paste the setting into Jamf Pro, or upload a ready-made profile. Both give the same result.

### Option A: paste the setting

**1. Create the profile**

In Jamf Pro, go to **Computers → Configuration Profiles → New**. Give it a name, such as *OpenWhispr: local processing only*, and set **Level** to **Computer Level**.

**2. Add the preference domain**

Open the **Application & Custom Settings** payload and choose **Upload**. Select **Add**, then enter `com.gizmolabs.openwhispr` as the **Preference Domain**.

**3. Paste the setting**

Paste this into **Property List**:

```xml theme={null}
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>RequireSignIn</key>
  <false/>
</dict>
</plist>
```

**4. Scope and save**

On the **Scope** tab, add the computers or groups, then select **Save**.

### Option B: upload the sample profile

Save this as `openwhispr-local-only.mobileconfig`. In Jamf Pro, go to **Computers → Configuration Profiles → Upload**, choose the file, set the scope, and save.

```xml openwhispr-local-only.mobileconfig theme={null}
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>PayloadContent</key>
  <array>
    <dict>
      <key>PayloadType</key>
      <string>com.apple.ManagedClient.preferences</string>
      <key>PayloadVersion</key>
      <integer>1</integer>
      <key>PayloadIdentifier</key>
      <string>com.gizmolabs.openwhispr.local-only.settings</string>
      <key>PayloadUUID</key>
      <string>98D6D095-0B57-4027-A2F4-8577E4861179</string>
      <key>PayloadDisplayName</key>
      <string>OpenWhispr settings</string>
      <key>PayloadEnabled</key>
      <true/>
      <key>PayloadContent</key>
      <dict>
        <key>com.gizmolabs.openwhispr</key>
        <dict>
          <key>Forced</key>
          <array>
            <dict>
              <key>mcx_preference_settings</key>
              <dict>
                <key>RequireSignIn</key>
                <false/>
              </dict>
            </dict>
          </array>
        </dict>
      </dict>
    </dict>
  </array>
  <key>PayloadType</key>
  <string>Configuration</string>
  <key>PayloadVersion</key>
  <integer>1</integer>
  <key>PayloadIdentifier</key>
  <string>com.gizmolabs.openwhispr.local-only</string>
  <key>PayloadUUID</key>
  <string>CB04B47D-F34F-475C-971C-F31D3CDA1F3A</string>
  <key>PayloadDisplayName</key>
  <string>OpenWhispr: local processing only</string>
  <key>PayloadDescription</key>
  <string>Locks OpenWhispr to on-device transcription with no sign-in.</string>
  <key>PayloadOrganization</key>
  <string>Your organization</string>
  <key>PayloadScope</key>
  <string>System</string>
</dict>
</plist>
```

You can change `PayloadOrganization` to your company name. To turn off meeting recording as well, add these two lines under `RequireSignIn` in the inner `mcx_preference_settings` block:

```xml theme={null}
<key>DisableMeetingRecording</key>
<true/>
```

> [!WARNING]
>
> Write `true` and `false` as `<true/>` and `<false/>`. A number such as `<integer>0</integer>` or the text `<string>false</string>` makes the policy invalid, and OpenWhispr stops working on that computer until it's fixed.

### Check it on a Mac

After the profile installs, open **System Settings → General → Device Management** (older macOS: **Privacy & Security → Profiles**). The OpenWhispr profile should be listed. In Terminal, this should print `RequireSignIn = 0;`:

```bash theme={null}
defaults read "/Library/Managed Preferences/com.gizmolabs.openwhispr"
```

A profile pushed to a user rather than the computer is in `/Library/Managed Preferences/<username>/` instead.

Then open OpenWhispr. Setup skips sign-in, and only on-device models are offered.

## Deploy on Windows

Create the values under `HKLM\SOFTWARE\Policies\OpenWhispr`:

| Value | Registry type | Data |
| - | - | - |
| `RequireSignIn` | `REG_DWORD` | `0` for local-only, `1` to require sign-in |
| `DisableMeetingRecording` | `REG_DWORD` | `1` to turn off meeting recording |
| `Policy` | `REG_SZ` | The full policy JSON |

For example, from an elevated Command Prompt:

```bat theme={null}
reg add "HKLM\SOFTWARE\Policies\OpenWhispr" /v RequireSignIn /t REG_DWORD /d 0 /f /reg:64
```

Use the 64-bit registry. A value a 32-bit tool writes under `WOW6432Node` is not read. On/off values must be `REG_DWORD` set to `0` or `1`. Any other type or number makes the policy invalid.

## Deploy on Linux

OpenWhispr reads two files from `/etc/openwhispr`:

* `device.json` holds `RequireSignIn` and `DisableMeetingRecording`
* `policy.json` holds a [full policy](#full-policy), written as a plain JSON object, not as text

For local-only:

```bash theme={null}
sudo install -d -o root -g root -m 755 /etc/openwhispr
echo '{ "RequireSignIn": false }' | sudo tee /etc/openwhispr/device.json > /dev/null
sudo chown root:root /etc/openwhispr/device.json
sudo chmod 644 /etc/openwhispr/device.json
```

To keep anyone else from planting a policy, OpenWhispr trusts the folder and files only when all of these are true:

* the folder and both files are owned by root, and only root can write to them
* `/etc` is owned by root, and only root can write to it
* neither the folder nor the files are symbolic links
* each file is 1 MB or smaller

If a file breaks one of these rules, OpenWhispr treats the policy as invalid. Don't put a `Policy` key in `device.json`: put the policy in `policy.json`.

## Full policy

The `Policy` setting holds every control in one JSON value. It uses the same format as an OpenWhispr workspace policy. Use it when the three simple settings aren't enough, for example to allow only certain cloud providers or to manage updates yourself.

This example keeps the app local-only, turns off meeting recording, and stops the app updating itself:

```json theme={null}
{
  "version": 1,
  "transcription": {
    "allowedModes": ["local"],
    "allowedByokProviders": [],
    "allowedEnterpriseProviders": []
  },
  "llm": {
    "allowedModes": ["local"],
    "allowedByokProviders": [],
    "allowedEnterpriseProviders": []
  },
  "features": {
    "agentEnabled": true,
    "webSearchEnabled": false,
    "screenContextEnabled": true,
    "connectorsEnabled": false,
    "meetingRecordingEnabled": false,
    "audioUploadEnabled": true
  },
  "sharing": { "externalLinkSharing": "disabled" },
  "dataRetention": {
    "audioRetentionMaxDays": null,
    "localHistoryMode": "user_choice",
    "cloudBackupAllowed": false
  },
  "requiredLocalModels": [],
  "minAppVersion": null,
  "updates": { "mode": "it_managed" }
}
```

| Field | What it controls |
| - | - |
| `version` | Always `1` |
| `transcription.allowedModes`, `llm.allowedModes` | Where speech-to-text and AI can run: `local` (on the computer), `openwhispr` (OpenWhispr Cloud), `providers` (the person's own API keys), `self-hosted`, `enterprise` (your company's cloud) |
| `allowedByokProviders` | Which providers people may use with their own keys. An empty list allows none. |
| `allowedEnterpriseProviders` | Which company clouds may be used: `azure` and `openai-compatible` for speech-to-text; `bedrock`, `azure` and `vertex` for AI |
| `features` | Turns the AI assistant, web search, screen context, connectors, meeting recording and audio-file upload on or off |
| `sharing.externalLinkSharing` | `allowed`, `domain_only` or `disabled` |
| `dataRetention.audioRetentionMaxDays` | The most days recorded audio can be kept. `null` sets no limit. |
| `dataRetention.localHistoryMode` | `user_choice`, `always_on` or `always_off` |
| `dataRetention.cloudBackupAllowed` | Whether notes and history can back up to OpenWhispr Cloud |
| `requiredLocalModels` | Model IDs that must be downloaded before people can dictate |
| `minAppVersion` | The oldest app version allowed, such as `"1.12.0"`, or `null` |
| `updates.mode` | `user_choice` (people decide), `always_on` (updates always install) or `it_managed` (the app never updates itself, so you deploy new versions) |

`requiredLocalModels`, `updates`, `transcription.allowedEnterpriseProviders`, and every feature except `agentEnabled` and `webSearchEnabled` can be left out. A feature you leave out stays on. Every other field is required: a policy with a missing required field, or a value the app doesn't recognise, is invalid.

How to deploy it:

* **macOS:** add a `Policy` key whose value is a `<string>` holding the JSON. Escape `<`, `>` and `&` if your JSON contains them.
* **Windows:** a `REG_SZ` value named `Policy` holding the JSON.
* **Linux:** the JSON object itself, as `/etc/openwhispr/policy.json`.

> [!WARNING]
>
> If you deploy `Policy` without `RequireSignIn`, OpenWhispr **requires sign-in**. To use a full policy on computers where nobody signs in, also set `RequireSignIn` to `false`.

## When changes take effect

OpenWhispr checks for a new or changed policy every minute while it runs, and again when someone switches back to the app. On macOS and Linux, it also notices a change to the policy files within seconds. No restart is needed.

To remove the policy, remove the profile, registry key or files. OpenWhispr goes back to normal at its next check.

## If the policy is invalid

If OpenWhispr finds a policy it can't use, it doesn't fall back to no policy. It stops working on that computer and shows: *The device policy could not be read or is invalid. Contact your administrator.* Fix or remove the policy and the app recovers within a minute.

Common causes:

| Cause | Fix |
| - | - |
| An on/off value written as a number or text | macOS: `<true/>` or `<false/>`. Windows: `REG_DWORD` `0` or `1`. Linux: JSON `true` or `false`. |
| `Policy` is not valid JSON, or is missing a field | Check it with a JSON validator against [Full policy](#full-policy) |
| Linux files or folder not owned by root, or writable by others | Run `chown root:root` and `chmod 644` on the files, `chmod 755` on the folder |
| A `Policy` key in Linux `device.json` | Move it to `policy.json` |

## Related

* [Network allowlist](https://docs.openwhispr.com/help/it/network-allowlist.md)
* [Set up single sign-on](https://docs.openwhispr.com/help/it/sso.md)
* [Provision people and teams with SCIM](https://docs.openwhispr.com/help/it/scim-provisioning.md)
* [Running models locally](https://docs.openwhispr.com/guides/local-models.md)

<Snippet file="still-need-help.mdx" />


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.