---
title: "Aerospace Tiling Window Manager for macOS"
aliases: [aerospace, aerospace-wm, macos-tiling-wm]
tags: [dotfiles, macos, tiling-wm, aerospace, productivity, keybindings]
sources: [raw/Aerospace Is The Best Tiling Window Manager I've Tried On macOS.md]
created: 2026-05-08
updated: 2026-05-08
---

# Aerospace Tiling Window Manager for macOS

i3-inspired tiling WM for macOS. No SIP disable required (unlike Yabai). Currently in public beta — used daily by the creator and stable enough for daily driving.

## Key Takeaways

- **No SIP required** — unlike Yabai, Aerospace does not need System Integrity Protection disabled
- **i3-style modal keybindings** — main mode + custom modes (e.g. service mode), identical mental model to i3 on Linux
- **Reimplements spaces** — bypasses macOS built-in Spaces with its own workspace system for better control
- **Tree-based layout engine** — windows are leaf nodes; containers hold tiles or accordions in horizontal/vertical orientations
- **Window callbacks** — auto-route new windows to workspaces by app ID; move mouse on focus change
- **Mnemonic workspaces** — use letters (B=browser, T=terminal, M=music, N=notes) for instant recall

---

## Installation

```sh
brew install --cask nikitabobko/tap/aerospace
```

Config locations (pick one):
- `~/.aerospace.toml`
- `~/.config/aerospace/aerospace.toml`

```sh
mkdir -p ~/.config/aerospace
touch ~/.config/aerospace/aerospace.toml
```

Paste the [default config](https://nikitabobko.github.io/AeroSpace/guide#default-config) as a starting point.

### Recommended initial changes

```toml
# Start at login
start-at-login = true

# Gaps between windows and monitor edges
[gaps]
inner.horizontal = 10
inner.vertical   = 10
outer.left       = 10
outer.right      = 10
outer.top        = 10
outer.bottom     = 10
```

---

## Keybinding Modes

Aerospace uses **modes** (like i3). Default mode is `main`. Define additional modes with `[mode.<name>.binding]`.

```toml
# Enter service mode
alt-shift-semicolon = ['mode service']

[mode.service.binding]
esc = ['reload-config', 'mode main']   # reload + return to main
```

Reload config: `alt-shift-;` → `esc`

---

## Focus & Moving Windows

| Action | Default Keybind |
|--------|----------------|
| Focus left/down/up/right | `alt-h/j/k/l` |
| Move window left/down/up/right | `alt-shift-h/j/k/l` |

---

## Layouts

Aerospace uses a **tree** internally. Windows are always leaf nodes; containers define layout.

### Two layout types

| Layout | Toggle | Description |
|--------|--------|-------------|
| Tiles | `alt-/` | Side-by-side; toggle horizontal ↔ vertical |
| Accordion | `alt-,` | One window at a time with peeking padding |

### Joining windows into a sub-container

In service mode: `alt-shift-h/j/k/l` (join-with command) — groups two windows under a shared parent container, enabling nested layout control.

---

## Resizing

| Action | Keybind |
|--------|---------|
| Shrink window | `alt-shift--` |
| Grow window | `alt-shift-=` |

Resize direction is determined by the parent container's orientation (horizontal or vertical).

---

## Workspaces

- Numbered 1–9, lettered A–Z
- Switch: `alt-<number/letter>`
- Move focused node: `alt-shift-<number/letter>`

### Mnemonic workspace layout (recommended)

| Workspace | App |
|-----------|-----|
| `B` | Browser |
| `T` | Terminal |
| `M` | Music |
| `N` | Notes |
| `P` | Photo editing |
| `V` | Video editing |

Optionally combine move + switch in one binding:

```toml
alt-shift-1 = ['move-node-to-workspace 1', 'workspace 1']
```

---

## Callbacks

### Auto-route new windows to workspaces

```toml
[[on-window-detected]]
if.app-id = 'com.googlecode.iterm2'   # find IDs with: aerospace list-apps
run = 'move-node-to-workspace T'

[[on-window-detected]]
if.app-id = 'com.google.Chrome'
run = 'move-node-to-workspace B'
```

### Move mouse on focus change

```toml
on-focused-monitor-changed = ['move-mouse monitor-lazy-center']
on-focus-changed = ['move-mouse window-lazy-center']
```

---

## Floating & Fullscreen

- **Float/tile toggle:** service mode → `f`
- **Fullscreen** (custom keybind):

```toml
alt-shift-f = 'fullscreen'
```

Aerospace auto-floats windows it detects should float (e.g. System Preferences).

---

## Multiple Monitors

- `alt-shift-tab` — move current workspace to next monitor

---

## Mission Control Fix

Aerospace hides inactive workspace windows off-screen. Mission Control shows them tiny.

**Fix:** System Settings → Desktop & Dock → Mission Control → enable **"Group windows by application"**

---

## Related Articles

- [[wiki/dotfiles/wezterm-workspaces|WezTerm Workspaces]] — WezTerm's own workspace/session system
- [[wiki/dotfiles/wezterm-key-tables|WezTerm Key Tables]] — modal keybinding layers, similar concept to Aerospace modes
- [[wiki/dotfiles/linux-terminal-ricing|Linux Terminal Ricing]] — full ricing guide including window management
- [[wiki/dotfiles/fish-shell-intro|Fish Shell Intro]] — shell that pairs well with this WM setup

---

## Sources

- Raw: `raw/Aerospace Is The Best Tiling Window Manager I've Tried On macOS.md`
- Original video: Josean Martinez, YouTube, 2024-08-10
