Docs · App & code signing

macOS agent

Liminal Keys for Mac presents virtual certificates to macOS through its virtual smartcard. Private keys stay in cloud custody.

Console devices view used to enroll Mac hosts

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

  1. 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
  2. Open the DMG, drag Liminal Keys for Mac (the app file is Liminal Keys Virtual Smartcard.app) to Applications
  3. Gatekeeper should allow a normal double-click for notarized builds — use Open anyway only if macOS still prompts
  4. 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)

  1. In Console, open Devices and issue an enrollment code
  2. In Liminal Keys for Mac, set API URL to https://api.liminalkeys.com
  3. Paste the enrollment code, complete enroll, then refresh identities
  4. 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/health should 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
Never paste private keys, PKCS#12 files, or long-lived enrollment secrets into support tickets or public channels. Rotate enrollment codes if exposure is suspected.

← Console · CI & pipelines · Security →