During Public Preview you can use the Team plan for free, and get an early-adopter discount at GA. Sign in
Machine Configuration
Locally runs entirely on your machine, and to do that it needs your machine to resolve Locally's DNS names (*.locally) and to trust the certificate Locally serves them with - both on your machine itself, and inside Docker or Podman if you use either. This page covers each of those, why they're needed, and how to undo them.
What you need to set up
Each resource gets its own hostname, as it would in Azure, so lookups for .locally (and only .locally) are sent to Locally.
- Elevated
- Yes -
sudo, or an Administrator terminal on Windows - Undo
locally configure dns --remove
Azure is HTTPS-only and the Azure SDKs check certificates, so your machine needs to trust the certificate Locally serves - or you can use your organisation's own CA.
- Elevated
- Yes on macOS and Linux - you run the command yourself
- Undo
- Remove it from your trust store
On macOS and Windows these run in a VM with its own resolver and trust store, so the services which run in containers need the same setup in there.
- Elevated
- No
- Undo
locally configure podman --remove/docker --remove
Good to know
Locally never edits your hosts file, your shell profile or your PATH, and doesn't install any background services - nothing of Locally's runs unless you've run locally build. It also leaves your existing Azure CLI setup alone - Locally keeps itself separate, so your logins, subscriptions and settings stay exactly as they were. If you're looking for what a machine needs before installing Locally, see Requirements.
1Resolving *.locally on your machine
Each Data Plane Emulator in Locally has its own hostname, in the same way it would in Azure - for example a Storage Account is available at <account>.blob.core.storage.locally and a Key Vault at <vault>.vault.locally. These are served by Locally's DNS server, which only answers for resources that exist, so a typo or a deleted resource fails the same way it would against Azure.
Your machine doesn't know about the .locally domain by default, so locally configure dns adds a rule which sends lookups for .locally (and only .locally) to Locally's DNS server - every other lookup keeps going to your usual DNS server, untouched. Locally's DNS server listens on port 5673 rather than 53, so it doesn't need elevated rights to run, and doesn't conflict with any other resolver on your machine.
locally setup doesn't make this change itself, but shows you the command to run:
$
locally configure dns
What this changes depends on your platform:
macOS
Writes /etc/resolver/locally (creating /etc/resolver if needed), which macOS uses to route lookups for a single domain to a specific nameserver. This is the same as running:
sudo mkdir -p /etc/resolver
sudo tee /etc/resolver/locally <<'EOF'
nameserver 127.0.0.1
port 5673
EOF
Locally runs the sudo commands itself, so you'll be prompted for your password in the terminal.
Linux
Where systemd-resolved is running, Locally writes a drop-in at /etc/systemd/resolved.conf.d/locally.conf and restarts systemd-resolved. Domains=~locally makes this a routing domain, meaning only .locally lookups are sent to Locally. This is the same as running:
sudo mkdir -p /etc/systemd/resolved.conf.d
sudo tee /etc/systemd/resolved.conf.d/locally.conf <<'EOF'
[Resolve]
DNS=127.0.0.1:5673
Domains=~locally
EOF
sudo systemctl restart systemd-resolved
Where dnsmasq is used instead, Locally writes /etc/dnsmasq.d/locally.conf and restarts dnsmasq, the same as running:
sudo tee /etc/dnsmasq.d/locally.conf <<'EOF'
server=/locally/127.0.0.1#5673
EOF
sudo systemctl restart dnsmasq
In both cases Locally runs the sudo commands itself, and you'll be prompted for your password. If neither systemd-resolved nor dnsmasq is in use, Locally doesn't change anything, and prints the details you'll need to configure your resolver by hand.
Windows
Adds a Name Resolution Policy Table (NRPT) rule for the .locally namespace pointing at 127.0.0.1, with the comment Managed by Locally, and then clears the DNS client cache. This is the same as running:
Add-DnsClientNrptRule -Namespace '.locally' -NameServers '127.0.0.1' -Comment 'Managed by Locally'
Clear-DnsClientCache
This needs to be run from an elevated (Administrator) terminal - Locally won't elevate itself, and will stop if it isn't.
Since an NRPT rule can only point at an IP address, rather than an address and a port, on Windows Locally's DNS server also listens on 127.0.0.1:53 whilst Locally's running. If another resolver is already using port 53, Locally still starts, but *.locally won't resolve until that port is free.
Checking and removing it
--status shows whether the rule is in place (and if Locally's running, whether control-plane.locally actually resolves), --dry-run prints what would change without changing it, and --remove removes exactly what locally configure dns added and nothing else:
$
locally configure dns --status
$
locally configure dns --remove
Note that on Windows --remove only removes rules carrying the Managed by Locally comment, so if you added the rule by hand you'll need to remove it by hand too. Some VPN clients also rewrite the resolver configuration whilst they're connected - Networking & Proxies covers what to do if that happens.
2Trusting the local Certificate Authority
Azure is only available over HTTPS, and the Azure SDKs (and most of the tools built on them) expect a valid certificate - as such, rather than asking you to disable certificate validation in your tools (which is then easy to forget to turn back on), Locally serves everything over HTTPS using a certificate signed by a Certificate Authority that's created on your machine - or, if you'd rather, one issued by your organisation's own CA.
How the certificates are created
locally setup creates the certificates (and locally certificate generate recreates them). If mkcert is on your PATH Locally uses it, and reuses mkcert's existing root - which, if you've already trusted it, means there's nothing more to do. Otherwise Locally generates them itself:
- A root CA named Locally CLI - Local Certificate Authority (RSA 4096, valid for 5 years).
- A TLS certificate signed by it (RSA 4096, valid for 2 years) covering
localhost,127.0.0.1,*.locallyand a wildcard for each service's domain (e.g.*.vault.locallyand*.blob.core.storage.locally), along with Locally's own hostnames such ascontrol-plane.locallyby name - since some clients won't accept a wildcard directly beneath a single-label domain like.locally.
Importantly, the CA's private key is discarded as soon as the TLS certificate has been signed - it's never written to disk. This means that even someone with access to your config directory can't use Locally's CA to issue a certificate for some other domain, which is the main risk of trusting a local root. The trade-off is that the CA can't sign anything else either, so regenerating the certificates creates a brand new CA, which then needs trusting again (see Renewing below).
Both certificates and the TLS key are written to the config directory as local-ca.pem, localhost.pem and localhost.key, readable only by you.
Adding it to your trust store
Adding a root certificate to your operating system's trust store is a security-sensitive change, so Locally doesn't do it for you - instead, the last screen of locally setup shows the command for your platform, and you run it yourself:
| Platform | Store | Command |
|---|---|---|
| macOS | System keychain (sudo) | sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain ~/.config/locally/local-ca.pem |
| Debian / Ubuntu | System CA store (sudo) | sudo cp ~/.config/locally/local-ca.pem /usr/local/share/ca-certificates/locally-ca.crt && sudo update-ca-certificates |
| Fedora / RHEL | System CA store (sudo) | sudo cp ~/.config/locally/local-ca.pem /etc/pki/ca-trust/source/anchors/locally-ca.crt && sudo update-ca-trust |
| Linux browsers | Your NSS database (Chrome, Chromium and Firefox) | certutil -d sql:$HOME/.pki/nssdb -A -t "C,," -n "Locally Local CA" -i ~/.config/locally/local-ca.pem |
| Windows | Your user's Trusted Root store | Import-Certificate -FilePath "$env:LocalAppData\locally\local-ca.pem" -CertStoreLocation cert:\CurrentUser\Root |
If Locally used mkcert, running mkcert -install instead covers both the system store and the NSS databases.
Some runtimes don't use the operating system's trust store at all - Java, Node.js and Python's requests being the common ones. Rather than asking you to configure each of these, locally run hands them the CA directly (see below), so these work when they're run through locally run regardless of what's in your trust store.
You can skip trusting the CA - locally validate reports it as a warning rather than a failure - but your browser will show a certificate warning for the Locally Dashboard and every emulator's UI, and anything you run outside of locally run will fail to connect.
Using your organisation's CA
If you're in a corporate environment you may not want (or be allowed) to trust a new root certificate, in which case you can use a certificate issued by your organisation's internal CA instead. Any CA works, as long as two things are true: the certificate it issues covers every name Locally needs, and the CA is already trusted by your machine - which, for a managed machine, it usually will be.
You can get the list of names to request from your CA by running:
$
locally certificate get-required-domains
This includes wildcards such as *.vault.locally and *.blob.core.storage.locally, since each resource gets its own hostname - so it's worth checking up front that your CA will issue wildcard certificates for an internal domain like .locally, since some are configured not to.
Once you've got the certificate, its private key and your CA's certificate as PEM files, choose to reuse existing certificates during locally setup and point it at those three files. Locally then uses them in the same way as its own - including handing your CA to tools run through locally run and to the containers it starts. locally validate checks the certificate covers the names Locally needs and hasn't expired, and since Locally doesn't renew a certificate it didn't issue, you'll need to request a new one from your CA before it expires (and again if a new version of Locally needs additional names).
Renewing
The TLS certificate isn't renewed automatically. locally validate warns once it's within 30 days of expiring and fails once it's expired, and re-running locally setup (or locally certificate generate) creates a new one. A new version of Locally can also need additional *.locally names on the certificate (v2026.11 adds *.azconfig.locally for App Configuration), which locally validate and locally build will tell you about. locally certificate generate --update-config creates a certificate that covers them and points Locally at it.
Since regenerating creates a new CA (unless you're using mkcert), you'll need to trust the new CA wherever you trusted the old one - your OS trust store, NSS, and if you use them, the Podman machine and Azure Storage Explorer (re-running locally configure podman and locally configure azure-storage-explorer handles those two). It's also worth removing the old CA from your trust store at the same time.
Note
3Inside Docker and Podman
Some services in Locally run in containers - Web Apps, Function Apps, Container Apps, Container Instances, Virtual Machines and the database servers - and the code inside them needs to reach Locally in the same way your machine does. That's not as simple as it sounds, since inside a container 127.0.0.1 is the container rather than your machine - and on macOS and Windows, Docker and Podman run inside a virtual machine which has its own resolver and its own trust store, neither of which know about the changes above.
If you don't use any of the services that run in containers, you don't need a container runtime at all, and none of this applies.
Containers that Locally starts
Every container Locally starts is given the local CA, mounted read-only at /etc/ssl/certs/locally-ca.pem, with SSL_CERT_FILE, REQUESTS_CA_BUNDLE, NODE_EXTRA_CA_CERTS and CURL_CA_BUNDLE pointing at it - so that, for example, a Function App calling a Key Vault over the Azure SDK works without any changes to its code. These containers are labelled as Locally's, and are removed when Locally stops (and if Locally crashed, the next locally build cleans up any which were left behind).
The images they're built from are pulled the first time they're needed and aren't removed by Locally, in the same way as any other image you've pulled.
Docker or Podman on Linux
Nothing to do - the container runtime runs directly on your machine and uses its resolver, so the rule from locally configure dns already applies.
Podman machine on macOS
locally configure podman makes the following changes inside the default Podman machine (over podman machine ssh), so that the VM can resolve *.locally and trusts the local CA - which is what's needed to push images to and pull images from the Container Registry Emulator:
- Switches NetworkManager to dnsmasq (
/etc/NetworkManager/conf.d/00-locally.conf), then adds/etc/NetworkManager/dnsmasq.d/locally.conf, which forwards.locallylookups to Locally's DNS server on your machine and rewrites answers of127.0.0.1to your machine's address as seen from the VM. - Adds the local CA as
/etc/pki/ca-trust/source/anchors/locally-ca.pemand runsupdate-ca-trust. If the CA's changed since, re-running the command replaces it.
These use sudo inside the VM, so nothing on your machine needs elevated rights. Containers resolve names through Podman's own networking rather than the VM's resolver, so whilst Locally's running it also starts the same DNS forwarder used for Docker Desktop (below) for the containers it launches.
Podman machine on Windows
On Windows, the Podman machine runs under WSL2 and uses the NRPT rule from locally configure dns for DNS, so locally configure podman only adds the local CA to the VM's trust store, as above.
If the VM can't reach Locally's Container Registry Emulator, on Windows 11 (22H2 and later) Locally can switch WSL to mirrored networking by adding networkingMode=mirrored under [wsl2] in %UserProfile%\.wslconfig, with a comment marking it as added by Locally. It won't change a value you've set yourself. This only takes effect once WSL restarts - which shuts down every WSL distribution, not just Podman's - so Locally asks before doing so, unless you pass --restart-wsl.
Docker Desktop on macOS and Windows
Docker Desktop doesn't offer a supported way to change its VM, so rather than modifying it, Locally works around it. Whilst Locally's running it starts a small DNS forwarder container (locally-dns-forwarder-5673, built locally from Alpine and dnsmasq), which forwards .locally lookups to Locally's DNS server and rewrites 127.0.0.1 to the address the VM reaches your machine on. Each container Locally starts is then pointed at the forwarder using --dns.
Containers you start yourself, and Docker Desktop itself, are left alone - which is also why pushing to the Container Registry Emulator from Docker Desktop isn't supported at this time, since that's the Docker daemon resolving the hostname and checking the certificate, rather than a container. Networking & Proxies covers how containers reach Locally in more detail.
The forwarder container is removed when Locally stops. Its image (localhost/locally/dns-forwarder) is kept so the next launch is quicker - locally configure docker builds it ahead of time, and locally configure docker --remove removes it.
Checking and removing it
As with DNS, locally configure podman and locally configure docker support --status, --dry-run and --remove. When Locally's running, locally validate also starts a throwaway container which looks up control-plane.locally, to confirm resolution works the way a workload would see it.
$
locally configure podman --status
What locally run sets
locally run is how your tools are pointed at Locally (see Automatic Configuration), and it doesn't change anything on your machine - it sets environment variables for the command it's running, and only that command. Nothing is written to your shell profile, so a terminal that isn't running through locally run is still pointed at Azure.
The variables fall into a few groups:
- Trust:
SSL_CERT_FILEandREQUESTS_CA_BUNDLEpoint at a bundle of the standard public roots plus the local CA (so public HTTPS keeps working),NODE_EXTRA_CA_CERTSat the local CA, andJAVA_TOOL_OPTIONSgains a trust store containing it (added to any value you've already set). - Endpoints: the Resource Manager, Microsoft Graph and authority endpoints, set using the variables the Azure CLI, the Azure SDKs, Terraform, Bicep and PowerShell each read, along with turning off instance discovery so nothing calls
login.microsoftonline.com. - Identity: the Tenant, Subscription and credentials for the identity being used - either a Client ID and Secret, or a per-run managed identity endpoint when running as a user or managed identity.
- Terraform:
TF_VAR_environment_is_locally,TF_VAR_locationand the Subscription variables listed in Automatic Configuration. - Telemetry: the Azure CLI's and PowerShell's own telemetry are turned off for commands run through Locally.
You can see the full list for your setup by running:
$
locally run env
So that commands run through locally run az don't share a login with your normal Azure CLI sessions, Locally keeps a separate Azure CLI setup for each identity, and leaves your own Azure CLI setup untouched.
The config directory
Everything else Locally keeps lives in a single directory - ~/.config/locally on macOS and Linux (readable only by you), and %LocalAppData%\locally on Windows (hidden by default). The main things in there are:
| Path | What it is |
|---|---|
config.json | Your settings - certificate paths, Tenant and Subscription IDs and feature flags |
local-ca.pem, localhost.pem, localhost.key | The local CA, and the TLS certificate and key it signed |
locally-installation-cert.crt, locally-installation-key.pem | The Installation Certificate from your Locally Account, and its key |
plugins/ | Installed plugins |
teams/ | Runbooks, policies and directory objects synced from your team |
snapshots/ | Your snapshots, including the state locally build --persist saves |
persist-keys/ | The keys each saved state signs tokens with, so tokens stay valid across a restart |
crashreports/, analytics.json | Crash reports and analytics waiting to be sent, only if you've opted in - see Security & Telemetry |
Locally also creates other temporary files and directories in here as it needs them, which come and go between versions - so it's best not to edit or rely on anything that isn't listed above.
Unless you start Locally with --persist, nothing you provision is kept here - it's held in memory and is gone when Locally stops (see State Persistence). Blob and file share contents are the exception whilst Locally's running, and are written to a temporary directory (locally-storage-*) which is removed on shutdown.
Optional changes
A couple of commands make changes to other tools' configuration, but only when you run them:
locally mcp install <client>adds Locally's MCP Server to that client's configuration file (e.g.~/.cursor/mcp.json), andlocally mcp uninstall <client>removes it.locally configure azure-storage-explorercopies the local CA into Azure Storage Explorer's settings and adds Locally as a custom provider, and--removeremoves both.
Checking everything
locally validate checks the certificate (and the names it covers, and when it expires), the DNS rule, your container runtime and your sign-in, and prints the fix for anything it finds. locally build also checks the certificate, DNS and your container runtime before it starts, and tells you if something needs fixing.
$
locally validate
When you're done with Locally, Updating & Uninstalling walks through undoing each of these in order.
Should you encounter any issues, please take a look at the troubleshooting section, reach out in our Discord or open an issue and we'll take a look.
During Public Preview you can use the Team plan for free, and get an early-adopter discount at GA. Sign in