-
Notifications
You must be signed in to change notification settings - Fork 3
Preference Keys
Gil Burns edited this page Aug 1, 2026
·
6 revisions
All preferences are read from the com.gilburns.patcher preference domain. They can be deployed via MDM as a configuration profile or set locally.
MDM profile path: /Library/Managed Preferences/com.gilburns.patcher.plist
Local override path: /Library/Preferences/com.gilburns.patcher.plist
Managed preferences take precedence. When a key is not present in either location, the default value is used.
Set preferences with
defaultsfor testing (not for production):sudo defaults write /Library/Preferences/com.gilburns.patcher ScanIntervalDays -int 7
The preference keys supported by Third Party Patcher are largely compatible with those used by the App Auto-Patch project. If you are migrating from or running alongside App Auto-Patch, most keys map directly.
Two things to be aware of when converting an App Auto-Patch preference profile:
-
Boolean type — Third Party Patcher uses native plist booleans (
<true/>/<false/>). App Auto-Patch represents booleans as strings (<string>TRUE</string>/<string>FALSE</string>). Any boolean key must be changed to the native type or it will not be read correctly.<!-- App Auto-Patch style — does NOT work with Third Party Patcher --> <key>SwiftDialogEnabled</key> <string>TRUE</string> <!-- Third Party Patcher style --> <key>SwiftDialogEnabled</key> <true/>
-
Missing keys — A small number of keys present in Third Party Patcher do not exist in App Auto-Patch (for example, keys specific to Managed Labels, the metadata sync, and Available Software). These have safe defaults and can simply be omitted if not needed.
| Key | Type | Default | Description |
|---|---|---|---|
LogVerbose |
Boolean | false |
Enable verbose debug logging. When true, per-label key dumps and other low-signal output are included in /Library/Logs/Patcher/. |
| Key | Type | Default | Description |
|---|---|---|---|
IgnoreAppsInHomeFolder |
Boolean | false |
When true, apps found only in /Users/* are never updated and are effectively ignored by the patcher. When false, apps in home folders are updated in place. |
ConvertAppsInHomeFolder |
Boolean | false |
When true, apps discovered in /Users/* are relocated to /Applications before patching. The original copy is removed. Ignored when IgnoreAppsInHomeFolder is true. Self-service installs from Available Software always behave as if this is true. |
IgnoreAppsOnExternalVolumes |
Boolean | false |
When true, apps found only on external volumes (/Volumes/*) are excluded from discovery and never updated. Useful in environments where external drives are transient and should not be managed. |
| Key | Type | Default | Description |
|---|---|---|---|
InstallomatorGitHubAccount |
String | "Installomator" |
GitHub account hosting the Installomator label repository. |
InstallomatorGitHubRepo |
String | "Installomator" |
GitHub repository name for Installomator labels. |
InstallomatorGitHubBranch |
String | "main" |
Branch to pull Installomator labels from. |
InstallomatorLabelsDisable |
Boolean | false |
When true, disables all Installomator label management: no initial download, no update checks, and Installomator labels are never used. Only Managed Labels are used. |
InstallomatorUpdateDisable |
Boolean | false |
When true, skips routine label update checks while still using labels already on disk. Has no effect on the initial download when no labels are present. Ignored when InstallomatorLabelsDisable is true. |
The metadata repository provides app descriptions, publisher names, icons, keywords, and links shown in the Available Software catalog.
| Key | Type | Default | Description |
|---|---|---|---|
InstallomatorGitHubMetadataAccount |
String | "gilburns" |
GitHub account hosting the Installomator Metadata repository. |
InstallomatorGitHubMetadataRepo |
String | "Installomator-Metadata" |
GitHub repository name for Installomator Metadata. |
InstallomatorGitHubMetadataBranch |
String | "main" |
Branch to pull metadata from. |
MetadataSyncEnabled |
Boolean | true |
When true, the scheduler periodically checks the metadata repository for updates and syncs icons and metadata to a local cache. |
MetadataSyncIntervalDays |
Integer | 10 |
Days between metadata repository sync checks. |
| Key | Type | Default | Description |
|---|---|---|---|
IgnoredLabels |
String | "" |
Space-separated list of label name patterns to skip entirely during scan. Supports * and ? wildcards (e.g. "adobe* microsoftteams"). |
IgnoreManagedApps |
Boolean | true |
When true, automatically detects apps whose updates are already controlled by MDM policies and excludes their labels from patching. Currently detects Microsoft 365/Office (via MAU), Microsoft Edge, Google Chrome, and Google Drive. See Installomator Integration for detection details. |
IgnoreNonProductionLabels |
Boolean | true |
When true, automatically ignores non-production label variants — labels whose name ends with one of NonProductionLabelSuffixes — but only when a production label of the same base name also exists. E.g. with the default suffixes, microsoftedgebeta and microsoftedgedev are ignored because microsoftedge also exists as a label; a label like figma is untouched, and a hypothetical somethingbeta is left alone if something is not also a known label. |
NonProductionLabelSuffixes |
String | "beta canary dev" |
Space-separated list of suffixes that mark a label as a non-production variant of a base label. Only used when IgnoreNonProductionLabels is true. Does not support wildcards. |
PreferPkgLabels |
Boolean | true |
When a label and its pkg-suffixed counterpart both exist (e.g. bbedit and bbeditpkg), only one should ever be active — they deliver the same app via different installer mechanisms. When true, the pkg-suffixed label is preferred and the non-pkg label is ignored. When false, the non-pkg label is preferred and the pkg-suffixed label is ignored instead. |
RequiredLabels |
String | "" |
Space-separated list of label names that must be managed, even if not currently installed. Does not support wildcards. |
OptionalLabels |
String | "" |
Space-separated list of label names made available for user-initiated self-service installation via the Available Software catalog. Does not support wildcards. Labels are presented in the order listed here, allowing you to feature priority apps at the top. Example: "microsoftword zoom slack". |
| Key | Type | Default | Description |
|---|---|---|---|
DownloadBandwidthLimit |
String | "" |
curl --limit-rate format bandwidth cap for staged downloads (e.g. "500K" for 500 KB/s, "2M" for 2 MB/s). Empty string = unlimited. |
StageDownloadFailThreshold |
Integer | 3 |
Consecutive download or verification failures before a label is marked broken and skipped by the stage phase. |
ApplyFailThreshold |
Integer | 3 |
Consecutive install failures before a staged update is abandoned and that version is blocked from re-staging. Staging resumes automatically when a newer version becomes available. |
IgnoreUnknownVersionLabels |
Boolean | false |
When true, labels that return no appNewVersion value are skipped entirely during staging. |
UnknownVersionCheckIntervalDays |
Integer | 7 |
For labels with unknown versions, re-check this many days after the last attempt (instead of the normal CheckIntervalHours cadence). |
VersionMismatchThrottleDays |
Integer | 7 |
When a label reports a version that does not match the file actually downloaded, suppress re-staging for this many days. Cleared automatically when the label reports a different appNewVersion. |
The scheduler wakes every 10 minutes and runs phases based on the elapsed time since each phase last ran.
| Key | Type | Default | Description |
|---|---|---|---|
InitialScanDelayEnabled |
Boolean | true |
When true, a one-time random delay is applied before the first scan after initial deployment. Spreads fleet-wide first-scan load across the InitialScanDelayMaxSeconds window. |
InitialScanDelayMaxSeconds |
Integer | 86400 |
Maximum jitter for the initial deployment delay in seconds (default: 24 hours). The actual delay is chosen randomly in [0, max] on first launch and persisted. |
ScanIntervalDays |
Integer | 30 |
Days between full application scans. A full scan re-evaluates all Installomator labels to discover installed apps. |
ScanOnLabelUpdate |
Boolean | true |
When true, a scan is triggered immediately if the Installomator or Managed Labels have been updated since the last scan, regardless of ScanIntervalDays. |
LightScanIntervalHours |
Integer | 24 |
Hours between light scan runs. A light scan checks uninstalled labels for apps that may have been installed by other means, without re-running label scripts or hitting the network for non-installed labels. |
CheckIntervalHours |
Integer | 12 |
Hours between check runs. A check reads installed versions for already-discovered apps to detect whether an update is needed. |
StageIntervalHours |
Integer | 12 |
Hours between stage runs. The stage phase downloads pending updates. |
ApplyIntervalHours |
Integer | 4 |
Minimum hours between apply runs in deadline-based patching mode. Prevents apply from running every 10-minute cycle once updates are pending. Not used in monthly patching mode — the patch-day window controls timing. |
When MonthlyPatchingCadenceEnabled is true, the apply phase is gated to a specific week and day of the month. See Patching Walkthrough — Monthly for a full walkthrough.
| Key | Type | Default | Description |
|---|---|---|---|
MonthlyPatchingCadenceEnabled |
Boolean | false |
When true, patching is restricted to the configured weekday/week-of-month window instead of using deadline-based timing. |
PatchingWeekday |
Integer | 3 |
Day of the week for the patch window: 1=Sunday, 2=Monday, 3=Tuesday … 7=Saturday. |
PatchingWeekOfMonth |
Integer | 2 |
Which occurrence of PatchingWeekday in the month: 1=first, 2=second, etc. |
PatchingStartTime |
String | "" |
Earliest time to begin applying on patch day (24-hour HH:MM). Empty = no lower bound. |
PatchingEndTime |
String | "17:00" |
Latest time to begin applying on patch day (24-hour HH:MM). Apply will not start a new run after this time. |
Deadline counters determine when deferral options are restricted or removed entirely. See Deferral and Deadlines for how they interact.
| Key | Type | Default | Description |
|---|---|---|---|
DeadlineDaysFocus |
Integer | 4 |
Days a pending update must be present before Focus/DND auto-deferral is disabled and the user must be prompted regardless of Focus state. 0 means Focus is always respected. |
DeadlineDaysHard |
Integer | 10 |
Days a pending update must be present before no further deferrals are offered and the update is applied at the next opportunity. 0 disables hard deadlines. |
FocusCheckEnabled |
Boolean | true |
When false, Focus/DND and display assertions (e.g. active screen sharing) are never checked. The prompt is shown regardless of the user's Focus state. |
AggressivePatchDayDeferral |
Boolean | true |
When true, deferral options are progressively capped as the patching window closes. Options shrink from 2 hours early in the day to 5 minutes near window end, then deferral is removed entirely once the window closes. When false, the full DeferralTimerMenu list is always shown. Applies to both monthly and deadline mode on the final patch day. |
| Key | Type | Default | Description |
|---|---|---|---|
QuietApplyEnabled |
Boolean | false |
When true, the scheduler runs a silent apply pass before the interactive apply phase. Apps whose blocking process is not running are installed without prompting. Items skipped in the silent pass are shown in the interactive dialog as usual. |
SwiftDialogEnabled |
Boolean | true |
Show swiftDialog prompts during the apply phase. If false (or swiftDialog is not installed), blocking process handling falls back to the configured BlockingProcessAction. |
AppTitle |
String | "Third Party Patcher" |
Title shown in swiftDialog windows. |
DialogOnTop |
Boolean | true |
When true, the swiftDialog window floats above all other windows. |
DialogIcon |
String | "" |
Path to a custom icon for the apply dialog. Empty = use the system computer icon. Supports absolute paths, SF=<symbol> notation, or an SF Symbol name directly. |
UseOverlayIcon |
Boolean | true |
When true, a small overlay icon is composited onto the dialog icon. Automatically disabled when swiftDialog is not installed. |
OverlayIcon |
String | "" |
Path to the overlay icon image. Empty = auto-detect from known MDM agents (Jamf, Intune, etc.). |
DialogScreenPosition |
String | "center" |
Position of the main apply dialog: topleft, left, bottomleft, top, center, bottom, topright, right, or bottomright. |
DialogScreenProgressPosition |
String | "bottomright" |
Position of the progress/status window during apply. Same position values as DialogScreenPosition. |
UnattendedExit |
Boolean | true |
When true, the apply completion dialog closes automatically after UnattendedExitSeconds if the user does not interact. |
UnattendedExitSeconds |
Integer | 60 |
Seconds before the apply completion dialog auto-closes when UnattendedExit is true. |
| Key | Type | Default | Description |
|---|---|---|---|
BlockingProcessAction |
String | "prompt" |
Action when a blocking process is running during apply: "ignore" (skip the check entirely), "kill" (force-quit silently), "notify" (brief notification; skip label if still running), "prompt" (timed dialog; user can quit or skip), "defer" (skip silently; retry next cycle). |
BlockingProcessCountdownSeconds |
Integer | 120 |
Seconds of countdown in the blocking process prompt before the automatic action fires. |
| Key | Type | Default | Description |
|---|---|---|---|
DeferralCountdownSeconds |
Integer | 300 |
Seconds of countdown in the deferral prompt before the automatic action fires. |
DeferralAutomaticAction |
String | "defer" |
Action when the deferral countdown expires with no user input: "defer" (postpone to next cycle) or "kill" (force-quit blocking app and apply). |
DeferralTimerDefault |
Integer | 240 |
Default deferral duration in minutes applied when the user accepts without choosing a custom time (4 hours). |
DeferralTimerMenu |
String | "5,30,60,120,240,480,1440" |
Comma-separated list of deferral durations in minutes shown in the pop-up menu. |
DeferralTimerFocus |
Integer | 60 |
Minutes to defer automatically when Focus/DND is active. Applied silently and does count toward the deferral limit. |
These values appear in the help popover in PatcherMenu and Available Software to give users a point of contact.
| Key | Type | Default | Description |
|---|---|---|---|
SupportTeamName |
String | "IT Support Team" |
Display name for your IT team. |
SupportTeamEmail |
String | "support@company.com" |
Support email address. Shown as a clickable mailto: link. |
SupportTeamPhone |
String | "None" |
Support phone number. Set to "None" to hide the field. |
SupportTeamWebsite |
String | "None" |
Support portal URL. Set to "None" to hide the field. |
These keys control the optional menu bar status item installed for the current console user.
| Key | Type | Default | Description |
|---|---|---|---|
ShowMenuBarApp |
Boolean | false |
When true, the scheduler installs and loads the PatcherMenu LaunchAgent for the current console user. When false, the LaunchAgent is unloaded and the plist removed. Managed automatically at each scheduler run. |
MenuBarIcon |
String | "" |
Icon displayed in the menu bar status item. Accepts an SF Symbol name (e.g. "gear") or an absolute path to a template-mode PNG. A template PNG adapts automatically to light/dark menu bar appearance. Empty = built-in default. |
ShowHelpButton |
Boolean | true |
When true, a Help (?) button is shown in the menu bar popover header. Tapping it displays the support contact information. |
ShowActivitySection |
Boolean | true |
When true, the Last Activity section (scan / check / stage / apply dates) is shown in the menu bar popover. |
ShowQuitButton |
Boolean | false |
When true, a Quit button is shown in the menu bar popover footer. |
ShowMenuDownloadAction |
Boolean | true |
When true, the "Download New Updates" option appears in the Run Now menu. |
ShowMenuCheckAction |
Boolean | true |
When true, the "Check for Updates" option appears in the Run Now menu. |
ShowMenuScanAction |
Boolean | true |
When true, the "Full Discovery Scan" option appears in the Run Now menu. |
ShowScanCheckProgressDialog |
Boolean | true |
When true, scan and check operations triggered from PatcherMenu display a swiftDialog progress window. |
These keys control the Available Software self-service catalog application.
| Key | Type | Default | Description |
|---|---|---|---|
CompanyName |
String | "Patcher Corp." |
Organization name shown in the Available Software sidebar header above the app title. |
CustomAppIconPath |
String | "" |
Absolute path to a PNG or ICNS file used as the Available Software app icon, overriding the built-in icon in the Dock, Finder, and app switcher. Empty = use the default built-in icon. |
AddToDockOnSelfServiceInstall |
Boolean | false |
When true, apps successfully installed via self-service are automatically added to the current user's Dock if not already present. |
Third Party Patcher can send webhook notifications to Microsoft Teams or Slack. See Reporting for the full report format.
| Key | Type | Default | Description |
|---|---|---|---|
WebhookFeature |
String | "FALSE" |
Controls when scheduled webhook reports are sent: "FALSE" (never), "FAILURES" (failures only), "ALL" (successes and failures). |
WebhookURLTeams |
String | "" |
Microsoft Teams incoming webhook URL. |
WebhookURLSlack |
String | "" |
Slack incoming webhook URL. |
WebhookAttributes |
String | "deviceName,serial,osVersion,user" |
Comma-separated list of device attributes included in webhook payloads, in display order. MDM info is always appended if detected. Supported values: deviceName, hostname, serial, osVersion, osBuild, osName, model, hardwareModel, user, patcherVersion, installomatorVersion. |
WebhookSchedule |
String | "immediate" |
When to send accumulated webhook reports: "immediate", "daily", "weekly", "monthly", or "patchDay". |
WebhookScheduleWeekday |
Integer | 1 |
For weekly schedule: day of week to send (0=Sunday … 6=Saturday). |
WebhookScheduleMonthDay |
Integer | 1 |
For monthly schedule: day of month to send (1–31). |
WebhookScheduleHour |
Integer | 8 |
For daily, weekly, and monthly schedules: hour of day (0–23) at which to send. |
WebhookStageFailureThreshold |
Integer | 2 |
Minimum consecutive stage failures for a label before it is included in webhook notifications. |
WebhookSelfServiceFeature |
String | "FALSE" |
Controls whether an immediate webhook is sent after a user-initiated self-service install, regardless of WebhookSchedule. Options: "FALSE" (never), "FAILURES" (failed installs only), "ALL" (success and failure). |
| Key | Type | Default | Description |
|---|---|---|---|
LogRetentionDays |
Integer | 90 |
Number of days to retain log files in /Library/Logs/Patcher/. Files older than this are deleted during the cleanLogs run. Set to 0 to disable automatic log cleanup. |