Skip to main content

Getting Started

Patch Extend is in Beta

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.

Do not rely on double-clicking the profile

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​

ItemValue
Demo packageTomatoBar v3.6.1 (appInZip), architectures arm64 and x86_64
Extend app IDextend-docs-quickstart
Feed file on disk/Library/Application Support/Alectrona/PatchExtend/quickstart-feed.json
Downloadsquick-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​

  1. Download patch-extend-feed.quickstart.json.
  2. 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​

  1. Download Patch-Extend-Quickstart-Unsigned.mobileconfig.
  2. Open it in a text editor (it is plain XML).

Confirm the com.alectrona.patch payload sets PatchExtendFeeds to:

  • Type = file
  • URI = /Library/Application Support/Alectrona/PatchExtend/quickstart-feed.json (same path as step 1)
  • Priority = 1
  • RequireSignature = 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:

Then confirm on the Mac:

  1. The profile is present as a computer / device profile (not only under the logged-in user’s profiles).
  2. 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-quickstart from 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-run is 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.app install 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 though extend-docs-quickstart is a unique id. That failure is a collision, not a silent fallback to the catalog title.

5. Clean up​

  1. Unassign or delete the computer-level profile in your MDM (and confirm it is removed on the Mac).
  2. Optionally delete the feed file:
sudo rm -f "/Library/Application Support/Alectrona/PatchExtend/quickstart-feed.json"

Next steps​