Skip to content

Container networking

OrbStack uses a custom-built virtual network stack designed to be seamless. It implements all common networking features, including IPv6, ping, and traceroute, and follows your VPN and DNS settings. The network is optimized for speed, with up to 45 Gbps of throughput between macOS and containers.

Port forwarding, host networking, and other features are supported.

Domain names

Containers in OrbStack have domain names at container-name.orb.local with zero configuration or port numbers required. This makes it easy to access services, especially for large projects, where port forwards can quickly get messy and difficult to remember.

See Container domain names for more details.

Port forwarding

You can use the -p flag to forward ports from the container to Mac. For example, to forward port 80 from a container to Mac:

bash
docker run --rm -p 80:80 nginx
docker run --rm -p 80:80 nginx

The server will be available on localhost, just like Linux.

Connecting to servers on Mac

You can use the host.docker.internal domain to connect to a server running on Mac. For example, to connect to a MySQL server on Mac:

bash
docker run --rm mysql mysql -h host.docker.internal -u root
docker run --rm mysql mysql -h host.docker.internal -u root

Host networking

OrbStack supports host networking, allowing you to run containers with --net=host and avoid having to deal with port forwarding. In this mode, any servers you run in the container will be accessible from Mac on localhost, and vice versa.

For example, to run a web server in a container:

bash
docker run --rm --net=host nginx
docker run --rm --net=host nginx

The server will be available on localhost.

localhost also works in the other direction, so you can connect directly to servers running on macOS instead of using host.docker.internal.

See Host networking for more details.

Direct container access

You can also connect to containers by IP, directly from Mac! Simply copy the container IP from the OrbStack app. For example:

bash
curl 192.168.215.2
curl 192.168.215.2

This can be a useful alternative to port forwarding — for example, if you don't know which ports you'll be using in advance, or if you don't want to clutter your Mac's ports.

VPN compatibility

OrbStack's network stack is fully compatible with VPNs, including advanced DNS resolver settings. This means that you can use VPNs with OrbStack without any additional setup.

Container IP ranges

To minimize conflicts, OrbStack uses IP addresses in the 192.168.x.x range for containers. If that conflicts with other subnets on your device, you can change it in Settings for both the default bridge network (bip) and Compose networks (default-address-pools). For example:

json
{
    "bip": "198.19.192.1/23",
    "default-address-pools": [
        {"base": "198.19.192.0/19", "size": 23},
        {"base": "198.19.224.0/20", "size": 23}
    ]
}
{
    "bip": "198.19.192.1/23",
    "default-address-pools": [
        {"base": "198.19.192.0/19", "size": 23},
        {"base": "198.19.224.0/20", "size": 23}
    ]
}

Reliability

OrbStack's custom network stack has been designed with an emphasis on reliability. Care has been taken to ensure that it remains stable in many cases, including opening and closing connections rapidly and concurrently.

Proxies

All containers will automatically follow your macOS proxy settings. This is done transparently, removing the need to set HTTP_PROXY and HTTPS_PROXY manually.

HTTP, HTTPS, and SOCKS proxies are supported. SOCKS proxies are preferred over HTTP and HTTPS proxies for all traffic, if configured.

You can also configure OrbStack to use a different proxy from the rest of your system, e.g. for security testing:

bash
# HTTP
orb config set network_proxy http://example.com
# HTTPS with password on port 8443
orb config set network_proxy https://user:password@example.com:8443
# SOCKS with password on port 1081
orb config set network_proxy socks5://user:password@example.com:1081

# reset to system proxy
orb config set network_proxy auto
# disable proxy
orb config set network_proxy none
# HTTP
orb config set network_proxy http://example.com
# HTTPS with password on port 8443
orb config set network_proxy https://user:password@example.com:8443
# SOCKS with password on port 1081
orb config set network_proxy socks5://user:password@example.com:1081

# reset to system proxy
orb config set network_proxy auto
# disable proxy
orb config set network_proxy none

Proxy exclusions configured in macOS settings will also be respected.

Self-signed certificates

OrbStack uses the macOS keychain, so certificates marked as trusted for SSL will work for container registries and other connections.

Keep in mind that you may also have to install certificates in containers, as each container image has its own set of trusted CA certificates.

Registry certificates

Instead of installing certificates in the macOS keychain, you can also use ~/.docker/certs.d to trust certificates for specific registry domains:

~/.docker/certs.d/internal.registry.example/ca.crt = CA certificate
~/.docker/certs.d/internal.registry.example/ca.crt = CA certificate

And for client TLS authentication:

~/.docker/certs.d/internal.registry.example/client.cert = Client certificate
~/.docker/certs.d/internal.registry.example/client.key = Client private key
~/.docker/certs.d/internal.registry.example/client.cert = Client certificate
~/.docker/certs.d/internal.registry.example/client.key = Client private key

IPv6

For containers, IPv6 is disabled by default for compatibility. To use IPv6, turn on "Enable IPv6" in the app settings or set "ipv6": true in the engine config.