SSL Certificates

CMDHub provides automatic HTTPS for local .test domains by acting as its own Certificate Authority (CA). This means you get a real padlock in your browser — no warnings, no click-throughs — for every local service running behind the reverse proxy.

How it works

CMDHub root CA  →  signs  →  *.myapp.test wildcard cert
      ↓                              ↓
macOS Keychain (trusted)       reverse proxy (serves HTTPS)

1. CMDHub generates a root CA once and stores it in ~/.cmdhub/certs/.
2. The CA is added to the macOS System Keychain as a trusted root, so the OS and all Keychain-aware browsers accept it.
3. For each project, CMDHub generates a wildcard certificate (*.myapp.test) signed by the root CA.
4. The reverse proxy uses these certs to terminate HTTPS on port 443.

CA Status

Settings → Proxy shows a CA Status indicator. The three states are:

Status	Meaning
Generated & Trusted	CA exists and is trusted in macOS Keychain. Everything is working.
Generated, Not Trusted	CA certificate exists on disk but has not been added to Keychain. Click Trust Certificate to fix.
Not Generated	No CA has been created yet. Click Generate Certificates to create one.

“Not Generated” appears when:

• You are enabling the proxy for the first time.
• The ~/.cmdhub/certs/ directory was deleted or the CA files were removed manually.
• A previous certificate generation attempt failed part-way through.

Generating certificates

If CA Status shows Not Generated:

1. Open CMDHub settings (gear icon) → Proxy tab.
2. Click Generate Certificates.
3. Enter your macOS password when prompted — this is required to add the CA to System Keychain.
4. CA Status updates to Generated & Trusted.

CMDHub will:

• Create ca.pem and ca-key.pem in ~/.cmdhub/certs/
• Generate a wildcard cert for each project domain (*.myapp.test, etc.)
• Register the CA as a trusted root in macOS System Keychain

Trusting the CA

If CA Status shows Generated, Not Trusted (the CA exists but wasn’t added to Keychain):

1. Click Trust Certificate in Settings → Proxy.
2. Enter your macOS password when prompted.
3. CA Status updates to Generated & Trusted.

Verify manually in Keychain Access:

1. Open Keychain Access (Spotlight → “Keychain Access”).
2. Search for CMDHub.
3. The CA certificate should appear with a blue trust badge (white cross on blue background).

If the certificate appears but shows a red X, double-click it → expand Trust → set “When using this certificate” to Always Trust.

Regenerating certificates

Regenerate when:

• A browser shows a certificate warning for a .test domain
• You switched macOS user accounts
• A macOS upgrade reset Keychain trust
• You want to rotate credentials

Steps:

1. Open CMDHub settings → Proxy tab.
2. Click Regenerate Certificates.
3. Enter your macOS password when prompted.
4. Quit and relaunch your browser — browsers cache certificate state aggressively.

Regeneration replaces the existing CA and all project certs. The old CA is removed from Keychain and the new one is added automatically.

Certificate file locations

All certificate files live in ~/.cmdhub/certs/:

~/.cmdhub/certs/
├── ca.pem              ← Root CA certificate (public, safe to share/import)
├── ca-key.pem          ← Root CA private key (keep private)
├── myapp.test.pem      ← Wildcard cert for *.myapp.test
├── myapp.test-key.pem  ← Private key for *.myapp.test
└── ...                 ← One pair per project domain

Caution

ca-key.pem is the private key for your local CA. Do not commit it to git or share it. Anyone with this key can issue certificates trusted by your machine.

Browser compatibility

Browser	Certificate source	Notes
Safari	macOS Keychain	Works automatically after trusting
Chrome	macOS Keychain	Works automatically after trusting
Arc / Brave / Edge	macOS Keychain	Chromium-based, works automatically
Firefox	Own cert store	Requires extra setup (see below)

Firefox

Firefox does not use the macOS Keychain by default. Choose one of:

Option A — Enable enterprise roots (recommended):

1. Open about:config in Firefox.
2. Search for security.enterprise_roots.enabled.
3. Set it to true.
4. Restart Firefox. CMDHub’s CA is now trusted automatically.

Option B — Manual import:

1. Open Firefox Preferences → Privacy & Security → scroll to Certificates → click View Certificates.
2. Go to the Authorities tab → click Import.
3. Select ~/.cmdhub/certs/ca.pem.
4. Check Trust this CA to identify websites → click OK.

Troubleshooting

CA Status stuck on “Not Generated” after clicking Generate:

• Check that ~/.cmdhub/certs/ is writable: ls -la ~/.cmdhub/
• Look at the CMDHub log for certificate generation errors.
• Try quitting and relaunching CMDHub, then generating again.

Browser still shows a warning after regenerating:

• Quit and relaunch the browser — certificate state is cached per session.
• Clear the browser’s SSL cache: Chrome → Settings → Privacy → Clear browsing data → check “Cached images and files”.
• Confirm CA Status shows Generated & Trusted in CMDHub settings.

Firefox shows a warning even after trusting:

• Verify security.enterprise_roots.enabled is true in about:config, or use the manual import method.
• After importing, restart Firefox fully.

See Troubleshooting → SSL certificate not trusted for additional steps.