Skip to main content

Bind Published Container Ports to a Specific Interface

· 2 min read
Erik Osterman
Erik Osterman
Founder @ Cloud Posse

Publishing a container port usually exposes it on every network interface of the host. For a local database, an admin portal, or a cloud emulator, that means anything on the same network can reach a service that was only ever meant for your own machine. Container port mappings in Atmos now accept an IP:port string in host, so you can keep a published port on loopback, or on any single interface you choose.

The Problem​

A port mapping such as host: 3000 / container: 3000 asks the container runtime to listen on 0.0.0.0:3000. On a laptop connected to shared Wi-Fi, or on a CI runner, that service becomes reachable from other machines. Restricting it meant dropping down to raw docker run -p 127.0.0.1:3000:3000 invocations outside of Atmos.

The Fix​

The existing host field now accepts either a port number or an IP:port string. For example, host: "127.0.0.1:3000" publishes port 3000 only on loopback. Numeric values retain the runtime's default binding, so existing configuration is unchanged.

How to Use It​

Set host to an address and port in any entry under run.ports:

components:
  container:
    portal:
      image: my-portal:local
      run:
        ports:
          - host: "127.0.0.1:3000"
            container: 3000
  • IPv6 addresses require brackets: host: "[::1]:3000". Use an IP literal, not a hostname.
  • Omitting host or setting it to 0 lets the runtime assign a free host port. Use host: "127.0.0.1:0" to restrict that automatic assignment to loopback.
  • The same field works in container workflow steps, background container services, and emulators.

Binding to loopback narrows where the runtime listens, but it isn't a firewall. Docker Engine versions before 28.0.0 can expose localhost-published ports to hosts on the same network segment, and some network configurations allow direct routing to container ports. See Docker's port publishing documentation for details.

Port bindings are fixed when a container is created. After you change one, recreate just that container:

atmos container down portal -s <stack>
atmos container up portal -s <stack>

Get Involved​

Questions or ideas for container components? Join us in the Cloud Posse community or open an issue on GitHub.