Linux machines ​

OrbStack can run full Linux machines with a variety of distros. Similar to the Windows Subsystem for Linux (WSL), these are highly-integrated lightweight machines that work almost exactly like traditional 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:

apt install nginx
systemctl start nginx

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 available 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 ​

Common Mac commands are aliased by default, so you can run them from Linux:

# open foo.txt in the default Mac text editor
open foo.txt
# copy `ps` output to Mac clipboard
ps | pbcopy

# open foo.txt in the default Mac text editor
open foo.txt
# copy `ps` output to Mac clipboard
ps | pbcopy

You can prefix any command with mac:

mac uname -a

mac uname -a

See Commands for more information.

macOS executables ​

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

# Compile a C program for macOS
mac gcc -o foo foo.c
# Run it ("mac" prefix not needed)
./foo

# Compile a C program for macOS
mac gcc -o foo foo.c
# Run it ("mac" prefix not needed)
./foo

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

Copy files between machines ​

You can access files from other Linux machines at /mnt/machines:

ls /mnt/machines/foo

ls /mnt/machines/foo

SSH ​

Keys & agent ​

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

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, 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:

orb create ubuntu new-ubuntu
# An older version
orb create ubuntu:jammy new-ubuntu
# Intel machine on Apple Silicon
orb create --arch amd64 ubuntu new-ubuntu

orb create ubuntu new-ubuntu
# An older version
orb create ubuntu:jammy new-ubuntu
# Intel machine on Apple Silicon
orb create --arch amd64 ubuntu 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:

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

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

Cloud-init ​

For more advanced setup, you can use Cloud-init with the same user data format as AWS EC2 and other cloud providers, or other tools like Ansible with the built-in SSH server.

Intel (x86) emulation ​

x86 machines ​

On Apple Silicon, OrbStack uses Rosetta to run Linux machines with Intel (x86_64/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:

orb create --arch amd64 ubuntu new-ubuntu

orb create --arch amd64 ubuntu new-ubuntu

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.

Emulating other CPU architectures ​

OrbStack can run 32-bit ARM (armhf), 64-bit ARM (aarch64), 32-bit Intel (i386), and 64-bit Intel (amd64) programs on both Apple Silicon and Intel Macs, as long as you have the appropriate libraries installed (or the program is statically linked).

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:

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

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

# Enable multi-arch
sudo dpkg --add-architecture amd64
# Fix repos
echo 'deb [arch=arm64] http://ports.ubuntu.com/ubuntu-ports lunar main restricted universe multiverse
deb [arch=arm64] http://ports.ubuntu.com/ubuntu-ports lunar-updates main restricted universe multiverse
deb [arch=arm64] http://ports.ubuntu.com/ubuntu-ports lunar-security main restricted universe multiverse
deb [arch=amd64] http://archive.ubuntu.com/ubuntu lunar main restricted universe multiverse
deb [arch=amd64] http://archive.ubuntu.com/ubuntu lunar-updates main restricted universe multiverse
deb [arch=amd64] http://archive.ubuntu.com/ubuntu lunar-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.

Debugging with GDB/LLDB ​

gdb and lldb can't attach directly to emulated x86 processes, but you can run x86 programs under QEMU with the debug server enabled, and connect to the debug server using gdb/lldb. For example:

sudo apt install qemu-user-static
qemu-x86_64-static -g 1234 ./hello

# in another terminal
gdb ./hello
target remote :1234
continue

sudo apt install qemu-user-static
qemu-x86_64-static -g 1234 ./hello

# in another terminal
gdb ./hello
target remote :1234
continue

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.

User accounts ​

Root access ​

Machines are created with passwordless sudo configured for your user.

You can log in as root directly using orb -u root, or orb -m ubuntu2 -u root to choose a specific machine. This allows you to set a root password and use su, for example.

To disable passwordless sudo, edit /etc/sudoers.d/orbstack.

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:

orb sudo passwd $USER

orb sudo passwd $USER

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

orb create --set-password ubuntu new-ubuntu

orb create --set-password ubuntu new-ubuntu

Additional users ​

Use the standard adduser or useradd commands to create additional users. You can log in as them directly using orb -u $USER.

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:

# Link commands
mac link adb
mac link fastboot

# Then run them as usual
adb devices
fastboot devices

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

Environment variables ​

By default, OrbStack forwards a limited set of environment variables to avoid causing issues. To forward more, set ORBENV to a colon-separated list of variables to forward:

# forward EDITOR and AWS_ACCESS_KEY_ID for one command
ORBENV=EDITOR:AWS_ACCESS_KEY_ID orb terraform apply
# or for all proceeding commands
export ORBENV=EDITOR:AWS_ACCESS_KEY_ID

# forward EDITOR and AWS_ACCESS_KEY_ID for one command
ORBENV=EDITOR:AWS_ACCESS_KEY_ID orb terraform apply
# or for all proceeding commands
export ORBENV=EDITOR:AWS_ACCESS_KEY_ID

For compatibility with scripts written for WSL, WSLENV is also supported.

Boot logs ​

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

orb logs ubuntu

orb logs ubuntu

Nested virtualization ​

It's not currently possible to support nested KVM virtualization on Apple Silicon. We're waiting for Apple to support it on the macOS side.

Kernel headers ​

Headers for the Linux kernel are available at /sys/kernel/kheaders.tar.xz.

Please note that building custom kernel modules is possible, but not officially supported. You will have to rebuild modules for nearly every OrbStack update.