How to use AeroSpace: install, configure and manage tiled windows

Check whether AeroSpace fits your workflow

AeroSpace is aimed at keyboard-centric users, developers and advanced users who are comfortable editing a text configuration file. It is also a good match for people with multi-monitor setups who want i3-style monitor handling, and for anyone who already knows i3 or another tiling window manager.

It is a poor fit if you want a graphical settings panel, since the project says it will never provide a GUI for configuration. It also does not acknowledge native macOS Spaces, so it is not suited to users who depend on them.

• Good fit: keyboard-first workflows, text-based config, i3-style multi-monitor handling.
• Poor fit: anyone wanting a GUI settings panel or who relies on native macOS Spaces.
• Not a priority: window borders, transparency and animations, which the project deliberately does not prioritize.

Install AeroSpace with Homebrew

The preferred way to install AeroSpace is with Homebrew, because it includes autoupdates. Run the following command in Terminal.

If your Mac uses more than one monitor, make sure the monitors are properly arranged before you start, as the project recommends. The guide linked from the project has further installation options.

Understand the tiling model and workspaces

AeroSpace is a tiling window manager based on a tree paradigm, so windows are arranged into layouts that fill the screen without overlapping. You move focus between windows with the keyboard rather than the mouse.

AeroSpace does not use macOS Spaces. Instead it emulates its own virtual workspaces, which the project says allows fast workspace switching without animations and without disabling SIP (System Integrity Protection).

• Tiled layouts fill the screen without overlapping windows.
• Workspaces are AeroSpace's own emulation, not macOS Spaces.
• Switching workspaces is fast and does not require disabling SIP.

Configure AeroSpace with a plain text file

AeroSpace's configuration is a plain text file, which makes it friendly to dotfiles workflows. The project provides a default-config.toml in its guide that you can use as a reference for your own settings.

Because there is no graphical settings panel, changes are made by editing the file in a text editor. The project's stated reasoning is that this is easier for advanced users than navigating checkboxes.

• Start from the default-config.toml shown in the AeroSpace Guide.
• Keep your configuration in version control if you manage dotfiles.
• Use the official docs for available settings rather than guessing key names.

Control AeroSpace from the command line

AeroSpace is CLI first. It ships with manpages and shell completion, so you can look up commands in the terminal. The full list of commands is documented in the AeroSpace Commands page.

The project also supports shell-like combinators such as ||, && and ; along with an eval command to send multiple commands in one go, according to its README roadmap notes.

• Manpages are included for reference from the terminal.
• Shell completion is included.
• The official Commands page lists every command and flag.

Know the project status before relying on it

The README describes AeroSpace as a Public Beta. The project says it can be used as a daily driver, but breaking changes are expected until version 1.0 is reached. Breaking changes to configuration files, CLI or behaviour are made with careful consideration and helpful messages.

Known open items include stability issues where windows may randomly jump to the focused workspace, and a planned large refactoring intended to address them.

• Expect breaking changes until 1.0.
• Questions and bug reports go to GitHub Discussions first, since the project does not accept Issues directly.
• Notarization is not used; the Homebrew install script removes the com.apple.quarantine attribute so the app runs without the usual warning.