AeroSpace

Who It's For

AeroSpace is aimed at developers who want i3-style tiling on macOS without the friction of SIP configuration. If you've seen yabai setups and want the same keyboard-driven workflow but don't want to reboot into recoveryOS or re-run setup after every macOS update, AeroSpace is the practical alternative. It's also a natural fit for anyone already fluent in TOML-based config files and who prefers declaring their entire setup in one place.

How It Works

AeroSpace uses a tree-based layout model borrowed directly from i3. Every workspace is a tree of containers: leaf nodes are windows, and branch nodes are horizontal or vertical splits. When you tile windows, you're building this tree — split a container horizontally and two windows sit side by side; split vertically and they stack. You can nest splits arbitrarily deep.

The key architectural decision: AeroSpace does not use native macOS Spaces. Instead, it implements its own virtual workspace system — all windows live on a single native Space, and AeroSpace hides/shows them to simulate workspace switching. This is why no SIP disable is needed. The tradeoff is that Mission Control won't show your workspaces, and integrations that read native Space state (like some status bar tools) won't see AeroSpace's workspaces. In practice, most users find this a worthwhile trade for the setup simplicity.

Configuration

AeroSpace is configured via a single TOML file at ~/.config/aerospace/aerospace.toml. Keybindings, gaps, and layout behavior all live here — no companion daemon needed:

# ~/.config/aerospace/aerospace.toml

[gaps]
inner.horizontal = 8
inner.vertical   = 8
outer.left       = 8
outer.right      = 8
outer.top        = 8
outer.bottom     = 8

[mode.main.binding]
# Focus windows (vim-style)
alt-h = 'focus left'
alt-j = 'focus down'
alt-k = 'focus up'
alt-l = 'focus right'

# Move windows
alt-shift-h = 'move left'
alt-shift-j = 'move down'
alt-shift-k = 'move up'
alt-shift-l = 'move right'

# Switch workspaces
alt-1 = 'workspace 1'
alt-2 = 'workspace 2'
alt-3 = 'workspace 3'

# Send window to workspace
alt-shift-1 = 'move-node-to-workspace 1'
alt-shift-2 = 'move-node-to-workspace 2'
alt-shift-3 = 'move-node-to-workspace 3'

# Change split direction
alt-slash = 'layout tiles horizontal vertical'
alt-comma = 'layout accordion horizontal vertical'

AeroSpace also supports binding modes (like i3's resize mode) — define a secondary mode with its own key map and a key to enter/exit it.

Compared to Similar Tools

Compared to yabai, AeroSpace is significantly easier to set up: no SIP changes, no companion hotkey daemon, no scripting addition that breaks on macOS updates. The cost is that yabai integrates with native Spaces more deeply — you can create and destroy spaces programmatically, and tools like SketchyBar can read native space state. Users who script their window environment heavily may still prefer yabai; users who want a reliable daily driver overwhelmingly prefer AeroSpace.

Compared to Amethyst, AeroSpace offers a config file instead of GUI preferences, which makes it easier to version-control and share your setup. Amethyst uses xmonad-style dynamic layouts (cycle through predefined layout algorithms), while AeroSpace uses a persistent tree that you manipulate manually — a style difference that users either love or don't.

Requirements

• macOS 13 Ventura or later
• Accessibility permission required: System Settings → Privacy & Security → Accessibility
• No SIP changes required
• Apple Silicon and Intel both supported

Getting Started

AeroSpace ships with a default config that works out of the box. After install:

# Launch AeroSpace from /Applications or Spotlight
# Grant Accessibility permission when prompted

# Edit your config (creates file with defaults if absent)
mkdir -p ~/.config/aerospace
aerospace config  # opens config in $EDITOR, or edit directly

# Reload config after changes (no restart needed)
aerospace reload-config

Full documentation is at nikitabobko.github.io/AeroSpace.