Troubleshooting

Helper tool not installing

Symptom: The proxy setup dialog shows an error, or ports 80/443 are not accessible after enabling the proxy.

Steps:

1. Open System Settings → General → Login Items & Extensions.
2. Scroll to Allow in the Background and look for CMDHub Helper. If it is listed but disabled, enable it.
3. If it is not listed, try re-installing: open CMDHub settings → Proxy → Install Helper Tool.
4. Check the system log for errors:

   log show --predicate 'subsystem == "dev.cmdhub"' --last 5m

Ports 80/443 already in use

Symptom: The helper tool installs but the proxy does not start, or you see “address already in use” in the CMDHub log.

Steps:

1. Find what is occupying port 80:

   sudo lsof -iTCP:80 -sTCP:LISTEN

2. Common culprits: macOS’s built-in Apache (httpd), nginx, or another reverse proxy.
3. Stop the conflicting service. For Apache:

   sudo apachectl stop
   sudo launchctl unload -w /System/Library/LaunchDaemons/org.apache.httpd.plist

4. Restart CMDHub’s proxy from settings → Proxy.

Services not starting

Symptom: A service stays in stopped or immediately goes to crashed.

Steps:

1. Click the service to open its log panel and read the error output.
2. Test the command manually in a terminal from the same working directory.
3. Check that the command is on $PATH in a login shell:

   /bin/zsh -l -c 'which your-command'

4. Verify the working directory is set correctly in the service settings.
5. If the command uses environment variables, confirm they are set in the service’s env config or .env file.

DNS not resolving

Symptom: myapp.test does not resolve, or the browser shows a “Server not found” error.

Steps:

1. Check that the resolver file exists:

   cat /etc/resolver/test

   It should contain nameserver 127.0.0.1 and port 15353.
2. If the file is missing, re-enable DNS in CMDHub settings → DNS.
3. Flush the DNS cache:

   sudo dscacheutil -flushcache && sudo killall -HUP mDNSResponder

4. Test CMDHub’s resolver directly:

   dig myapp.test @127.0.0.1 -p 15353

   You should see 127.0.0.1 in the answer section.
5. Avoid using .local as your TLD - it is reserved by mDNS and will not work reliably.

SSL certificate not trusted

Symptom: The browser shows a certificate warning for https://myapp.test.

Steps:

1. Open CMDHub settings → Proxy tab and check CA Status:
   • Not Generated → click Generate Certificates first, then return here.
   • Generated, Not Trusted → click Trust Certificate and enter your macOS password.
   • Generated & Trusted → proceed to step 2.
2. Click Regenerate Certificates in Settings → Proxy. This replaces the certs and re-adds the CA to macOS Keychain.
3. Quit and relaunch your browser — browsers cache certificate state aggressively.
4. To verify the CA is trusted, open Keychain Access, search for “CMDHub”, and confirm the certificate shows a blue trust badge.
5. If using Firefox: Firefox uses its own certificate store. Enable security.enterprise_roots.enabled in about:config, or import ~/.cmdhub/certs/ca.pem manually via Firefox Preferences → Privacy & Security → Certificates → Import.

See SSL Certificates for a complete guide to the certificate flow.

High CPU or memory usage

Symptom: CMDHub itself is using unexpected CPU or memory.

Steps:

1. Open the CMDHub popover and look at the resource monitor indicators next to each service.
2. Identify which service is consuming resources and check its logs for runaway behavior (tight loops, excessive logging).
3. If CMDHub’s own process is high (not a managed service), please file a bug report with the output of:

   sample CMDHub 5 -file /tmp/cmdhub-sample.txt && cat /tmp/cmdhub-sample.txt

Service health check always failing

Symptom: A service shows as unhealthy (orange) even though it seems to be working.

Steps:

1. Check the health check configuration - verify the URL, port, or command is correct.
2. Test the check manually:
   • HTTP: curl -o /dev/null -w "%{http_code}" http://localhost:3000/healthz
   • TCP: nc -zv localhost 5432
   • Shell: run the check command directly in a terminal.
3. Increase the timeout value if the service is slow to respond on startup.
4. Make sure the service is binding to localhost or 0.0.0.0, not only to a non-loopback interface.