What is lcl.host?

With just two easy commands, you can setup HTTPS in your local environment with lcl.host. The lcl.host CLI will walk you through the steps to create a secure browsing context in your local browser using HTTPS.

lcl.host is made by the Anchor team (opens in a new tab) that makes production-grade private Certificate Authorities, and now you can use the same technology in your development environment.

When do I need HTTPS locally?

There are a number of reasons why you will need HTTPS in your development environment to reduce pain and suffering.

You're dealing with...

• Mixed Content

  In an ideal world, all content is served over HTTPS. Unfortunately in the real world a secure webpage may request unprotected content over HTTP. You will need to add HTTPS to your local environment to mimic the mixed content in your production environment.

• CORS errors

  When a webpage has mixed content the browser security context may change, causing a CORS error. By keeping the browser in the same security context as production, you can reproduce and debug the CORS issues locally.

• HTTP/2

  HTTP/2 and HTTP/3 require (or make it hard to avoid) using TLS. If you want to test something like loading performance on HTTP/2 or reproduce behavior specific to HTTP/2 then you will need HTTPS in your local environment as insecure HTTP/2 isn't supported on localhost.

• Secure Cookies

  Generally browsers handle cookies in localhost the same as in production, with the exception of secure cookies. To keep behavior consistent across browsers, use HTTPS in your local environment so that it matches your production environment.

• OAuth and secure 3rd Party endpoints

  Many external organizations require HTTPS in their callbacks for security, even in local development, such as Facebook's OAuth. To test them out, you'll need to switch your local development to HTTPS.

• Localhost Apps and Marketplaces

  There are tools that run a webserver on a local port and are accessible from the browser via http://localhost:[PORT] (opens in a new tab) that occasionally require HTTPS. Many marketplaces such as Heroku, Slack, and AWS also require HTTPS for developing marketplace apps.

• Requirement for tools

  Certain development tools require HTTPS in development to ensure that they function correctly.

You are developing...

• On the Public Web

  Your production environment has a public certificate, and you want to mimic that environment locally.

• SaaS

  With services that are connected to the internet, such as a Ruby on Rails SaaS project.

• Microservices

  A React app that talks to a separate backend API, setting cookies and making API requests.

Benefits of lcl.host

Dev/Prod Parity

It's important to maintain development/production parity (opens in a new tab) to keep development and production as similar as possible so that the gap between the environments is kept small. Within a secure browser context like lcl.host you can develop in similarly secure conditions. lcl.host is a Fully Qualified Domain Name (FQDN) that you don't have to setup, maintain, or register in order to use it.

Usually localhost acts like HTTPS and correctly handles Service Workers, Progressive Web Apps (PWAs), payment APIs, credential APIs, and web authentication APIs. However in certain cases you will need HTTPS in your development environment to make it act like your production environment.

Another benefit of using HTTPS locally is that some features of WebRTC and Web Workers require it, even on localhost. Similarly, when using gRPC (opens in a new tab) you will need HTTP/2 to establish bidirectional streaming, which also requires TLS.

What is anchor lcl?

The Anchor CLI has many commands for setting up your certificates in all environments. When you run anchor lcl, the CLI does the following:

1. Configures your local certificate stores to trust Anchor-provided certificates from your account, and your account only.
2. Detects the application type.
3. Adds WebPKI-linted, CA certificates to your filesystem that are specific to your app or service.
4. Finally, the Anchor Setup Guide shows you a few easy steps to set up and use ACME for future certificate provisioning.

What does Anchor lcl.host do?

lcl.host maps your localhost, or the loopback address (127.0.0.1), to a specific subdomain.lcl.host. Then you use that subdomain in your dev environment to work in a secure context. You can setup multiple subdomains for different projects, and each subdomain maps to a specific port of your localhost.

Under the hood, this is how lcl.host works:

1. When you open your browser and go to your locally running site in HTTPS, your browser checks the certificate of your local development server.
2. The browser sees that the certificate has been signed by the Anchor-generated Certificate Authority (CA), which the browser then confirms is a trusted CA.
3. Anchor is listed as a trusted authority, so your browser trusts the certificate and creates an HTTPS connection to your local site.

FAQ

What is TLS and why do I need it?

TLS, formerly called SSL, ensures that your data and users are safe from attacks by encrypting the traffic between the client and the server. Learn more about TLS here.

Once I setup lcl.host, can I share my certificate so my team can use it too?

lcl.host is free for life! There is no need to share user accounts or certificates across team members. lcl.host is a free tool for developers so each team member should set up their own certificates as they are specific to the team member's account.

If you need tools for collaborating or want to create certificates for your production environment, create an organization account on Anchor.

Can I use lcl.host in prod or staging?

For production and staging environments, go to Anchor.dev (opens in a new tab) to setup your certificate so that it can be used in staging or production.

What is a .pem file?

Privacy Enhanced Mail (PEM) is a file type for Public Key Infrastructure (PKI) files used for keys and certificates. The certificate created by lcl.host will end in cert.pem and the key will end in key.pem. The chain file includes the end-user certificate and the intermediate certificate that issues the end-user certificate.

Why use a FQDN instead of localhost?

lcl.host, a FQDN, maintains a secure context and is lightweight to setup. Localhost sometimes acts like a secure context but other times it does not, so it's easier to always use a FQDN like lcl.host.

How is lcl.host better than mkcert?

By default you get a high quality, linted certificate, held to the same standard as WebPKI certificates, such as a LetsEncrypt certificate.

Does my project need to have globally unique name?

No, it doesn't need to. Due to each subdomain being specific to your local environment, there's no worry about project names overlapping.

Will my dev environment be publicly accessible (on the internet)?

No, your dev environment is still secure on your machine. If someone else tries to visit YourSubdomain.lcl.host, they will get an error. This is because YourSubdomain is going to their localhost, or their loopback address, not yours. All of your subdomains are only accessible from on your local dev machine.