Click Enable in Mugshot. The guided setup asks you to approve the privileged helper in System Settings → General → Login Items and grant the helper Full Disk Access so it can update the protected sudo PAM configuration. The window checks each approval and continues when it is available.

The package installs the selected sudo component using the system Installer’s privileges, so this separate helper setup is generally unnecessary at installation. The app may still need its helper for later configuration changes or uninstallation.

An older development installation may have left the Python LaunchAgent com.lorenzo.faceid running alongside Mugshot. Both engines use the same socket, so requests can reach the old Python process, which macOS may deny camera access.

Mugshot now disables and unloads this legacy job before starting its own engine. The change persists across restarts and also runs after DMG and automatic updates. The old configuration remains on disk; your enrolled face and permissions are kept.

Use the copy in Applications and open its Configure… setup. An older build may have left an authorization tied to a different code signature.

For a stale grant, remove the old Mugshot entry with −, completely quit System Settings, then reopen Accessibility. Add /Applications/Mugshot.app with + and enable it. Use Restart Mugshot and resume in setup if the process still waits. Do not rebuild or re-sign the app during this sequence.

Local builds now use a persistent signing certificate. Installing a compatible rebuild preserves the permission identity. Migrating from an old ad-hoc build requires fresh consent once; the package clears the incompatible Mugshot camera and Accessibility entries before opening setup.

Open Mugshot and read the status at the top of its window. Check that your face is registered and sudo is enabled, then click Test. Improve lighting or add an appearance if recognition misses you. Use Copy diagnostics for a support report; from a checkout, bash scripts/diagnose.sh checks the installed components.

Use the package installer to update an app installed by a package. That copy can be owned by root, so dragging another app over it may fail. Reopen the updated copy from Applications after installation.

Click Uninstall Mugshot… at the bottom of the main window. The uninstaller removes the sudo rule and PAM module, restores the system Touch ID rule, unregisters the helper and login item, deletes the stored lock-screen password, and offers to remove your face data and move the app to the Trash.

Dragging the app to the Trash alone leaves its sudo integration behind. If the app’s helper setup prevents uninstallation, remove that integration from Terminal:

sudo bash /Applications/Mugshot.app/Contents/Resources/scripts/pam-uninstall-root.sh

Use macOS 14+ on Apple Silicon, Xcode Command Line Tools and Python 3.12. For portable release bundles, use the python.org framework build rather than a Homebrew Python compiled for your current macOS version.

git clone https://github.com/Lorenzo-Coslado/macos-faceid.git
cd macos-faceid
./install.sh

This prepares dependencies, downloads models and builds a development package at build/Mugshot-dev.pkg. Open that package to install; the script stages the app rather than overwriting the running copy in Applications.

For a self-contained local app and package:

./scripts/build-standalone.sh
ALLOW_UNSIGNED_PKG=1 ./scripts/build-pkg.sh dist/Mugshot.app dist/Mugshot-local.pkg

Local builds use a persistent certificate in a dedicated keychain under ~/Library/Application Support/Mugshot/Signing. Keep that directory outside the checkout. Initialization may ask for native administrator approval to trust the certificate for code signing. If its identity is missing, restore it; builds refuse to silently generate a replacement or use LOCAL_SIGN_IDENTITY=-.

An explicit LOCAL_SIGN_IDENTITY can select an existing signing certificate. Keep that identity stable between builds. The package compares the old and new designated requirements, verifies the installed payload and opens that exact app for setup. ALLOW_UNSIGNED_PKG=1 permits local test packaging; it does not notarize the app or make the local certificate suitable for distribution to other Macs.

The public release pipeline requires Developer ID Application, Developer ID Installer, and a notarytool profile (default: faceid-notary):

MARKETING_VERSION=1.2.0 BUILD_VERSION=9 ./scripts/build-release.sh

It signs the app, notarizes and staples the artifacts, and produces release packages and disk images. Set MARKETING_VERSION and BUILD_VERSION for the candidate. Use the same Developer ID team across releases. BUILD_PKG=0 skips the package. See the script headers for signing and notarization options. The release build installs requirements-build.txt for headless DMG layout. See the release procedure for verification, draft preparation, resuming notarization and the final public publication step.

Relevant checks:

.venv/bin/python -m faceid.selftest
.venv/bin/python tests/test_engine.py
bash scripts/check-lock-screen-setup.sh
python3 tests/test_signing_identity.py
bash scripts/check-i18n.sh

The signing tests reproduce the old ad-hoc identity mismatch, confirm that different builds with the persistent certificate remain compatible, and reject unsigned resource changes. Permission tests use fixtures; they do not replace verification on an installed app.