How to Integrate mkcert CA with macOS Keychain: Complete Developer Guide

Run mkcert -install to automatically register the local Certificate Authority with the macOS System keychain, enabling trust for all certificates generated by mkcert.

The mkcert tool by FiloSottile creates a local Certificate Authority (CA) that generates trusted development certificates. When you integrate mkcert CA with macOS Keychain, browsers and TLS clients automatically trust certificates signed by this local authority without security warnings. This integration works through platform-specific code in the mkcert repository that interacts directly with the macOS security framework and System keychain.

How mkcert Installs the CA into macOS Keychain

The integration process involves three distinct phases handled by specific source files in the repository: CA generation, CLI command parsing, and macOS-specific trust store manipulation.

CA Generation in cert.go

When you run mkcert for the first time, the newCA() function in cert.go generates a self-signed root certificate and private key. These files (rootCA.pem and rootCA-key.pem) are stored in ~/Library/Application Support/mkcert on macOS. The function creates a standard X.509 certificate with basic constraints set to act as a certificate authority.

The Installation Command Flow

When you execute mkcert -install, the entry point in main.go parses the flag and invokes the mkcert.install() method. This method checks that the system trust store is enabled before calling installPlatform(), which routes to platform-specific implementations based on the operating system.

macOS-Specific Trust Store Integration

The truststore_darwin.go file contains the critical integration logic for macOS Keychain. The installPlatform() function performs two essential operations:

1. Certificate Installation: It executes security add-trusted-cert -d -k /Library/Keychains/System.keychain <root-cert> to add the mkcert CA to the system keychain with default trust settings.

2. Trust Settings Configuration: Because older Go versions omit default trust parameters, the code explicitly manages trust settings by:

   • Exporting current trust settings via security trust-settings-export
   • Modifying the plist in-memory to set trust levels for sslServer and basicX509 policies
   • Re-importing the modified settings via security trust-settings-import

After installation, mkcert verifies the integration by attempting to validate the root certificate against the system pool using x509.Certificate.Verify in the checkPlatform() method.

Step-by-Step Integration Guide

Follow these commands to integrate mkcert with your macOS Keychain and generate trusted local certificates:

# Install mkcert via Homebrew

brew install mkcert

# Install the mkcert root CA into the macOS System keychain

mkcert -install

The -install flag triggers the full installation sequence described above, requiring administrative privileges to modify the System keychain.

After installation, generate certificates for your local development domains:

# Create a certificate valid for localhost and common local addresses

mkcert localhost 127.0.0.1 ::1

# This creates localhost.pem and localhost-key.pem in the current directory

Use these files with your local development server:

# Example: Python HTTPS server with mkcert certificates

python3 -m http.server 8443 \
  --bind 127.0.0.1 \
  --directory . \
  --certfile localhost.pem \
  --keyfile localhost-key.pem

Verifying the CA Installation

Confirm that mkcert successfully integrated with the macOS Keychain by listing the installed certificate:

security find-certificate -c "mkcert" -a -Z /Library/Keychains/System.keychain

This command searches the System keychain for certificates with "mkcert" in the common name and displays SHA-256 hashes. You should see your local CA certificate listed with trust settings applied for SSL.

Removing the mkcert CA from macOS Keychain

When you need to remove the CA (for example, when uninstalling mkcert), use the -uninstall flag:

mkcert -uninstall

This invokes uninstallPlatform() in truststore_darwin.go, which executes security remove-trusted-cert -d <root-cert> to delete the entry from the System keychain and removes associated trust settings.

Summary

• cert.go generates the root CA using newCA() and stores it in ~/Library/Application Support/mkcert
• main.go handles the -install flag and orchestrates the installation process through mkcert.install()
• truststore_darwin.go contains macOS-specific code that uses the security command to add the CA to /Library/Keychains/System.keychain and configures explicit trust settings for SSL and X.509
• The installation requires administrative privileges to modify the System keychain
• Use mkcert -uninstall to remove the CA using the uninstallPlatform() method

Frequently Asked Questions

Does mkcert require sudo to install the CA on macOS?

Yes, integrating mkcert CA with macOS Keychain requires administrative privileges. The security add-trusted-cert command modifies the System keychain located at /Library/Keychains/System.keychain, which is protected by macOS. The mkcert tool will prompt for your password when running mkcert -install to execute these privileged operations.

Where does mkcert store the root CA files on macOS?

mkcert stores the root CA certificate and private key in ~/Library/Application Support/mkcert (or the directory specified by the CAROOT environment variable). The files are named rootCA.pem and rootCA-key.pem. While the certificate is safe to share, you must protect the rootCA-key.pem file as it represents the private key of your local Certificate Authority.

Why does mkcert modify trust settings explicitly instead of relying on default trust?

According to the source code in truststore_darwin.go, older versions of the Go standard library omitted default trust settings when adding certificates via the Security framework. To ensure the CA is trusted for SSL/TLS connections (sslServer) and general X.509 validation (basicX509), mkcert exports the current trust settings, modifies the plist to add explicit trust policies, and re-imports the configuration using security trust-settings-import.

Can I use mkcert certificates in Safari without manual configuration?

Yes, once you run mkcert -install, certificates generated by mkcert are automatically trusted by Safari, Chrome, and other macOS applications that use the system certificate store. The integration modifies the macOS System keychain directly, so no manual certificate import is required in individual browsers or trust stores.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}