Troubleshooting
Common problems on vmuxMac with cause and fix for each.
| Problem | Cause | Fix |
|---|
| First launch shows "vmuxMac cannot be opened because Apple cannot check it for malicious software." | Direct download (not App Store) hit Gatekeeper. | Right-click the app icon, choose Open, confirm in the dialog. macOS remembers the choice. App Store builds never see this. |
| Launch shows "vmuxMac is damaged and cannot be opened." | Quarantine attribute on a download that did not finish properly. | Re-download. If the issue persists, run xattr -cr /Applications/vmuxMac.app and try again. |
| App opens, then immediately quits. | Corrupted preferences file. | Quit vmuxMac, run defaults delete app.vmux.mac, relaunch. You will lose UI preferences but not saved hosts. |
Bundle is missing from /Applications. | Mac App Store finished installing but Launchpad has not refreshed. | Open the App Store, find vmuxMac under Purchases, click Open. |
| App is allowed to run but cannot reach the network. | Sandbox prompt for outgoing connections was dismissed without approving. | Open System Settings → Privacy & Security → Network and enable vmuxMac. Restart the app. |
| Problem | Cause | Fix |
|---|
ssh user@host returns "Connection refused" | The remote sshd is not running, or a firewall is blocking the port. | Confirm sshd is up: ssh -v user@host to see the handshake. Try a different port with -p. |
ssh user@host times out without a response. | Network reachability or DNS. | Ping the host, resolve it with dscacheutil -q host -a name HOST. If the network is bad, prefer Mosh. |
| SSH connects, then prompts for a password every time. | Public-key authentication is not in use; key path or permissions wrong. | Verify your key is loaded: ssh-add -l. Check permissions: chmod 600 ~/.ssh/id_*. Add IdentityFile to ~/.ssh/config. |
| Public-key auth fails with "Permission denied (publickey)." | Server's authorized_keys does not include the public key, or wrong key for this host. | Confirm the matching public key is in ~/.ssh/authorized_keys on the server. Check IdentitiesOnly yes and IdentityFile in your local ~/.ssh/config. |
mosh user@host prints "mosh-server: command not found." | mosh-server is not installed on the remote host. | Install on the server: apt install mosh, dnf install mosh, brew install mosh. |
| Managed vmux session shows "Host key changed" warning. | Server's host key is different from the pinned fingerprint. | Investigate before proceeding — this can mean a server reinstall or a man-in-the-middle. If you trust it, remove the saved fingerprint from the host's profile and reconnect. |
| Managed session disconnects after every network change. | Plain SSH does not roam across networks. | Use Mosh instead: mosh user@host or set Mosh as the protocol on the saved host. |
SSH_AUTH_SOCK is set to vmuxAgent's socket but signing fails. | vmuxAgent is not running, or the iPhone is not reachable. | Open vmuxAgent in the menu bar, confirm the socket path, and confirm the iPhone is awake and unlocked. See vmuxAgent troubleshooting. |
| Problem | Cause | Fix |
|---|
| Prompt symbols render as boxes or replacement characters. | Selected font is not a Nerd Font. | Install a Nerd Font (Font Book, double-click .ttf/.otf). Switch to it in Settings → Appearance → Font or via font in vsh. |
| A newly-installed font does not appear in the picker. | Font discovery cache is stale. | Run font-rescan in vsh. Or restart vmuxMac. |
| Theme imported from VSCode looks washed out. | The VSCode theme does not include all 16 ANSI colors; missing slots fall back to defaults. | Pick a theme that defines terminal.ansi* colors, or edit the .json to add them, then re-import. |
| Theme switch does not apply to an already-open window. | The terminal is currently rendered by libghostty, which is reading its own config. | Close and reopen the window, or change the same theme in your Ghostty config and run Import Ghostty Config. |
| Font size keyboard shortcuts do not work. | Focus is on a non-terminal control (palette, settings window). | Click into the terminal first, then press Cmd++, Cmd+-, or Cmd+0. |
| Imported Ghostty config did not apply the font. | The font name in your Ghostty config is not bundled with vmuxMac and is not installed as a Nerd Font. | Install the font on macOS, then re-run Import Ghostty Config. |
| Problem | Cause | Fix |
|---|
| Cmd+Shift+R does nothing visible. | The CRT pipeline is paused on macOS while the terminal uses libghostty. | Expected. The toggle is stored for parity. See CRT effects. |
| CRT looks different on Mac than on Vision Pro. | CRT is currently disabled on Mac, so any visible difference is the lack of effects. | Use vmux on visionOS for the spatial CRT effect today. |
| Problem | Cause | Fix |
|---|
| Cmd+N opens a tab instead of a window (or vice versa). | macOS preference Prefer tabs when opening documents is set to always. | Change it in System Settings → Desktop & Dock. Set it to never for strict windows, always for tabs. |
| Window title shows "vmux" instead of the running command. | The shell or remote tool is not setting the terminal title (no \033]0;...\007 sequence). | Add a title-setting step to your shell prompt (zsh: precmd { print -Pn "\e]0;%~\a" }). |
| Title bar will not hide. | The setting is off, or another window manager (Yabai, Amethyst) is overriding it. | Toggle Hidden Title Bar in Settings → Mac. If a tiler is interfering, exclude vmuxMac from its rules. |
| Window restored to a tiny size after a display change. | A previously-saved frame referenced a display that is no longer attached. | vmuxMac re-centers the window and clamps it to a reasonable size. Resize manually; the new frame is saved. |
| Focus follows mouse selects the wrong window when clicking apps in the dock. | Race between dock click and pointer movement. | Disable Focus Follows Mouse in Settings → Mac if you find it interferes with your workflow. |
| Problem | Cause | Fix |
|---|
| A setting in General or Appearance appears greyed out. | The Mac terminal currently uses libghostty; many settings are stored but their visible effect is paused. | This is intentional. Use the Mac tab and the Ghostty config import for active controls today. |
| Settings reset on every launch. | Preferences file is not writable, or sandbox is denying writes. | Check ~/Library/Preferences/app.vmux.mac.plist exists and is owned by your user. Reinstall vmuxMac if not. |
defaults read app.vmux.mac shows no keys. | Settings have not been changed since launch (defaults are not written until first change). | Toggle any setting in the Settings window. Re-run the command. |
| Imported Ghostty settings did not stick. | Settings save is debounced; quit happened before the write. | Wait a moment after the import message, then quit. Or use Cmd+, to open Settings, which forces a flush. |
| Problem | Cause | Fix |
|---|
| Terminal feels sluggish on a very large window. | High pixel count plus heavy output (yes, fast tail). | Reduce window size. Lower font size to reduce cell count if helpful. |
| Bell sound plays repeatedly during heavy output. | Remote tool is emitting the bell character on every line. | Set your shell's bell-style to none, or filter the bell from the remote tool's output. |
If you want to file a bug report, attach the diagnostic export:
- Open the command palette.
- Run Export Diagnostics.
- The clipboard now holds an anonymized JSON report — no hostnames, usernames, or passwords are included.
- Paste it into your support email or issue.
The report contains macOS version, vmuxMac version, current settings (with sensitive fields redacted), the last few non-secret events, and the names (not contents) of any imported themes or fonts. Review it before sending if you are concerned.
- Settings — confirm a setting's expected behavior before assuming it is broken.
- Connecting — SSH and Mosh details if a connection issue is the symptom.
- vmuxAgent troubleshooting — when the issue is iPhone-backed signing.