Docs · App & code signing
macOS agent
What it does
Liminal Keys for Mac holds the device credential from enrollment, talks to the production API,
and makes virtual certificates available to macOS. When
codesign or Xcode requests a signature, the digest is sent to cloud custody for signing.
The Mac keeps public certificates and device credentials only — never private key bytes.
Install Liminal Keys for Mac
- Download the notarized package from the public page www.liminalkeys.com/download/mac/ (no Console sign-in), or use Download Liminal Keys for Mac in Console as an admin
- Open the DMG, drag Liminal Keys for Mac (the app file is
Liminal Keys Virtual Smartcard.app) to Applications - Gatekeeper should allow a normal double-click for notarized builds — use Open anyway only if macOS still prompts
- Enroll with a one-time enrollment code from your administrator (Devices in Console)
Customers do not build from source. Download does not enroll the Mac — a valid, unconsumed enrollment code is still required.
Enrollment (Host UI)
- In Console, open Devices and issue an enrollment code
- In Liminal Keys for Mac, set API URL to
https://api.liminalkeys.com - Paste the enrollment code, complete enroll, then refresh identities
- Approve the Liminal signing extension in System Settings if macOS prompts
Enrollment (Host CLI)
For build Macs and CI, use the bundled Host CLI located at:
/Applications/Liminal\ Keys\ Virtual\ Smartcard.app/Contents/Helpers/LiminalKeysHostCLI
You can optionally create a symlink to put it on your PATH (run manually; the app does not modify system directories):
sudo ln -s "/Applications/Liminal Keys Virtual Smartcard.app/Contents/Helpers/LiminalKeysHostCLI" /usr/local/bin/liminal-keys
Set the production API URL explicitly and run enrollment:
export LIMINAL_KEYS_API_BASE_URL=https://api.liminalkeys.com
export LIMINAL_KEYS_ENROLLMENT_CODE='…from Console…'
liminal-keys enroll --json
liminal-keys status --require-enrolled --json
Details: CI & pipelines. Prefer environment variables for enrollment codes so they do not appear in shell history or committed scripts.
Signing with codesign and Xcode
After identities appear, use your normal signing workflow. Select the Liminal virtual identity where you would select a local certificate. The extension presents the public cert; the private operation happens in cloud custody (Key Vault) through the API.
Sign confirmation
Sign confirmation prompts are not yet available in the macOS agent. If a Console policy rule has Require user confirmation enabled, matching signs are denied and recorded in audit. Leave confirmation unchecked until the agent supports prompts.
Troubleshooting checklist
If signing or extension registration encounters issues, run the built-in diagnostic tool first:
/Applications/Liminal\ Keys\ Virtual\ Smartcard.app/Contents/Helpers/LiminalKeysHostCLI doctor
The doctor command verifies enrollment, API health, virtual smartcard registration, extension election, keychain isolation, policy permission, and runs a scratch signing probe.
- API reachable:
curl -s https://api.liminalkeys.com/healthshould return OK - Enrollment code not expired or already consumed
- Policy applied in Console after identity or rule changes
- Token extension enabled for the user session
- Host shows Connected and lists the expected certificate
- Leave Require user confirmation unchecked (not supported yet — matching signs are denied)
- If Refresh identities fails, use Copy on the error panel when contacting support