Skip to content

HTTPS for containers

Web services running in OrbStack are accessible via HTTPS by their orb.local domain names. No setup is required; OrbStack automatically sets up a reverse proxy with a local CA and TLS certificates for each domain.

This removes the need to generate, install, and trust self-signed certificates manually and configure a reverse proxy for each service, which can easily take hours.

Simply visit https://orb.local to get started in under 5 seconds. OrbStack will automatically ask to install the certificate on first use.

HTTPS connection to OrbStack domain

Between containers

OrbStack automatically adds the OrbStack root CA certificate to containers, so you can use orb.local domains between containers seamlessly without disabling certificate verification.

To disable this behavior, set the dev.orbstack.add-ca-certificates label to false.

Firefox

If you're on Firefox 119 or older, certificates added to the macOS system keychain are ignored by default, so OrbStack's certificate won't be trusted. To fix this:

  1. Visit about:config
  2. Dismiss the warning ("Accept the Risk") if necessary
  3. Set security.enterprise_roots.enabled to true

Firefox about:config

No restart is necessary for the setting to take effect.

Security

OrbStack's HTTPS implementation is one of the most secure ways to develop locally with HTTPS. In a local HTTPS setup, the root CA's private key is very sensitive and may allow intercepting all HTTPS traffic on the machine, so it needs to be protected.

In OrbStack, private keys are stored encrypted in the macOS keychain with access limited to OrbStack, enforced by code signatures. They are temporarily decrypted when needed and erased from memory shortly after use, and domains in certificate signing requests are checked to prevent misuse. Keys are never stored unencrypted on disk, making it much more secure than popular developer tools like mkcert that expose unencrypted keys.

Redirect port 443

If you want to run your own HTTPS server without using our proxy, listen on port 443 or 8443.

Alternatively, you can use the https-port label to redirect port 443 to any port:

bash
docker run --rm -l dev.orbstack.https-port=8443 nginx

Or with Compose:

yaml
services:
  nginx:
    image: nginx
    labels:
      - dev.orbstack.https-port=8443