Getting Started
Patch Extend is currently in beta and available for testing. We're actively refining the feature and building out comprehensive documentation. We recommend evaluating it in a test environment before deploying to production, and we welcome your feedback as we continue to improve!
This walkthrough configures Patch Extend with a computer-level configuration profile from your MDM (for example Jamf). Patch discovers Extend feeds from the PatchExtendFeeds preference on domain com.alectrona.patch. Deploy that preference as device / computer policy—the same scope Patch Agent and sudo patch … use.
Manually opening a .mobileconfig typically installs a user profile for the logged-in account. That is not equivalent to an MDM computer profile. sudo patch install runs as root and will not see a user-scoped profile the way it sees managed computer preferences. Use MDM or Jamf computer-level deployment for this walkthrough.
What you will use​
| Item | Value |
|---|---|
| Demo package | TomatoBar v3.6.1 (appInZip), architectures arm64 and x86_64 |
| Extend app ID | extend-docs-quickstart |
| Feed file on disk | /Library/Application Support/Alectrona/PatchExtend/quickstart-feed.json |
| Downloads | quick-start feed JSON, unsigned test profile |
The feed uses TomatoBar’s real download URL, checksum, designated requirement, bundle ID, and /Applications/TomatoBar.app install path, with a unique Extend app ID (extend-docs-quickstart) so a successful resolve comes from this private feed.
1. Place the feed file​
- Download patch-extend-feed.quickstart.json.
- Install it to the path the profile expects:
sudo mkdir -p "/Library/Application Support/Alectrona/PatchExtend"
sudo chown root:wheel "/Library/Application Support/Alectrona/PatchExtend"
sudo chmod 755 "/Library/Application Support/Alectrona/PatchExtend"
sudo cp ~/Downloads/patch-extend-feed.quickstart.json \
"/Library/Application Support/Alectrona/PatchExtend/quickstart-feed.json"
sudo chown root:wheel "/Library/Application Support/Alectrona/PatchExtend/quickstart-feed.json"
sudo chmod 644 "/Library/Application Support/Alectrona/PatchExtend/quickstart-feed.json"
The feed file must be readable by root. Keep write access administrator-controlled on both the file and its containing directory (see Host and secure feeds). Adjust the source path if your browser saved the download elsewhere.
Optionally validate the feed JSON against the published schema (file shape only; Patch does not need to be installed for this step)—see Feed schema for uvx / pipx / npx ajv-cli examples.
2. Inspect the test profile​
- Download Patch-Extend-Quickstart-Unsigned.mobileconfig.
- Open it in a text editor (it is plain XML).
Confirm the com.alectrona.patch payload sets PatchExtendFeeds to:
Type=fileURI=/Library/Application Support/Alectrona/PatchExtend/quickstart-feed.json(same path as step 1)Priority=1RequireSignature=false
RequireSignature must be present. Omitting the key causes the feed configuration to fail to decode. This quick start uses an unsigned local file feed (RequireSignature = false), which is a supported mode when the feed file stays under administrator control.
3. Deploy the profile (computer level)​
Deploy the .mobileconfig (or an equivalent payload) as a computer-level configuration profile with your MDM. Recommended options:
- Upload Patch-Extend-Quickstart-Unsigned.mobileconfig as a computer configuration profile and scope it to a test Mac, or
- In Jamf, use computer-level Application & Custom Settings for preference domain
com.alectrona.patchand include thePatchExtendFeedsarray from the profile (full payload guidance is on Configuring Patch Extend)
Then confirm on the Mac:
- The profile is present as a computer / device profile (not only under the logged-in user’s profiles).
- The display name Patch Extend Quick Start (Unsigned File Feed) (or your Jamf profile name) is listed.
4. Dry-run install​
sudo patch install extend-docs-quickstart --dry-run
What dry-run does​
- Resolves
extend-docs-quickstartfrom configured Extend feeds (and the builtin catalog). - May download and cache the TomatoBar zip, then check package integrity (for example sha256 / size) as applicable.
- Does not perform the real installation when
--dry-runis set.
Expected success (shape)​
You should see the process start for extend-docs-quickstart, reference TomatoBar / the cached zip, and finish with 0 errors / success state—similar to:
Starting installation process for 1 app(s): [extend-docs-quickstart]
...
Dry run enabled, installation skipped for TomatoBar (Extend Docs Quick Start).
...
Installation process completed with 0 errors; 1 app(s) reached success state.
Exact log wording can vary by Patch version; the important proof is that extend-docs-quickstart resolves at all. That app ID is not in the builtin catalog, so a successful resolve means your Extend feed was used.
If the command reports the app is missing, not found, or refused:
- Confirm the profile is deployed at computer level (not a user profile from double-clicking the
.mobileconfig) and the feed path is readable by root. - Remember append-only collisions: this demo reuses TomatoBar’s bundle identifier and
/Applications/TomatoBar.appinstall path. If TomatoBar (or another title with that bundle ID or path) is later added to the builtin catalog, Patch can refuse the feed entry even thoughextend-docs-quickstartis a unique id. That failure is a collision, not a silent fallback to the catalog title.
5. Clean up​
- Unassign or delete the computer-level profile in your MDM (and confirm it is removed on the Mac).
- Optionally delete the feed file:
sudo rm -f "/Library/Application Support/Alectrona/PatchExtend/quickstart-feed.json"
Next steps​
- Author a feed — more install methods and field notes
- Configure Patch Extend — Jamf payloads and key reference
- Host and secure feeds — HTTPS feeds, feed auth, package URL tokens
- Troubleshooting