Reverse Proxy

The CMDHub reverse proxy maps local .test domains to your running services so you can access them at addresses like https://frontend.myapp.test instead of http://localhost:3000.

How it works

CMDHub runs a local reverse proxy that:

1. Listens on ports 80 and 443 (via a privileged helper tool).
2. Routes incoming requests based on the subdomain.
3. Forwards traffic to the service’s configured port.
4. Terminates SSL using a locally-trusted self-signed certificate.

The DNS responder handles resolving *.test to 127.0.0.1, so no /etc/hosts editing is needed.

Setup

1. Open CMDHub settings (gear icon) and go to the Proxy tab.
2. Toggle Enable Reverse Proxy.
3. When prompted, install the helper tool - this is a privileged daemon that binds ports 80 and 443 so CMDHub itself does not need to run as root.
4. CMDHub generates a local CA certificate and installs it in your macOS Keychain so browsers trust it.

Note

The helper tool installation requires your macOS password once. After that it runs in the background without further prompts.

Domain structure

Each project gets a base domain derived from its name:

Project name: "My App"  →  base domain: myapp

Each service gets a subdomain derived from its name:

Service name: "Frontend"  →  subdomain: frontend
Full URL: https://frontend.myapp.test

Both the project domain and service subdomain can be customized in the project and service settings.

Per-project configuration

Field	Description
Domain	Base domain for the project (default: slugified project name)

Per-service configuration

Field	Description
Subdomain	Subdomain prefix (default: slugified service name)
Port	Port to forward to (default: taken from the service’s Port field)

If you leave Port blank on the service, make sure to set it in the service’s main settings so the proxy knows where to forward.

SSL certificates

CMDHub generates a local Certificate Authority (CA) and uses it to issue a wildcard certificate for each project domain (*.myapp.test). The CA is added to the macOS System Keychain so browsers show a real padlock with no warnings.

See the SSL Certificates page for the full flow — including how to generate, trust, and regenerate certificates, the CA Status indicator, browser-specific notes, and troubleshooting.

Offline page

When a request arrives for a service that is stopped or unhealthy, the proxy serves a styled “Service Offline” page. The page auto-refreshes every few seconds and updates as soon as the service comes back up.

Helper tool

The helper tool is a small privileged daemon (cmdhub-helper) installed in /Library/PrivilegedHelperTools/. It:

• Binds ports 80 and 443 and forwards connections to CMDHub’s proxy listener on an unprivileged port.
• Is registered as a launchd service so it starts at boot.
• Can be removed via CMDHub settings → Proxy → Uninstall Helper Tool.

See Troubleshooting if the installation fails.