---
title: "cmux — macOS Ghostty Wrapper; Two Separate Configs"
aliases: [cmux-config, ghostty-cmux, cmux-ghostty]
tags: [macos, terminal, ghostty, cmux, config]
sources:
  - "daily/2026-05-08.md"
created: 2026-05-08
updated: 2026-05-08
---

# cmux — macOS Ghostty Wrapper; Two Separate Configs

cmux is a macOS GUI workspace/multiplexer application that delegates actual terminal rendering to Ghostty. Configuring cmux appearance requires editing **two separate config files** — one for Ghostty (font/colors/terminal behaviour) and one for cmux itself (workspaces/panes/UI layout).

## Config File Split

| What | File | Controls |
|---|---|---|
| Terminal rendering (font, colors, cursor, keybinds) | `~/.config/ghostty/config` | Ghostty settings |
| Workspaces, panes, window layout, UI chrome | `~/.config/cmux/cmux.json` (or `~/Library/Application Support/cmux/`) | cmux settings |

A common mistake: editing `cmux.json` to change font size and seeing no effect because font is a Ghostty concern, not cmux's.

## Example Ghostty Config

```
# ~/.config/ghostty/config
font-family = "JetBrains Mono"
font-size = 14
theme = "Catppuccin Mocha"
cursor-style = block
window-padding-x = 8
window-padding-y = 8
```

## macOS Quarantine After Download

cmux installed via zip download from the web may be blocked by macOS Gatekeeper:

```bash
# Symptom: "cmux is damaged and can't be opened"
# Fix: remove quarantine attribute
xattr -cr /Applications/cmux.app

# Or for files in a specific path
xattr -cr ~/Downloads/cmux.app
# Then move to /Applications/
```

## Related Concepts

- [[wiki/concepts/fish-shell-path-config]] — Fish shell and PATH configuration for terminal tools
- [[wiki/concepts/remote-server-dotfiles-bootstrap]] — Full-stack remote dotfiles bootstrap including terminal config

## Sources

- [[daily/2026-05-08.md]] — Discovered while setting up cmux as a terminal workspace manager; had to separately configure Ghostty for font/colors and cmux.json for workspace layout; also encountered macOS quarantine block on first launch
