Docker containers ​

OrbStack includes a Docker engine to run containers. Features including networking, port forwarding, bind mounts, and volumes work seamlessly.

Commands ​

OrbStack includes the latest command-line tools, including Compose and buildx. These tools will be installed automatically if you don't already have working tools, and are kept up to date with each OrbStack update.

If you already have CLI tools but want to use the OrbStack versions instead, uninstall/delete your existing tools and restart the app.

Compose ​

Since OrbStack includes a Docker engine and Compose tools, it's fully compatible with Docker Compose. You can run Compose projects with the docker compose command as usual, while benefiting from automatic domain names and other OrbStack features.

Network ​

OrbStack has 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. Port forwards, host networking, and other features are supported.

See Networking for more details.

Volumes & mounts ​

You can use bind mounts to access Mac files from containers, and volumes for persistent storage. Volumes are easily accessible from Mac for debugging and inspection. See Volumes & mounts for more details.

Intel (x86) emulation ​

On Apple Silicon, OrbStack uses Rosetta to run images built for Intel CPUs (x86_64/amd64 architecture) seamlessly with good performance. You can use multi-arch to build and run x86 and ARM images side-by-side by passing the --platform flag:

# Run an x86 container
docker run -it --rm --platform linux/amd64 alpine
# Run an arm64 container
docker run -it --rm --platform linux/arm64 alpine

# Build for x86
docker build --platform linux/amd64 .
# Build for arm64
docker build --platform linux/arm64 .

# Run an x86 container
docker run -it --rm --platform linux/amd64 alpine
# Run an arm64 container
docker run -it --rm --platform linux/arm64 alpine

# Build for x86
docker build --platform linux/amd64 .
# Build for arm64
docker build --platform linux/arm64 .

On macOS 12 and older, Rosetta is not available and a slower fallback is used instead. We recommend upgrading to macOS 13 for over 2x faster emulation (more for some workloads).

You can also set an environment variable to use x86 images by default: export DOCKER_DEFAULT_PLATFORM=linux/amd64

Image builds ​

See Container images.

Graphical manager ​

The OrbStack app includes a GUI for managing containers and volumes. It has near feature parity with Docker Desktop, but with a much simpler interface.

It's a native Swift app, so it feels right at home on macOS.

Resource usage ​

OrbStack uses very little CPU in the background, measured at around 0.1% on M1. That's lower than the background CPU usage of many typical macOS apps! It's slightly higher when containers are running, but still low.

To minimize CPU usage, stop any containers you're not using. See Efficiency for more information.

Docker context & socket ​

OrbStack creates a Docker context called orbstack. This context is automatically used when you run commands from the terminal.

If you have admin access, OrbStack will also create a symlink at /var/run/docker.sock to improve compatibility with some third-party tools.

SSH agent forwarding ​

To use SSH keys in containers (e.g. Git), you can forward your SSH agent from Mac to the container:

docker run -it --rm \
    -v /run/host-services/ssh-auth.sock:/agent.sock \
    -e SSH_AUTH_SOCK=/agent.sock \
    alpine

docker run -it --rm \
    -v /run/host-services/ssh-auth.sock:/agent.sock \
    -e SSH_AUTH_SOCK=/agent.sock \
    alpine

You can also use -v $SSH_AUTH_SOCK:/agent.sock in most cases, but this will not work if you're using 1Password's agent.

Third-party tools ​

Since OrbStack provides a highly-compatible environment similar to Docker Desktop, it should be compatible with all third-party tools, such as Dev Containers.

If you run into any trouble with third-party tools, please open an issue and we'll do our best to help.

Emulating other CPU architectures ​

OrbStack can run 32-bit ARM (linux/arm), 64-bit ARM (linux/arm64), 32-bit Intel (linux/386), and 64-bit Intel (linux/amd64) images on both Apple Silicon and Intel Macs.

Graphical apps ​

By default, OrbStack doesn't provide an X server or Wayland compositor for running graphical apps. You can run XQuartz yourself and set the DISPLAY environment variable to connect to it over the network at host.docker.internal.

Engine config ​

To add registry mirrors, insecure registries, and more, you can edit the config (daemon.json) by running orb config docker.

You can also edit the config directly at ~/.orbstack/config/docker.json and restart the engine with orb restart docker.

{
    "hosts": ["tcp://0.0.0.0:2375", "unix:///var/run/docker.sock"],
    "tls": false
}

{
    "hosts": ["tcp://0.0.0.0:2375", "unix:///var/run/docker.sock"],
    "tls": false
}

Engine logs ​

To view the engine logs, run orb logs docker.

Credential store ​

OrbStack uses the open-source macOS keychain credential store (osxkeychain) to store registry credentials securely.

Docker Desktop uses a different credential store (desktop), so you may need to log in again after switching to OrbStack. If you use them side-by-side, you may need to fix the store in ~/.docker/config.json.

To log in to private registries, such as GitHub Packages container registry (ghcr.io):

docker login ghcr.io

docker login ghcr.io

Run docker-credential-osxkeychain list to view saved credentials, and erase to delete them.