Introduction⌗

Ever since I started using OrbStack, there’s no going back. OrbStack automatically registers container domain names into the host’s mDNS, solving a few tricky issues for beginners:

  • Different HOST values when accessing the same database container from the host machine and from inside another container
  • The need to map the database container’s ports to the host machine

For example, in my local development environment, I run MySQL and Redis containers and assign them the following domain names:

  • mysql.database.local
  • redis.database.local

Once the corresponding containers start in OrbStack, it automatically registers them with macOS’s mDNS, allowing access to containers via these domain names.

OrbStack Network Architecture⌗

OrbStack uses a custom networking stack to manage communication between containers and the host. By default:

  • Internal container IP (e.g., 10.0.8.33): This is the private IP assigned to the container within OrbStack’s virtual network (typically a bridged network like bridge101). It usually belongs to a subnet like 10.0.0.0/8, visible only within OrbStack’s internal network, and used for container-to-container or VM communication.

  • External access IP (e.g., 198.19.248.8): OrbStack assigns each container an externally accessible IP, usually in the 198.19.248.0/23 range. This is provided by OrbStack’s network proxy layer (running on the macOS host), routing external traffic (e.g., access via container-name.orb.local) to the container.

In other words, 10.0.8.33 is the container’s internal network address, while 198.19.248.8 is the external proxy address provided by OrbStack’s network layer.

Once a container is running, you can check the mDNS record using:

dns-sd -Q mysql.database.local
DATE: ---Tue 11 Mar 2025---
13:51:43.488  ...STARTING...
Timestamp     A/R  Flags         IF  Name                          Type   Class  Rdata
13:51:43.623  Add  2             26  mysql.database.local.         Addr   IN     198.19.248.8

The Cause⌗

Everything seemed fine—until our project used the Swoole PHP extension. In the Swoole project, I couldn’t connect to the database container using mysql.database.local as mentioned above.

I got the following error:

php bin/hyperf.php migrate --path migrations/tenant

In Connection.php line 1169:
                                                                                                    
  SQLSTATE[HY000] [2002] DNS Lookup resolve failed (SQL: select `enterprise_id` from `enterprise`)  
                                                                                                    

In Connector.php line 107:
                                                    
  SQLSTATE[HY000] [2002] DNS Lookup resolve failed

Initially, I didn’t think much of it, assuming it was some network compatibility issue with OrbStack. But later, another colleague—on macOS with the same configuration—could access the OrbStack-defined domain names in their Swoole project just fine.

Troubleshooting⌗

I started a process of elimination, comparing environment differences between my machine and my colleague’s. It turned out the only difference was that I had enabled the c-ares library. From its name alone, you wouldn’t guess its DNS relevance—but after some research, I found that c-ares is an asynchronous DNS resolution library, useful for applications needing non-blocking DNS queries or parallel lookups.

Swoole doesn’t enable it by default; you have to compile Swoole with the --enable-cares flag to use it.

The problem? This library does not support querying mDNS records.

Solutions⌗

  • Recompile the Swoole extension without enabling c-ares
  • Assign a fixed IP to the container and manually add a mapping in /etc/hosts

I hope this helps—Happy hacking!