---
title: "Reach a Mac localhost service from a Docker container · Kilobat Guides"
url: "https://kilobat.app/guides/localhost-from-container"
description: "Inside a container, localhost is the container. Use host.docker.internal to reach a database, API or model server that runs on your Mac."
---

Developers

# A container cannot reach localhost on the Mac

Each container has its own network stack. In a container, `localhost` is the container itself, not the Mac.

Applies to: Docker Desktop and OrbStack on current macOS versions. · Checked: 29 October 2026

## Symptoms

- An app in a container gets “connection refused” on `localhost:5432` or a similar port.
- The same URL works in Safari or Terminal on the Mac.
- A model server or API on the Mac is not reachable from a dev container.

## Likely causes

- **localhost points to the container.** The container looks for the service in its own network stack, where nothing listens.
- **The host address changes.** Docker's documentation says that the host IP address changes. It gives a special name for the host instead.
- **A firewall on the Mac.** The macOS firewall or another firewall app can block incoming connections to the service.

## How to check

1. Make sure that the service works on the Mac. Replace 8000 with your port.

   ```
   curl http://localhost:8000
   ```
2. See which address the Mac service listens on.

   ```
   lsof -nP -iTCP:8000 -sTCP:LISTEN
   ```

   Output `*:8000` means all addresses. `127.0.0.1:8000` means the loopback address only.
3. Test the host name from inside the container, if the image includes wget.

   ```
   docker exec my-container wget -qO- http://host.docker.internal:8000
   ```

## How to fix it

1. In the container, use `host.docker.internal` instead of `localhost`. Docker Desktop and OrbStack both support this name.
2. Set the address in the app's configuration, for example in an environment variable.

   ```
   docker run -e API_URL=http://host.docker.internal:8000 my-image
   ```
3. With OrbStack, you can use host networking instead. Then Mac services are on `localhost` in the container.

   ```
   docker run --net host my-image
   ```
4. If the connection still fails, look at the macOS firewall settings. See [The macOS firewall blocks incoming connections](https://kilobat.app/guides/macos-firewall-incoming).

## With Kilobat

1. Kilobat's checks run on the Mac, not in the container. Add `--context container` to get a command to run in the container.

   ```
   kilobat why http://localhost:8000 --context container
   ```
2. If a hosted service calls your Mac, use `--context provider`. Kilobat then says that localhost is private and out of its reach.

   ```
   kilobat why http://localhost:8000 --context provider
   ```

## Questions

**Does host.docker.internal work on Linux too?**

This page covers the Mac. On Docker Desktop for Mac and OrbStack, the name resolves to the host.

**Why does Safari reach the service when the container cannot?**

Safari runs on the Mac, so localhost is the Mac. The container has its own localhost.

## Sources

- [Docker Docs: Explore networking how-tos on Docker Desktop](https://docs.docker.com/desktop/features/networking/networking-how-tos/)
- [OrbStack Docs: Container networking](https://docs.orbstack.dev/docker/network)
- [OrbStack Docs: Host networking](https://docs.orbstack.dev/docker/host-networking)
- lsof(8), man page installed with macOS 27.2

Sources checked on 29 October 2026. Man pages are the ones installed with macOS; open one with `man <name>` in Terminal.

## Related guides

- [Cannot reach a Docker container from the Mac](https://kilobat.app/guides/docker-container-from-mac): Docker on a Mac runs containers in a Linux virtual machine.
- [The macOS firewall blocks incoming connections](https://kilobat.app/guides/macos-firewall-incoming): The macOS firewall controls connections that other computers start to your Mac.
- [Find why one site or API won't connect](https://kilobat.app/guides/recipes/why-cant-it-connect): When the internet works but one address fails, Kilobat checks each layer in turn.
- [Port already in use on a Mac](https://kilobat.app/guides/port-already-in-use): Only one process can listen on a TCP port and address.