Networking & Proxies

Networking & Proxies

Locally is a set of services listening on your machine, reached through *.locally hostnames that its own DNS server answers. This page is the complete port map, which listeners are reachable from beyond the loopback interface, how containers find their way back to Locally, and what to do when a proxy, VPN or corporate resolver sits in the way.

Port map

Locally uses 5660-5680 plus 5671 and 5883. Every listener binds 127.0.0.1 unless the Bind column says otherwise.

Plugins (one process per installed Resource Provider) are handed their listener by Locally - an inherited socket on macOS and Linux, a loopback port Locally allocates at launch on Windows - so they never need a port of their own in the map. Mode both means locally build and locally ci. The external endpoints Locally calls are listed in Security & Telemetry.

What is reachable from other machines

Two listeners bind every interface, and both are there so that containers - which reach the host through a gateway address, not loopback - can use them: the DNS server on 5673, and the managed-identity endpoint above. Neither hands out anything without a credential: DNS answers only for names that exist, and the identity endpoint refuses requests without the secret Locally injects into the app it belongs to. Everything else, including the control plane and every data plane, is loopback-only; there is no flag to expose them, and a teammate cannot point their tools at your Locally. A firewall that blocks inbound 5673/udp and 5673/tcp from the LAN costs you nothing unless you run containers in a VM (see below).

How containers reach Locally

Inside a container, 127.0.0.1 is the container, and a *.locally name has to resolve to the host instead. How that happens depends on where the container runtime lives:

• Linux, Docker or Podman on the host - the daemon shares your machine's resolver, so the .locally rule from locally configure dns already applies. Nothing to do.
• Podman machine (macOS, Windows) - the daemon runs in a VM with its own resolver. locally configure podman writes a rule into that VM forwarding the whole .locally domain to Locally's DNS server on the host and rewriting loopback answers to the VM's host address, and installs the local CA in the VM's trust store so the daemon can push to and pull from the registry emulator.
• Docker Desktop (macOS, Windows) - its VM offers no supported way in, so locally build starts a small DNS forwarder container on Docker's network once the DNS server is up, and every container Locally launches is pointed at it with --dns. Your own containers and the daemon itself are untouched, which is why docker push to the registry emulator stays a Podman-only capability today.

Every container Locally launches is also given the local CA, so Azure SDK calls from inside a Web App or Function App to Storage, Key Vault or the control plane verify without changes. In the other direction, the container gateway on port 5669 is how you reach a container: each container group and VM endpoint is published under a <name>.gondola.locally hostname, which is what az container show hands back as an address that actually responds.

HTTP proxies

If your shell exports HTTPS_PROXY or HTTP_PROXY, the Azure CLI, Terraform and the SDKs will send Locally traffic to that proxy, which cannot reach 127.0.0.1 on your machine and doesn't trust Locally's CA. locally run passes your proxy variables through untouched, so exclude Locally explicitly:

$ export NO_PROXY="${NO_PROXY:+$NO_PROXY,}.locally,localhost,127.0.0.1"

Set no_proxy as well if a tool only reads the lower-case form (curl and some Python versions). Locally's own outbound calls - certificate renewal, sign-in, updates - honour the same proxy variables, so a proxy that is required for internet access is fine as long as *.locally.build is allowed through it.

VPNs and corporate DNS

locally configure dns adds a resolver rule for the .locally domain only (an /etc/resolver/locally file on macOS, a systemd-resolved drop-in on Linux, an NRPT rule on Windows); every other lookup keeps going to your normal DNS. Some VPN clients rewrite the resolver configuration when they connect and put it back when they disconnect, which can drop the rule while the tunnel is up. If *.locally stops resolving after connecting:

$ locally configure dns --status

reports whether the rule is still present, and re-running locally configure dns restores it without touching anything else. A resolver that answers NXDOMAIN for a Storage Account you just created is usually Locally telling the truth - see DNS Server on why only resources that exist resolve.

Port conflicts

Locally cannot share its ports with another process. When a launch fails with a bind error naming one of the addresses above, find the holder (lsof -i :5680 on macOS and Linux, netstat -ano | findstr 5680 on Windows); the usual culprits are a second Locally instance or a service a crashed launch didn't get to stop. On Windows, port 53 is shared with any other local resolver; Locally treats it as best-effort and still starts on 5673 when it can't bind 53, but the NRPT rule then has nowhere to send queries until the other resolver is stopped.