OrbStack Docs

Appearance

Linux 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 Linux.

Domain names ​

Machines in OrbStack have domain names at machine-name.orb.local with zero configuration required. See Container domain names for more details.

Running servers ​

Any servers that you run in Linux machines are accessible from Mac. For example, if you run a web server on port 8000 in Linux, you can access it from Mac on localhost:8000:

bash
python3 -m http.server 8000
python3 -m http.server 8000

If your server listens on 0.0.0.0 or ::, it will also be accessible from other devices on your network.

Connecting to Mac servers ​

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

bash
mysql -h host.orb.internal -u root
mysql -h host.orb.internal -u root

Connecting to localhost

To avoid surprising behavior, connecting directly from machines to localhost macOS servers is not supported. (It is, however, supported for Docker host networking.) Please open an issue if you want this to be supported in machines.

Connecting between machines ​

All Linux machines are connected to the same network bridge, so you can connect between machines using their IP addresses. Run ip addr to find the IP address of a machine:

2: eth0@if6: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc noqueue state UP group default qlen 1000
    link/ether 46:51:ff:fb:a0:2f brd ff:ff:ff:ff:ff:ff link-netnsid 0
    inet 198.19.249.204/24 metric 1024 brd 198.19.249.255 scope global dynamic eth0 
       valid_lft 170414sec preferred_lft 170414sec
    inet6 fd07:b51a:cc66:0:4451:ffff:fefb:a02f/64 scope global mngtmpaddr noprefixroute
       valid_lft forever preferred_lft forever
    inet6 fe80::4451:ffff:fefb:a02f/64 scope link
       valid_lft forever preferred_lft forever
2: eth0@if6: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc noqueue state UP group default qlen 1000
    link/ether 46:51:ff:fb:a0:2f brd ff:ff:ff:ff:ff:ff link-netnsid 0
    inet 198.19.249.204/24 metric 1024 brd 198.19.249.255 scope global dynamic eth0 
       valid_lft 170414sec preferred_lft 170414sec
    inet6 fd07:b51a:cc66:0:4451:ffff:fefb:a02f/64 scope global mngtmpaddr noprefixroute
       valid_lft forever preferred_lft forever
    inet6 fe80::4451:ffff:fefb:a02f/64 scope link
       valid_lft forever preferred_lft forever

This example machine has an IPv4 address of 198.19.249.204 and an IPv6 address of fd07:b51a:cc66:0:4451:ffff:fefb:a02f on its primary network interface, eth0. Both addresses can be used to connect between machines.

Connectivity between machines is very fast (up to 115 Gbps on M1).

Connecting from Mac to machines ​

You can also use a Linux machine's IP address to connect to the machine from Mac. For example, to connect to a server running on the machine above:

bash
curl 198.19.249.204
curl 198.19.249.204

Connecting to Docker containers ​

If you've started containers from Mac, you can also connect to their forwarded ports from Linux machines using docker.orb.internal:

bash
# On macOS
docker run --rm -p 80:80 nginx
# On Linux
curl docker.orb.internal
# On macOS
docker run --rm -p 80:80 nginx
# On Linux
curl docker.orb.internal

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.

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 machines will automatically follow your macOS proxy settings. This is done transparently, removing the need to set HTTP_PROXY or HTTPS_PROXY manually.

HTTP, HTTPS, and SOCKS proxies are supported. If a SOCKS proxy is configured, it will be used for all traffic. Otherwise, HTTP and HTTPS proxies will be used for HTTP and HTTPS traffic, respectively.

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 in machines.

© 2024 Orbital Labs, LLC