Machine Configuration

Preview

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, *.locally and a wildcard for each service's domain (e.g. *.vault.locally and *.blob.core.storage.locally), along with Locally's own hostnames such as control-plane.locally by 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
macOSSystem keychain (sudo)sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain ~/.config/locally/local-ca.pem
Debian / UbuntuSystem CA store (sudo)sudo cp ~/.config/locally/local-ca.pem /usr/local/share/ca-certificates/locally-ca.crt && sudo update-ca-certificates
Fedora / RHELSystem CA store (sudo)sudo cp ~/.config/locally/local-ca.pem /etc/pki/ca-trust/source/anchors/locally-ca.crt && sudo update-ca-trust
Linux browsersYour 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
WindowsYour user's Trusted Root storeImport-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

This is a different certificate to your Installation Certificate, which is issued by your Locally Account when you sign in and identifies this installation and its plan. The local CA secures the endpoints on your machine and never leaves it.

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 .locally lookups to Locally's DNS server on your machine and rewrites answers of 127.0.0.1 to your machine's address as seen from the VM.
  • Adds the local CA as /etc/pki/ca-trust/source/anchors/locally-ca.pem and runs update-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_FILE and REQUESTS_CA_BUNDLE point at a bundle of the standard public roots plus the local CA (so public HTTPS keeps working), NODE_EXTRA_CA_CERTS at the local CA, and JAVA_TOOL_OPTIONS gains 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_location and 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.jsonYour settings - certificate paths, Tenant and Subscription IDs and feature flags
local-ca.pem, localhost.pem, localhost.keyThe local CA, and the TLS certificate and key it signed
locally-installation-cert.crt, locally-installation-key.pemThe 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.jsonCrash 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), and locally mcp uninstall <client> removes it.
  • locally configure azure-storage-explorer copies the local CA into Azure Storage Explorer's settings and adds Locally as a custom provider, and --remove removes 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.

Preview

During Public Preview you can use the Team plan for free, and get an early-adopter discount at GA. Sign in

A local cloud for you and your AI agents.

Your Azure infrastructure, running on your machine. Deploy in seconds, break things freely, and ship to Azure when you're ready.