Managed Settings

Quick start#

1. Download the profile generator and build a profile with the settings you need. It checks every value before it writes the profile.
2. Upload the profile to your MDM, for example as a custom profile in Iru or under Configuration Profiles in Jamf Pro, and assign it to a test Mac.
3. On the Mac, open TypeWhisper > Settings > Advanced > Managed Settings. It lists the managed values and any policy problems.

# The generator from the release you deploy (here v1.8.0)
curl -fsSLO https://raw.githubusercontent.com/TypeWhisper/typewhisper-mac/v1.8.0/deployment/macos/make-typewhisper-profile.py
chmod +x make-typewhisper-profile.py

./make-typewhisper-profile.py \
    --set AllowCloudTranscription=false \
    --set AllowCloudTextProcessing=false \
    --set TranscriptionProviderId=com.typewhisper.parakeet \
    --set TranscriptionModelId=parakeet-tdt-0.6b-v3 \
    --set SuppressOptionalPrompts=true \
    --recommend LaunchAtLogin=true \
    --domain com.typewhisper.mac \
    --domain com.typewhisper.typewhisper-app \
    --identifier com.example.typewhisper \
    --organization "Example Corp" --output TypeWhisper.mobileconfig

Details are under Profile generator, Iru, Jamf Pro, and other MDMs.

How managed settings work#

A configuration profile sets managed preferences for the app's preference domain, the same mechanism Iru, Jamf, and other MDMs use for app settings. Each edition has its own domain:

Keys at the top level of the payload are enforced: users cannot change them. Keys inside a Recommended dictionary are administrator defaults: they apply until the user makes their own choice and stay editable. When several sources set a value, this order applies:

1. Enforced value
2. The user's own choice
3. Recommended value
4. The app default

TypeWhisper never writes these values and never stores the effective result over a user's own setting, so removing a value brings the user's setting back.

Profile layout#

Each payload names the domain as its PayloadType and holds the settings next to its own Payload keys. Once the profile is installed, System Settings lists every setting with its value:

<dict>
    <key>PayloadType</key>
    <string>com.typewhisper.mac</string>
    <key>PayloadVersion</key>
    <integer>1</integer>
    <key>PayloadIdentifier</key>
    <string>com.example.typewhisper.com.typewhisper.mac</string>
    <key>PayloadUUID</key>
    <string>0D5A3A6E-9C1B-4F3A-8E2D-6B7C1F0A2E41</string>
    <key>PayloadDisplayName</key>
    <string>TypeWhisper managed settings</string>
    <key>UpdateMode</key>
    <integer>1</integer>
    <key>AllowedUpdateChannels</key>
    <array>
        <string>stable</string>
    </array>
    <key>SuppressOptionalPrompts</key>
    <true/>
    <key>Recommended</key>
    <dict>
        <key>LaunchAtLogin</key>
        <true/>
    </dict>
</dict>

• The surrounding profile is the same as in the example profiles.
• The custom settings payload (com.apple.ManagedClient.preferences) with the values under Forced > mcx_preference_settings works the same way.
• Device and user scope both work. A device profile applies to every user of the Mac, a user profile only to that user.
• macOS copies some keys of the profile itself into the domain, such as PayloadUUID and _manualProfile. TypeWhisper ignores keys that start with Payload or _.

Value types and lists#

• Switches are Booleans: <true/> or <false/>. <integer>1</integer> is not a Boolean.
• Options are integers.
• Text is a string: trimmed, not empty, at most 1024 characters, and without control characters.
• Lists are arrays of at most 256 strings. An empty array, or the single entry none, allows nothing. One invalid entry makes the whole list invalid.
• Key names are case-sensitive. A key that differs only in letter case is reported with the intended name and ignored.

Invalid and unknown values#

• A value of the wrong type is invalid. An invalid enforced value blocks everything its key governs until it is corrected, and never relaxes a restriction: an invalid AllowCloudTranscription refuses every engine, local ones included; an invalid AllowedPlugins refuses every plugin; an invalid update key pauses updates.
• Unknown keys, an invalid recommendation, and restrictions placed in Recommended are reported and ignored.
• Values written with defaults write are user-writable, so TypeWhisper ignores and reports them. The one exception is ManagedLicenseKey, see below.

When changes apply#

TypeWhisper reads the profile at launch, before any other setting is used, so a profile that is present at the first launch applies right away. After that, the app reads it again when it becomes active, after wake, after switching back to the user session, and every 30 seconds. macOS has no change notification for profiles, so a new, replaced, or removed profile takes effect within about 30 seconds without a restart.

Key reference#

