Architecture ​

OrbStack uses a lightweight Linux virtual machine with a shared kernel to minimize overhead and save resources, similar to WSL 2 (Windows Subsystem for Linux). This flexible architecture comes with many advantages such as high efficiency, low resource usage, seamless integration with macOS, and more.

Services built from scratch ​

Vertical integration plays a key role in OrbStack's advantages and seamless integration. All important services have been purpose-built from scratch to work with each other, tailored to the specific needs of OrbStack and its virtual environment, instead of using off-the-shelf programs. Low-level Linux tuning and optimizations are also included to make everything work efficiently.

Services are written in a mix of Swift, Go, Rust, and C.

Docker ​

An embedded Docker engine alongside Linux machines in the OrbStack VM. This allows you to run Docker containers and Linux machines at the same time with low resource usage. It also enables powerful features, such as connecting between Docker and Linux machines.

The Docker engine is made available to macOS for a seamless experience.

This design is similar to Docker Desktop, but with a few key differences:

• The overall architecture of the services and how they communicate is similar, but OrbStack's services are more specialized.
• Docker Desktop is split into many components, resulting in more complexity and communication overhead. OrbStack has a monolithic design that can bring significant advantages in this context.

Linux machines ​

OrbStack runs full-blown Linux machines that work almost exactly like traditional virtual machines, all while sharing the same kernel. Init systems including systemd, OpenRC, and runit are fully functional, allowing you to run services as usual. 15 distros are available and support for custom distros is planned.

Strictly speaking, OrbStack machines are not independent VMs, but they're virtually indistinguishable for most intents and purposes — just with better integration. This is why we choose to call them "machines".

This architecture brings unparalleled efficiency and flexibility: machines can be created and destroyed in under a minute, and you can run dozens of machines simultaneously without breaking a sweat.

Network ​

Access to the outside network is provided by a custom virtual network stack with tuning around it for performance. NAT is used for IPv4 and IPv6, and a custom DNS server forwards DNS queries to macOS. This setup makes it possible to follow VPN and DNS settings.

Docker containers are connected to Docker's default bridge network. Host networking is also available.

Linux machines are also connected to a virtual network bridge, allowing them to communicate with each other. The Docker engine is connected to the same network, making Docker port forwards accessible from Linux machines.

Event-based port forwarding makes servers instantly available at localhost on macOS.

File sharing ​

OrbStack uses the latest VirtioFS technology with additional tuning to provide fast Docker bind mounts and access to files on Mac.

Files in Docker volumes and Linux machines are accessible through a mount at ~/OrbStack on macOS, which also appears in the Finder sidebar. Mounts are automatically created and destroyed as needed. Data is transferred through a special low-latency transport.

Security ​

Linux machines are considered trusted because OrbStack provides integration with macOS, but support for isolated machines (without integration) could be added in the future. You can run containers using systemd-nspawn or LXD to get an isolated environment.

Internal OrbStack services are protected by a firewall to ensure that untrusted code running in Docker containers (and custom Docker/LXD instances if you choose to install them) cannot tamper with them.

On Apple Silicon, KASLR (Kernel Address Space Layout Randomization) protection is augmented by a security feature that doesn't incur the overhead of KPTI mitigations, speeding up system calls without degrading security.