TLS and Certificates

12.1 BrowserBox-managed TLS #

On normal local or self-hosted setups, bbx setup ensures host resolution is sane, obtains certificates through BrowserBox’s TLS flow, and starts BrowserBox in HTTPS mode when the expected certificate files exist.

BrowserBox automatically chooses the certificate strategy based on the hostname:

• Domain names with public DNS — Let’s Encrypt via certbot (http-01 challenge). An email address is required.

• Public IP addresses (e.g. 198.51.100.42) — Let’s Encrypt short-lived certificates (6-day validity) via acme.sh. Port 80 must be reachable. Falls back to mkcert if LE issuance fails.

• Private/loopback IPs (127.x, 10.x, 192.168.x, 172.16--31.x) — locally trusted certificates via mkcert.

• Local hostnames (localhost, *.local, *.test, etc.) — locally trusted certificates via mkcert.

An existing certificate pair in ~/sslcerts/ (or BBX_SSLCERTS_DIR) is reused whenever it is unexpired, its key matches the certificate, and its subject alternative names cover the configured hostname; a wildcard covers exactly one label. When a new certificate is needed, it is issued into a private temporary directory and installed only after it is verified, so a failed issuance leaves the existing pair in place.

Example with a public IP:

bbx setup --hostname 198.51.100.42 --port 8888
# Obtains a Let's Encrypt short-lived cert (auto-renewed by acme.sh)
bbx start

12.2 Customer-managed certificates #

If you want BrowserBox to use your own certificate material instead of BrowserBox-managed certificates, set:

export BBX_SSLCERTS_DIR="/path/to/your/certs"

The certificate directory must contain:

• fullchain.pem

• privkey.pem

When BBX_SSLCERTS_DIR is set and the directory already contains fullchain.pem and privkey.pem, BrowserBox skips all certificate generation (no Let’s Encrypt, no mkcert) and uses the provided certificates as-is.

When BBX_SSLCERTS_DIR is set but the directory does not yet contain certificates:

• bbx setup and bbx ng-run generate certificates into that directory instead of ~/sslcerts/. bbx ng-config validate checks the existing pair but never generates one.

• Nginx configuration points to the override directory.

• The Node.js runtime reads certificates from there.

• In --for mode (Section 9), certificates are generated into the override directory and chowned to the target user.

If you already have externally managed certificates, simply point BBX_SSLCERTS_DIR at the directory—BrowserBox detects existing certs and skips generation automatically.

For bbx ng-run, BrowserBox generates per-service names as <random>.<domain>. The certificate must cover those generated names. For example:

BBX_HOSTNAME=bbx-dev.corp.example
required nginx SAN: *.bbx-dev.corp.example

A shallower wildcard such as *.corp.example only covers one label under corp.example. When BBX_SSLCERTS_DIR points at an existing certificate and exactly one shallower wildcard parent matches the configured hostname, BrowserBox uses that parent for ng-run route generation and logs the decision. You can also make the parent explicit:

export DOMAIN="corp.example"
bbx ng-run --for bbxruntime

Another common TLS pattern is to run bbx setup --backend http and terminate TLS in nginx, Caddy, or another reverse proxy.