Troubleshooting

Causes and fixes for vmuxAgent issues — disconnected menu, empty key list, agent refused operation, slow signing.

How to diagnose

Most vmuxAgent problems fall into one of three buckets:

Socket / shell — SSH_AUTH_SOCK isn't set, points at the wrong file, or the socket isn't there.
Pairing — the iPhone isn't reachable over Multipeer Connectivity, or notifications are blocked.
Signing — the pair is up but the iPhone denies, times out, or returns an error.

Start with the first bucket; each later bucket assumes the earlier one is healthy.

Bucket 1: socket and shell

Symptom: `ssh-add -l` says Could not open a connection to your authentication agent

The shell can't find the socket. Check:

echo $SSH_AUTH_SOCK

If empty, your shell didn't load the export. Check your shell startup file (~/.zshrc for zsh, ~/.bash_profile for bash) and confirm the export line is there. Open a new terminal — exports don't apply retroactively.

If set but pointing at the wrong path:

ls -l "$SSH_AUTH_SOCK"

You want a file with type s and mode srw-------. If it doesn't exist, vmuxAgent isn't running. Launch it from the Applications folder and check the menu bar.

Symptom: socket exists but `ssh-add -l` hangs forever

vmuxAgent is running but blocked on an internal operation. Quit vmuxAgent (menu -> Quit) and relaunch. If the socket file remains after quit, delete it manually:

rm ~/.ssh/vmux-agent.sock

Then relaunch.

Symptom: GUI apps (Tower, GitHub Desktop, VS Code) ignore the agent

Variables exported in ~/.zshrc aren't visible to GUI apps started from the Dock. Run:

launchctl setenv SSH_AUTH_SOCK "$HOME/.ssh/vmux-agent.sock"

This sets the variable on the user agent until reboot. Restart the GUI app afterward.

Bucket 2: pairing

vmuxAgent and RemoteSignerPhone aren't discovering each other.

Check	Fix
RemoteSignerPhone open and on home screen	Foreground the iPhone app; suspended apps don't advertise MPC.
iPhone Local Network permission	iOS Settings -> RemoteSignerPhone -> Local Network -> on.
Mac Local Network permission for vmuxAgent	macOS Settings -> Privacy & Security -> Local Network -> vmuxAgent on.
Same Wi-Fi network or BLE in range	Toggle Wi-Fi off and on, ensure Bluetooth is on, retry.
VPN active on Mac	Some VPNs block multicast. Disconnect VPN; pair; reconnect VPN.
iCloud account match	Helps with discovery but not required. Sign both devices into the same Apple ID for fastest pair.

If discovery still fails, restart both apps. If that fails, restart the iPhone — iOS occasionally wedges its MPC daemon and a reboot is the only recovery.

Symptom: paired briefly, drops within a minute

This is almost always the iPhone going to sleep or backgrounding. It's working as designed: the next sign request triggers an APNs wake push and re-pair. To verify:

Lock the iPhone.
Run ssh user@host on the Mac.
Within 1–3 seconds, your iPhone should buzz with a notification.
Tap it; RemoteSignerPhone opens; the agent reconnects; Face ID prompt appears.

If no notification arrives, see the next item.

Symptom: APNs wake pushes don't arrive

Several possible causes:

Check	Fix
iPhone notification permission	Settings -> RemoteSignerPhone -> Notifications -> Allow.
Focus / Do Not Disturb mode	Turn off, or allow RemoteSignerPhone in your active Focus.
iPhone offline (no cell or Wi-Fi)	Wakes only deliver when the iPhone has a path to APNs.
APNs key file on Mac missing	Wakes silently fail. The key is normally bundled with the app; if you upgraded across breaking changes, reinstall vmuxAgent.
Device token stale	Open RemoteSignerPhone manually; it will refresh its token and send the new one to the Mac the next time you pair.

You can check the macOS unified log for the wake attempt:

log show --last 5m --predicate 'subsystem == "app.vmux.agent" AND category == "apns"'

A successful wake logs Wake push sent successfully; a failure logs Push failed: <code>.

Bucket 3: signing

Symptom: `ssh user@host` says agent refused operation

The agent could not produce a signature. Possible reasons:

Cause	How to confirm
Server doesn't trust the offered key	Run `ssh -v user@host`. If you see `Offering public key: ...` followed by no further offers, the key isn't in `authorized_keys`. Add it via `ssh-add -L` output.
Phone is unreachable and APNs wake failed	Menu bar shows Disconnected; no notification arrived on the phone. Open RemoteSignerPhone manually.
Sign request expired	The phone took longer than 60 seconds to approve. Try again.
User denied on the phone	The phone showed a Face ID prompt and you cancelled, or biometrics failed five times. Retry with Face ID lined up.
Pairing invalid	The phone has revoked or rotated the pairing. Quit and relaunch RemoteSignerPhone, then vmuxAgent.

The phone-side error message often appears in the Mac log:

log show --last 5m --predicate 'subsystem == "app.vmux.agent" AND category == "coordinator"'

Look for Sign request rejected: <message>.

Symptom: `ssh-add -l` says The agent has no identities

Three sub-cases:

iPhone never paired. Menu bar icon is hollow. Fix the pairing first.
iPhone paired but has no keys. Open RemoteSignerPhone and check that at least one identity exists. Generate one if needed.
Cache is stale and phone is offline. Click Refresh Keys in the menu (disabled if offline), or quit and relaunch vmuxAgent after the phone reconnects.

Symptom: signing is very slow (10+ seconds)

Cause	Fix
iPhone is asleep, every signature waits for APNs wake	Open RemoteSignerPhone and leave it foregrounded for the duration of the session, or issue a session certificate (menu -> Request Certificate) to amortize signatures.
Multipeer link is on Bluetooth-only	Bluetooth MPC is much slower than Wi-Fi. Move to Wi-Fi; toggle Wi-Fi on if it was off.
Mac is on a congested Wi-Fi network	AWDL contention with other Continuity features (AirDrop, Handoff). Try a different network or hotspot.

Symptom: repeated unpair-pair loop

Logs show repeated Connected to: <name> immediately followed by Disconnected from: <name>.

Cause	Fix
Two iPhones nearby, both running RemoteSignerPhone	Quit one. MPC is first-come-first-served and can flap if both respond.
iOS Background App Refresh is killing RemoteSignerPhone	iOS Settings -> RemoteSignerPhone -> Background App Refresh -> on.
Battery Saver / Low Power Mode on iPhone	Disable Low Power Mode for the duration; it suspends MPC aggressively.
Mac's network changed mid-pair (Wi-Fi to wired, joining VPN)	Pair after networks settle; avoid switching networks during signing.

Symptom: certificate keeps expiring or won't issue

Cause	Fix
Phone denies cert requests	Phone-side policy may have certs disabled. Check RemoteSignerPhone's settings.
Cert expires before auto-renew triggers	Auto-renew kicks in at 60 minutes left. If you frequently let the Mac sleep for hours, renewal won't happen. Click Request Certificate when you wake the Mac.
Server doesn't accept the cert	The server's `TrustedUserCAKeys` must include the vmux CA public key. Without that, signatures using the cert won't authenticate; the agent will fall through to the phone-held key.

Capturing logs for support

If a bug persists, capture the relevant logs:

log show --last 15m --predicate 'subsystem == "app.vmux.agent"' > /tmp/vmuxagent.log

The log includes connection lifecycle, sign request types, and APNs delivery results. It does not include any key material, signed challenges, or message payloads.

If you need verbose SSH output to pair with the agent log, run with -vv:

ssh -vv user@host 2> /tmp/ssh-debug.log

Attach both to a support request.

Resetting state

When all else fails, a clean reset:

# Quit vmuxAgent first (menu -> Quit), then:
rm -f ~/.ssh/vmux-agent.sock
defaults delete app.vmux.agent

This clears the cached public keys and last-known device token. Relaunch vmuxAgent; pair again from scratch.

On the iPhone side, quitting RemoteSignerPhone (swipe up from app switcher) and relaunching is enough. Reinstalling RemoteSignerPhone deletes its identities — only do this if you want to regenerate keys.

Getting started — first-run pairing.
iPhone pairing — discovery details.
SSH CLI integration — shell setup.
RemoteSignerPhone troubleshooting — phone-side issues.