The key names, values, and precedence match the policies of TypeWhisper for Windows, apart from some plugin and provider IDs (see Provider IDs), so one set of decisions applies to both platforms. Keys that can also be recommended go into the Recommended dictionary. Pairs and provider IDs are described in more detail below.

The Mac App Store edition is updated by the App Store and has its plugins built in. It ignores the keys marked “direct download only” and lists them as policy problems: ManagedLicenseKey, UpdateMode, UpdateChannel, AllowedUpdateChannels, and AllowPluginDownloads.

License#

Models#

Updates and startup#

Data and plugins#

Provider and model pairs#

A pair names a provider by its provider ID and a model by the ID the provider lists, for example com.typewhisper.parakeet with parakeet-tdt-0.6b-v3, or com.typewhisper.groq with whisper-large-v3. For a plugin with several providers, such as OpenAI Compatible with several endpoint profiles, name the provider as <plugin ID>:<provider ID>. Providers that list no models accept the ID as written. An enforced pair with only one value is invalid and blocks the feature until it is complete; an incomplete recommended pair is reported and ignored.

Enforced pairs#

An enforced transcription pair is used by dictation and its live preview, file transcription, the Recorder, watch folders, recovery, re-transcription in History, and the HTTP API, regardless of the selected engine, workflow overrides, or per-feature engines. An API request that asks for another engine or model, or to load another model, gets 403. The engine and model pickers are locked. The user's own engine selection is kept and applies again once the pair is removed.

Parakeet 1.5.0 and WhisperKit 1.3.0 or later use the enforced model without saving it. Once the pair is removed, they return to the model the user had selected, or to no model, also when the profile was removed while TypeWhisper was not running. A model the user picks on the engine's settings page meanwhile is saved and used after the pair is removed. Other engines save the enforced model as their selection; see Known limits.

An enforced language model pair replaces the provider and model of every language model call. The workflow editor and the global LLM fallbacks keep their saved selections but are locked.

Missing providers and models#

A pair that cannot be used never falls back to another provider. If the provider is not installed, turned off, or refused by another key, or does not offer the model, the affected feature is blocked with the reason, and Settings > Advanced > Managed Settings lists the problem. With AllowModelDownloads set to false, deploy the model files with the app.

Recommended pairs#

A recommended pair is applied once: when the user has not chosen an engine (or has kept the built-in default language model) and the provider and model are ready, which means the model is already downloaded. A recommendation never starts a download. The user can change the pair afterwards.

Provider IDs#

• Policies name providers by plugin ID, the id in the plugin's manifest, for example com.typewhisper.parakeet, com.typewhisper.whisperkit, or com.typewhisper.groq. A plugin ID covers every provider the plugin offers.
• For a single provider of a plugin with several, such as one endpoint profile of OpenAI Compatible, use <plugin ID>:<provider ID>.
• Apple Intelligence, which is built into the app, is com.typewhisper.apple-intelligence.
• Matching ignores letter case.
• The plugin catalog at https://typewhisper.github.io/typewhisper-mac/plugins-community-v1.json lists every plugin's id and locality. Not all IDs start with com.typewhisper; Mistral AI, for example, is com.minerale.mistralai. GET /v1/models of the local HTTP API lists the model IDs as id.
• Some plugin IDs differ from TypeWhisper for Windows: Parakeet is com.typewhisper.parakeet on the Mac and com.typewhisper.sherpa-onnx on Windows. If you keep one set of decisions for both platforms, put both IDs in the lists; pairs need their own values per platform.

Cloud processing and plugin locality#

Every plugin declares in the locality field of its manifest where it processes content; the plugin catalog publishes the same value:

• local: nothing leaves the Mac.
• cloud: the vendor's fixed service.
• configurable: an endpoint, script, or command the user configures, which TypeWhisper cannot classify.

With AllowCloudTranscription or AllowCloudTextProcessing set to false, only local plugins keep receiving that content. Plugins marked cloud or configurable and plugins without a known value are refused.

A plugin that is not local and whose every capability (its manifest categories) is refused is refused as a whole: it is not installed, loaded, or enabled, and the Marketplace and its plugin page show the reason. A plugin with an allowed capability keeps running, and its refused capability is refused where it is used. Refused engines and language models disappear from the pickers.

When the selected engine is refused, TypeWhisper falls back to an allowed engine for the moment, as it does for any unavailable engine, and keeps the user's choice for when it is allowed again. When no allowed engine is ready, dictation reports the reason.

Known limits#

