Configuration
gmux works out of the box with no configuration. Everything is customizable through three config files in ~/.config/gmux/:
| File | Purpose | Reference |
|---|---|---|
host.toml | Daemon behavior: port, Tailscale remote access, devcontainer discovery | host.toml → |
settings.jsonc | Terminal options, keybinds, UI preferences | settings.jsonc → |
theme.jsonc | Terminal color palette (Windows Terminal theme compatible) | theme.jsonc → |
All files are optional. Create or edit them manually. The only exception is gmux remote, which can add [tailscale] to host.toml with your confirmation.
Settings and theme changes take effect on browser refresh (no daemon restart needed). Host config changes require restarting gmuxd.
Runtime state
Section titled “Runtime state”Not everything lives in config files. gmux keeps daemon-owned state in ~/.local/state/gmux/:
- Peers are added at runtime via Settings → Hosts → Connect to host and stored in the daemon’s SQLite database (
state.db) — they are not configured inhost.toml. - Projects are managed via Settings → Projects and stored in
state.db. - The host auth token lives in
auth-token(seedable withGMUXD_TOKEN);gmux authprints it along with a login/pairing URL.
See Multi-machine and File paths for details.
More reference
Section titled “More reference”- File paths — config files, sockets, runtime state, logs
- CLI commands —
gmuxandgmuxdusage - Environment variables — variables that affect gmux and variables set inside sessions
- Using the UI: Projects — project matching and peer-project setup