On this page
Short answers to the questions people ask most. If yours isn’t here, troubleshooting covers specific errors, and you can ask in the issue tracker.
How is this different from mkcert?#
mkcert creates locally trusted certificates. You still have to configure DNS (or /etc/hosts) and a server or
proxy for each name. lokal does names, certificates and routing together, and its CA is name-constrained, so it
can only sign .lokal names (and .local names, which lokal served before 0.6.0).
Does it work with Docker?#
Yes, for ports you publish on your Mac. With docker run -p 8080:80 …, run lokal service add app 8080.
Containers can’t resolve lokal’s names themselves.
Can I open my dev URLs on my phone or another computer?#
Not yet. lokal listens only on loopback by design. A LAN mode is on the roadmap.
Does it edit /etc/hosts?#
No. lokal doctor warns if /etc/hosts has an entry that conflicts with a lokal name.
Why only .lokal, and not .test or .internal?#
The CA is trusted system-wide, so it’s constrained to as few TLDs as possible: .lokal, which lokal serves, and
.local, which it served before 0.6.0 (dropping it would mean a new CA, and a password prompt, for everyone).
Adding .test or .internal would let a leaked key sign names that companies use for real internal hosts. The
security model explains the name constraints, and
.lokal names explains why .local names were removed.
Why does setup ask for my password twice?#
On macOS, once is sudo in Terminal. The second time is a macOS dialog, because macOS asks separately before it changes certificate trust settings. On Linux, setup asks once, for sudo. Setting up lokal lists the exact commands setup runs with sudo.
Is it macOS only?#
Mostly. On macOS, lokal needs macOS 14 Sonoma or later. It’s tested on Apple Silicon. Intel builds are
published, but they haven’t been tested on an Intel Mac yet. Linux is a preview: since 0.5.1 there are .deb
and .rpm packages and tarballs for x86_64 and arm64, and setup needs systemd 258 or later (such as Ubuntu 26.04
or Fedora 43). See Linux (preview). There are no
Windows builds yet.
PORTING.md collects what each OS needs.
What’s the license?#
lokal is licensed under the Apache License, Version 2.0. Unless you explicitly state otherwise, any contribution you intentionally submit for inclusion in lokal, as defined in the Apache-2.0 license, is licensed the same way, without any additional terms or conditions.