• Code of a plugin that was running when it became refused stays loaded until TypeWhisper quits. The plugin receives no further calls.
• Configuration actions in a plugin's settings, such as validating an API key, still run. They carry credentials, not transcripts.
• Audio that a streaming engine received before a stricter policy arrived cannot be recalled. The policy applies again at the next request.
• A plugin refused as a whole never runs, so TypeWhisper learns its engine IDs only from an earlier launch of TypeWhisper 1.8 or later. If the selected engine belongs to such a plugin and no allowed engine is ready, dictation can report that no engine is selected instead of the reason.
• If an engine had no model selected before an enforced pair, the enforced model stays selected after the pair is removed, because plugins cannot clear a selection. The user's engine choice and a model they had selected are restored. Parakeet 1.5.0 and WhisperKit 1.3.0 or later are not affected.
• An Apple Intelligence pair accepts any model ID, for example default, because Apple Intelligence has a single system model, and needs macOS 26 or later; on earlier versions the pair blocks language model features.
• These keys govern TypeWhisper's behavior. They are not a network firewall: use your MDM's network controls for stronger guarantees.

Managed license key#

ManagedLicenseKey activates a commercial license in the signed-in user's session. You don't need to call Polar yourself or write to users' Keychains. Surrounding whitespace is ignored, and supporter keys are not accepted. The key has been available since TypeWhisper 1.6.1 and only in the direct download: Apps and Books licenses of the Mac App Store edition do not include in-app purchases.

Use the example license profile and replace the placeholder with your license key, escaping special characters for XML. Or build a profile with the generator (--set ManagedLicenseKey=…); the key then appears in your shell history and, while the generator runs, in its command line, which other users of the Mac can see. Use a Mac only you work on, and clear the history entry afterwards. Upload the profile as a custom profile and assign it to the intended Macs. Install the app, then launch or restart TypeWhisper in each user's session with internet access.

Alternative: script#

The same preference can be written with defaults in the intended user's context:

/usr/bin/defaults write com.typewhisper.mac ManagedLicenseKey -string 'YOUR_LICENSE_KEY'

This is a provisioning preference, not an access-control boundary: a forced MDM profile prevents users from editing the value, a value written with defaults does not. MDM agents commonly run scripts as root, and root's preferences do not configure the signed-in user's app. Use your MDM's user-session execution, and wait until a user is signed in. Do not enable shell tracing (set -x), and keep real keys out of shell history and command logs. While defaults runs, the key also appears in its command line, which other users of the Mac can see, so prefer the configuration profile.

Activation#

• The app reads the key at launch. From TypeWhisper 1.8, a key delivered by a configuration profile is read again whenever the profile changes, so a new, changed, or removed key takes effect within about 30 seconds without a restart. Earlier versions, and a key written with defaults, need a restart after a change. Settings > License also offers Retry Activation.
• The app stores the key and its Polar activation in the user's Keychain and does not activate again on every launch. Several users on one Mac have separate Keychain records and activations, so a Mac with several users uses one activation per user.
• The first activation needs internet access. If it fails, retry it in Settings > License or at the next launch; there is no retry loop in the background. Existing licenses keep their normal offline validation.
• While the key is managed, the License page hides manual commercial activation and the plan controls, suppresses license selection prompts, and shows the status without the key. Microphone permission, model setup, and the setup wizard are unchanged.

Changing or removing the key#

• A new key is validated and stored before the old activation is deactivated. If the replacement fails, the old record stays intact.
• If deactivating the old activation fails, the app keeps it queued in the Keychain and retries at later launches and when the user chooses Retry Activation: at most three entries per pass, first after an hour, then doubling up to once a day. After three requests that Polar rejects outright, for example with HTTP 422, the app stops retrying that entry. The current activation is never deactivated by this cleanup. Activations that are still listed in Polar afterwards can be removed there.
• Removing the value restores the manual license controls: right away for a profile from TypeWhisper 1.8, otherwise at the next launch. It does not revoke or delete the existing activation, and queued cleanup of replaced activations continues. Deactivate it manually or revoke it centrally in Polar. The app notices central changes at its next validation, at launch or on Retry Activation, once seven days have passed since the last successful check of an active license.
• A revoked license is not reactivated over and over. An activation deleted in Polar can be created again while the configured key stays valid.

Profile generator#

make-typewhisper-profile.py builds a configuration profile from --set (enforced) and --recommend (recommended) values and checks every value against the reference above, so a typo fails when you build the profile instead of on the Macs. It needs Python 3.9 or later and no packages; on a Mac, the Xcode Command Line Tools include it.

