Skip to content
On this page

Linux machines

OrbStack can run full Linux machines with a variety of distros. Similar to WSL, these machines are lightweight and can be used like standard virtual machines.

Services

You can run services in Linux machines using your distro's init system. For example, to run a web server on Ubuntu:

bash
apt install nginx
systemctl start nginx

Depending on your distro, the init system may be systemd, OpenRC, or runit. You can configure services to start on boot as usual.

Servers are available at localhost. See Networking for more information.

File transfer

Mac files are avaialable in Linux machines at /mnt/mac, and Linux files are available from Mac at ~/OrbStack or the OrbStack tab in Finder. See File sharing for more information.

File transfer commands are also available.

Run Mac commands from Linux

From Linux, you can use Mac commands by prefixing them with mac. For example, to open a file in the default Mac text editor:

bash
mac open ~/foo.txt

See Commands for more information.

macOS executables

Similar to WSL, you can also run macOS executables (Mach-O) directly from Linux using binfmt, which can be useful for development. For example:

bash
mac gcc -o foo foo.c
# prefix not needed
./foo

This allows you to add macOS binaries to your Linux PATH. For example, you can add /opt/homebrew/bin to run Homebrew commands directly from Linux.

Share files across machines

You can access files from other Linux machines at /mnt/machines. For example, to access machine foo:

bash
ls /mnt/machines/foo

SSH keys

Your preferred SSH agent on macOS is automatically forwarded to Linux machines, so you can push to Git and connect to SSH servers without any additional setup.

SSH server

OrbStack has a built-in SSH server that multiplexes access to all Linux machines, so there is no need to install an SSH server in each machine.

Resource usage

Idle Linux machines use nearly no additional CPU compared to OrbStack's baseline (around 0.1% on M1), so you can run dozens of machines without breaking a sweat.

See Efficiency for more information.

Machine creation

Creating machines with any supported distro is easy and quick (less than 1 minute on fast connections). You can use the GUI or automate creation using the command line:

bash
orb create ubuntu new-ubuntu
# Or specify a version other than latest
orb create ubuntu:jammy new-ubuntu

See Distros for more details.

Automatic setup

To set up new machines automatically, use the command line to create a machine and run a setup script. For example, to create a new Ubuntu machine and run the setup.sh script:

bash
orb create ubuntu new-ubuntu && orb -m new-ubuntu ./setup.sh

You can also use tools like Ansible with the built-in SSH server. For cloud-init support (like AWS EC2), vote on the feature request.

Intel (x86) machines

On Apple Silicon, OrbStack uses Rosetta to run Linux machines with Intel (x86/amd64) binaries. This is much faster than emulation with QEMU or UTM, seamlessly providing near-native performance.

To create an Intel machine, use the --arch flag:

bash
orb create --arch amd64 ubuntu new-ubuntu

Running Intel (x86) programs

There are two ways to run programs built for Intel (x86) CPUs on Apple Silicon:

  1. Create an Intel machine (see above) and run the program in it.
  2. Install multi-arch support in an ARM machine.

If you see rosetta error: failed to open elf at /lib64/ld-linux-x86_64.so, it means you're missing multi-arch support. Choose one of the two options above to fix it.

Multi-architecture

Some Linux distros support multi-arch, which allows you to run both x86 and ARM programs in the same machine by installing the libraries needed to run x86 programs. For example, on Ubuntu:

bash
# Enable multi-arch
sudo dpkg --add-architecture amd64
# Fix repos
echo 'deb [arch=arm64] http://ports.ubuntu.com/ubuntu-ports kinetic main restricted universe multiverse
deb [arch=arm64] http://ports.ubuntu.com/ubuntu-ports kinetic-updates main restricted universe multiverse
deb [arch=arm64] http://ports.ubuntu.com/ubuntu-ports kinetic-security main restricted universe multiverse
deb [arch=amd64] http://archive.ubuntu.com/ubuntu kinetic main restricted universe multiverse
deb [arch=amd64] http://archive.ubuntu.com/ubuntu kinetic-updates main restricted universe multiverse
deb [arch=amd64] http://archive.ubuntu.com/ubuntu kinetic-security main restricted universe multiverse' | sudo tee /etc/apt/sources.list

# Install libraries
sudo apt update
sudo apt install libc6:amd64

Instructions vary by distro, and not all distros (e.g. Arch) support multi-arch. Search for the appropriate commands for your distro.

Graphical apps

OrbStack does not currently support running graphical Linux apps by default, but you can set up XQuartz and use it as an X11 server in Linux. Xrdp is another option.

USB devices

Support for USB device passthrough is planned.

In the meantime, consider using command linking to run the Mac versions of USB tools from Linux. For example, Android developers can use adb and fastboot this way:

bash
# Link commands
mac link adb
mac link fastboot

# Then run them as usual
adb devices
fastboot devices

This works seamlessly in most cases and allows you to run commands as if they were installed on Linux, including working with files on either Linux or Mac.

Nested virtualization

Nested KVM virtualization is not currently supported, but we plan to look into the feasibility of adding it.

User password

By default, OrbStack creates a user with the same name as your macOS user, with no password set. sudo is configured to run commands as root without asking for a password.

To set a password:

bash
orb sudo passwd $USER

You can also set a default password when creating a machine:

bash
orb create --set-password ubuntu new-ubuntu

Boot logs

To view a machine's boot logs and console output, use the orb logs command:

bash
orb logs ubuntu