cmuxcmux/docs

Configuration

cmux reads configuration from Ghostty config files, giving you familiar options if you're coming from Ghostty.

Config file locations

cmux looks for configuration in these locations (in order):

  1. ~/.config/ghostty/config
  2. ~/Library/Application Support/com.mitchellh.ghostty/config

Create the config file if it doesn't exist:

mkdir -p ~/.config/ghostty
touch ~/.config/ghostty/config

Appearance

Font

~/.config/ghostty/config
font-family = JetBrains Mono
font-size = 14

Colors

~/.config/ghostty/config
# Theme (or use individual colors below)
theme = Dracula

# Custom colors
background = #1e1e2e
foreground = #cdd6f4
cursor-color = #f5e0dc
cursor-text = #1e1e2e
selection-background = #585b70
selection-foreground = #cdd6f4

Split panes

~/.config/ghostty/config
# Opacity for unfocused splits (0.0 to 1.0)
unfocused-split-opacity = 0.7

# Fill color for unfocused splits
unfocused-split-fill = #1e1e2e

# Divider color between splits
split-divider-color = #45475a

Behavior

Scrollback

~/.config/ghostty/config
# Number of lines to keep in scrollback buffer
scrollback-limit = 10000

Working directory

~/.config/ghostty/config
# Default directory for new terminals
working-directory = ~/Projects

App settings

In-app settings are available via cmux > Settings (⌘,):

Theme mode

  • System: follow macOS appearance
  • Light: always light mode
  • Dark: always dark mode

Automation mode

Control socket access level:

  • Off: no socket control (most secure)
  • cmux processes only: only allow processes started inside cmux terminals to connect
  • allowAll: allow any local process to connect (CMUX_SOCKET_MODE=allowAll, env override only)
On shared machines, consider using "Off" or "cmux processes only" mode.

Browser link behavior

In Settings > Browser, cmux exposes two host lists with different purposes:

  • Hosts to Open in Embedded Browser: applies to links clicked from terminal output. Hosts in this list open in cmux; other hosts open in your default browser. Supports one host or wildcard per line (for example: example.com, *.internal.example).
  • HTTP Hosts Allowed in Embedded Browser: applies only to HTTP (non-HTTPS) URLs. Hosts in this list can open in cmux without a warning prompt. Defaults include localhost, 127.0.0.1, ::1, 0.0.0.0, and *.localtest.me.

Example config

~/.config/ghostty/config
# Font
font-family = SF Mono
font-size = 13

# Colors
theme = One Dark

# Scrollback
scrollback-limit = 50000

# Splits
unfocused-split-opacity = 0.85
split-divider-color = #3e4451

# Working directory
working-directory = ~/code