ssl-proxy

name

ssl-proxy

description

Terminate HTTPS locally for development servers with auto-generated trusted certificates. Use when you need HTTPS on localhost, are testing Stripe webhooks that require HTTPS, building service workers (which require HTTPS), testing mixed-content policies, or any scenario where your local dev server must be accessible via https://. Triggers include "HTTPS locally", "trusted cert localhost", "https dev server", "SSL local", "mkcert", "browser security warning", "service worker local", "mixed content error".

ssl-proxy

Terminate HTTPS locally for dev servers with auto-generated mkcert certificates. Zero browser security warnings.

When to use

• Testing Stripe, PayPal, or any payment SDK that requires HTTPS
• Building Progressive Web Apps or service workers (HTTPS required)
• Testing secure cookies (Secure flag requires HTTPS)
• Reproducing mixed-content policy issues
• Any time you get "Not Secure" in the browser address bar on localhost
• OAuth flows that require a registered HTTPS redirect URI

Prerequisites

1. mkcert installed: brew install mkcert (macOS), choco install mkcert (Windows), or download from https://github.com/FiloSottile/mkcert/releases
2. ssl-proxy installed globally
3. CA installed once: ssl-proxy trust install

Installation

ssl-proxy is a global CLI tool. Do NOT add it as a project dependency.

npm install -g @your-org/ssl-proxy

Quick Start

# One-time: install CA into system trust store
ssl-proxy trust install

# Start HTTPS proxy for your dev server on port 3000
ssl-proxy start --from 3000
# -> https://localhost:3443 -> http://localhost:3000

Usage Patterns

Basic proxy

ssl-proxy start --from 3000
# Starts: https://localhost:3443 -> http://localhost:3000

Custom HTTPS port

ssl-proxy start --from 3000 --to 8443
# Starts: https://localhost:8443 -> http://localhost:3000

Custom domain (requires /etc/hosts entry)

ssl-proxy cert generate myapp.test
ssl-proxy start --from 3000 --domain myapp.test
# Starts: https://myapp.test:3443 -> http://localhost:3000
# Add to /etc/hosts: 127.0.0.1  myapp.test

Multiple proxies from project config

# Create .ssl-proxy.json in project root
ssl-proxy config init

# Edit .ssl-proxy.json, then start all proxies
ssl-proxy start

List running proxies

ssl-proxy list

Stop a proxy

ssl-proxy stop react-app   # by label
ssl-proxy stop a3b4c5d6   # by ID prefix

Config File (.ssl-proxy.json)

Place in project root to define multiple proxies:

{
  "proxies": [
    { "httpsPort": 3443, "httpPort": 3000, "label": "react-app" },
    { "httpsPort": 4443, "httpPort": 4000, "label": "api-server" }
  ]
}

Run ssl-proxy start with no arguments to start all defined proxies.

CLI Reference

Command	Description
ssl-proxy start --from <port>	Start HTTPS proxy
ssl-proxy start --from <port> --to <port>	Use specific HTTPS port
ssl-proxy start --from <port> --domain <host>	Use custom domain
ssl-proxy start --from <port> --label <label>	Add a label
ssl-proxy stop <id-or-label>	Stop a proxy
ssl-proxy list	List running proxies
ssl-proxy status	Daemon and proxy summary
ssl-proxy cert list	List all certificates
ssl-proxy cert generate <domain>	Generate cert for domain
ssl-proxy cert revoke <id>	Delete a certificate
ssl-proxy trust install	Install CA into system trust store
ssl-proxy trust status	Check CA trust status
ssl-proxy config show	Show current configuration
ssl-proxy config init	Create .ssl-proxy.json

Environment Variables

Variable	Description	Default
LSPROXY_DATA_DIR	Data directory (SQLite, certs, socket)	~/.local-ssl-proxy
LSPROXY_API_PORT	Web dashboard port	9443
LSPROXY_LOG_LEVEL	Log level: debug, info, warn, error	info
LSPROXY_LOG_RETENTION	Request log retention days	7
LSPROXY_MKCERT_PATH	Override path to mkcert binary	(from PATH)
LSPROXY_DEV	Extra debug output (0 or 1)	0

Behavior

• Auto-start daemon: The daemon starts automatically when you run ssl-proxy start. No manual daemon management needed.
• Certificate reuse: If a valid cert for the domain already exists, it is reused. No unnecessary cert generation.
• Request logging: All proxied requests are logged to SQLite and visible in the dashboard at http://127.0.0.1:9443.
• Header redaction: Authorization and Cookie headers are stripped from stored request logs.

Troubleshooting

"mkcert not found in PATH"

Install mkcert: brew install mkcert (macOS) or see https://github.com/FiloSottile/mkcert/releases

Browser still shows security warning after trust install

Restart your browser. Chrome and Firefox require a restart to pick up new CA certificates.

"port N is already in use"

Another process (or another ssl-proxy) is using that port. Use --to <different-port> or stop the conflicting process.

HTTPS proxy starts but returns 502

Your dev server (the --from port) is not running. Start your dev server first, then the proxy will work automatically.

Custom domain not resolving

Add an entry to /etc/hosts: 127.0.0.1 myapp.test. The cert is valid but the OS needs to know where to route the hostname.