OrbStack Docs

Appearance

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.

© 2024 Orbital Labs, LLC