# Updates through your deployment, recommended (editable) channel
./make-typewhisper-profile.py --set UpdateMode=external --recommend UpdateChannel=stable \
    --identifier com.example.typewhisper.updates --output TypeWhisper-Updates.mobileconfig

# Approved providers and plugins only, no plugin downloads
./make-typewhisper-profile.py \
    --set AllowedTranscriptionProviders=com.typewhisper.parakeet,com.typewhisper.openai \
    --set AllowedLlmProviders=com.typewhisper.openai,com.typewhisper.apple-intelligence \
    --set AllowPluginDownloads=false \
    --identifier com.example.typewhisper.approved --output TypeWhisper-Approved.mobileconfig

# Only the Parakeet plugin may load
./make-typewhisper-profile.py --set AllowedPlugins=com.typewhisper.parakeet \
    --identifier com.example.typewhisper.plugins --output TypeWhisper-Plugins.mobileconfig

• Take the generator from the release you deploy, as in the quick start above, so it accepts exactly the keys that version reads.
• Lists are comma-separated; an empty value (--set AllowedPlugins=) allows nothing. Booleans are true or false.
• UpdateMode accepts external, check-only, or user-initiated, and UpdateChannel accepts stable, daily, or release-candidate, or their numbers.
• The generator refuses unknown keys (with the intended spelling for a key in the wrong case), restrictions passed to --recommend, and incomplete pairs.
• Keep --identifier stable, for example com.example.typewhisper, so a new profile replaces a deployed one instead of adding a second. The profile's UUIDs derive from the identifier, so regenerating it with new values keeps them. Use one identifier per profile you deploy; profiles with the same identifier replace each other.
• Restrictions apply only to the domains you include. To manage both editions, add both with --domain, or deploy one profile per domain; the App Store edition reads only com.typewhisper.typewhisper-app. The generator leaves the keys that edition ignores out of its payload and says so.
• --scope chooses a device (System) or user (User) profile, and --name and --organization set the display name and organization.

Deployment files#

All files are in the repository under deployment/macos. The examples use the direct-download domain unless their name says otherwise. Build your own profiles with the generator rather than editing the examples, so the values are checked.

Iru#

Add the generated profile to the Library as a custom profile and assign it to the Blueprints of the intended Macs. The login item and privacy examples are custom profiles as well. When the profile is removed from a Mac, TypeWhisper returns to the users' own settings within about 30 seconds.

Jamf Pro#

Jamf Pro can configure the settings through a form generated from a schema:

1. Computers > Configuration Profiles > New, then Application & Custom Settings > External Applications > Add > Custom Schema.
2. Enter the preference domain, com.typewhisper.mac or com.typewhisper.typewhisper-app, and paste the content of the matching file from jamf/.
3. Configure the properties you manage and leave the others at “Not Configured”, which writes nothing. Recommended settings are under “Recommended settings (users can change)”.
4. Scope the profile and save. Add a second payload for the other edition if needed.

Jamf Pro delivers the configured top-level values as managed preferences, which TypeWhisper treats as enforced; values under “Recommended settings (users can change)” are defaults users can change. Uploading a profile built with the generator (Configuration Profiles > Upload) works as well and is the way to deploy the login item and privacy examples.

The schema has not been checked in a Jamf Pro instance yet. Before a wide rollout, confirm on a pilot Mac in Settings > Advanced > Managed Settings that properties left at “Not Configured” do not appear.

Other MDMs#

Any MDM that installs custom configuration profiles works: upload the generated .mobileconfig file. For a profile editor, import the matching file from ProfileManifests/, or write the payload by hand following the profile layout above. Sign the profile if your MDM expects signed uploads.

Test without MDM#

Open the profile in Finder and install it in System Settings > General > Device Management. The managed preferences then apply as in a managed fleet. The Service Management and privacy payloads take effect only when an MDM delivers them.

Check the effective values#

• Settings > Advanced > Managed Settings lists the managed values with their scope (enforced or recommended), invalid keys, and Policy Problems, with the time the current values were read (shown as “Last checked”; it changes only when the values change) and a Refresh button.
• The section appears only while a value is managed, a key is reported, or the managed settings cannot be read. If it is missing, no managed value reached this edition's domain.
• Locked settings show “Managed by your organization”, and refused providers and plugins show the reason. If the managed settings cannot be read, the section says so, and managed features wait until they can be read again.
• Support diagnostics (Settings > Advanced > Support Diagnostics > Export Diagnostics) contain the managed values, invalid keys, and validation problems; pair and edition problems appear only in Settings. Users can send the diagnostics to you or to TypeWhisper support.
• System Settings > General > Device Management shows the installed profile with every setting and its value.