Local HTTPS

Local HTTPS gives your development site a browser-trusted HTTPS URL. LPM CLI handles TLS in front of your application.

Your application continues to use plain HTTP. Use local HTTPS for secure cookies, OAuth callbacks, service workers, secure WebSockets, and browser features that require a trusted origin.

The trust applies only to devices that trust your local certificate authority (CA).

How local HTTPS works

LPM CLI accepts the HTTPS or secure WebSocket connection. It sends the request to your application over plain HTTP or WebSocket.

Browser HTTPS/WSS → LPM CLI → Application HTTP/WS

LPM CLI creates one root CA for each machine. This CA signs the certificates for your local projects.

Per-machine root CA → Project certificate → Browser trust

The root CA is not part of LPM CLI. Its private key stays on your machine.

If you run lpm dev --https --port 4000, the browser connects to port 4000. LPM CLI gives the application a separate managed port.

Your application must use plain HTTP in this workflow. Disable framework HTTPS and let LPM CLI manage TLS.

Choose a workflow

Enable HTTPS in lpm.json

Add https: true to the lpm.json file next to package.json:

{
  "$schema": "https://cli.lpm.dev/schemas/lpm.json",
  "https": true
}

Start the project:

lpm dev

LPM CLI creates the project certificate and starts the HTTPS frontend. It renews the project certificate before it expires.

Use a command-line override for one run:

lpm dev --https       # enable HTTPS for this run
lpm dev --no-https    # disable HTTPS for this run

Approve the local CA

The first HTTPS run can require approval to install the local CA. LPM CLI asks only when the trust-store installation is necessary.

Approve the installation in an interactive terminal. If you decline, LPM CLI stops the HTTPS development run.

For an approved non-interactive run, use --yes:

lpm dev --https --yes

If lpm.json enables HTTPS, use this command:

lpm dev --yes

You can also prepare the machine before a development run:

lpm cert trust
lpm dev

To remove the CA from the trust store, run:

lpm cert uninstall

This command keeps the CA files on disk. You can trust the same CA again with lpm cert trust.

Use project hostnames

If one local service needs a project hostname, use proxy.host:

{
  "https": true,
  "proxy": {
    "host": "app.localhost",
    "port": 9443,
    "httpRedirect": false
  }
}

lpm dev

Open the HTTPS URL that lpm dev prints. For a project with multiple services, give each service a different services.<name>.host value.

Names below .localhost usually need no hosts-file entry. Names below these suffixes can require a managed hosts-file entry:

• .local
• .test
• .internal
• .home.arpa

See lpm proxy and lpm hosts for local routing and hosts-file management.

You can add a certificate hostname manually:

lpm cert generate --host api.app.local

This command adds a certificate name. It does not create a proxy route or a hosts-file entry.

Permit more DNS names

The cert block controls the DNS subtrees that a project certificate can cover:

{
  "https": true,
  "cert": {
    "extraPermittedDns": ["myapp.internal"],
    "allowPublicDns": false
  }
}

extraPermittedDns expands the permitted DNS subtrees. It does not add a certificate hostname, browser URL, proxy route, or hosts-file entry.

Add the actual browser hostname with one of these options:

• proxy.host
• services.<name>.host
• lpm cert generate --host

Public DNS names require an explicit opt-in:

{
  "cert": {
    "extraPermittedDns": ["staging.example.com"],
    "allowPublicDns": true
  }
}

CAUTION: Enable allowPublicDns only for DNS names that you control. This field increases the authority of your local CA.

Protect the local CA

The root CA is unique to your machine. LPM CLI does not ship or download a shared root CA.

Anyone with the root CA private key can create certificates that your machine trusts. Do not copy or commit this key.

On Unix systems, certificate directories must use mode 0700. Private keys must use mode 0600.

LPM CLI refuses to sign with a group-readable or world-readable CA private key. Run lpm cert status to get the repair command.

Project certificates for custom hostnames use a constrained project chain. The requested DNS permissions limit that project chain.

Platform and browser behavior

Chrome, Edge, Safari, and many Linux browsers use the operating-system trust store.

Firefox can use a separate trust store. If Firefox shows a warning, use one of these options:

• Set security.enterprise_roots.enabled to true in about:config.
• Import ~/.lpm/certs/rootCA.pem as a certificate authority in Firefox.

Use HTTPS on another device

A phone or another computer must trust your local CA before it accepts the project certificate.

Start a network development server with CA bootstrap enabled:

lpm dev --https --network --allow-ca-bootstrap

LPM CLI prints a plain HTTP URL for CA installation. Open that URL on the other device, then install and trust the CA.

CA bootstrap is off by default. The operating system selects its LAN port.

CAUTION: Anyone on the local network can download the CA certificate while the bootstrap server runs. The private key does not leave your machine.

Without CA bootstrap, copy ~/.lpm/certs/rootCA.pem to the device through a trusted method. Then install and trust the certificate manually.

Certificate files

Do not commit the generated project files. If the project does not ignore .lpm/, add it to .gitignore.

The default project certificate contains these names:

• localhost
• 127.0.0.1
• ::1

Renewal and rotation

LPM CLI creates a new project certificate in these cases:

• The certificate is missing.
• The certificate expires soon.
• The certificate does not contain a requested hostname.
• The certificate is not compatible with the active CA.

Project certificate renewal starts within 30 days of expiry. Root CA warnings start within 60 days and become urgent within 30 days.

LPM CLI never rotates the root CA automatically because rotation changes machine trust. When lpm cert status reports an expiry warning, rotate the CA:

lpm cert rotate

If rotation stops before it is complete, reconcile its state:

lpm cert reconcile --dry-run
lpm cert reconcile

The reconcile command also removes expired grace entries.

Common problems

The browser shows a certificate warning

Show the trust and certificate status:

lpm cert status

If the CA is not trusted, install it:

lpm cert trust

If only Firefox shows the warning, configure Firefox to use the operating-system trust store or import the CA.

The browser reports a hostname mismatch

Make sure that the URL hostname is in the project certificate. Add it with proxy.host, services.<name>.host, or lpm cert generate --host.

extraPermittedDns is not a certificate hostname. It only permits certificates below the configured DNS subtree.

LPM CLI reports unsafe permissions

Run lpm cert status. Then run the exact permission-repair command from its output.

The root CA expires soon

Run lpm cert rotate. LPM CLI replaces the CA and reissues the known project certificates.

Root CA rotation stopped

Preview the repair with lpm cert reconcile --dry-run. Then run lpm cert reconcile.

Another device does not trust the site

Install and trust rootCA.pem on that device. Use CA bootstrap or copy the certificate through a trusted method.

Local HTTPS or a tunnel?

If the site stays on your computer or local network, use local HTTPS. Each client device must trust your local CA.

If a remote person or service needs a public URL, use a tunnel.

See also

• lpm cert — manage the local CA and project certificates
• lpm dev — start the development server
• lpm proxy — configure local hostnames and proxy ports
• lpm hosts — manage local hosts-file entries
• Tunneling — expose a local service through a public URL
• lpm.json — configure project HTTPS