Menu Bar Reference
Every item in the vmuxAgent menu bar dropdown — connection status, key list, certificate state, and one-click actions.
The menu bar icon
vmuxAgent shows a single key glyph in the system menu bar. The fill state is the at-a-glance pairing indicator:
| Icon | Meaning |
|---|---|
| Hollow key | No iPhone paired, or pairing dropped |
| Filled key | iPhone paired and connected |
Click the icon to open the dropdown. The contents change depending on connection state and certificate state.
Connection status
The first line is always one of:
- Connected to iPhone Name — the menu bar icon is filled, the iPhone is reachable, and signing is online. iPhone Name is the device's localized name (whatever you called it in Settings -> General -> About -> Name on the iPhone).
- Disconnected — the agent is up and the socket is listening, but no iPhone is reachable. Cached public keys are still listed below; signing will fail or trigger an APNs wake.
This line updates within a few seconds of the underlying state changing.
Certificate status
Below connection status, vmuxAgent shows the state of the short-lived session certificate it requests from the phone's CA on every pair. There are three possibilities:
| Label | Meaning | Color |
|---|---|---|
| Certificate valid until time | Active session cert; signatures up to the wall-clock cutoff are signed locally on the Mac without prompting the phone for every keystroke. | Green |
| Certificate expired — connect phone to renew | The cert has passed its validBefore timestamp. The next signature falls back to the phone. | Orange |
| No session certificate | No cert has been issued yet, or it was cleared. New signatures will go through the phone with biometrics. | Secondary (gray) |
The session certificate has a default validity of 8 hours and auto-renews when fewer than 60 minutes remain on it, as long as the iPhone is reachable. See Keys and certificates for the full lifecycle.
Key list
A divider separates the status header from the key list. Each key advertised by the iPhone shows up as a two-line entry:
| Field | Format | Source |
|---|---|---|
| Comment | Free text | Set on the phone (e.g. iphone-secure-enclave, prod-deploy) |
| Fingerprint | SHA256: + base64 hash of the public-key blob | Computed locally on the Mac |
Examples:
iphone-secure-enclave
SHA256:K9F+Z3W...
prod-deploy-key
SHA256:Aq2nG7d...If the iPhone has not been paired yet (so no public keys have been received and no cache exists), the list shows No keys available in gray.
The cache survives app restarts. If you quit and relaunch vmuxAgent while the iPhone is asleep, the same key entries are shown so ssh-add -l continues to work; the actual signature has to wait for the phone.
Action buttons
Below the key list:
Copy SSH_AUTH_SOCK Command
Puts the line below on your clipboard, with the absolute path to your home directory expanded. This is the most common way to wire up vmuxAgent into a new shell.
export SSH_AUTH_SOCK=/Users/you/.ssh/vmux-agent.sockPaste it into your ~/.zshrc, ~/.bash_profile, or a fresh terminal to use the agent for that shell. See SSH CLI integration for the persistent setup.
Request Certificate
Forces a new session-certificate request to the iPhone immediately, even if the existing one is still valid. Useful if you want to extend validity past the auto-renewal threshold or if you are testing the workflow.
This button is disabled when no iPhone is paired. The request is denied if the user declines on the phone; the certificate state in the menu does not change.
Refresh Keys
Asks the iPhone for its current list of public keys and replaces the local cache with the response. Use this after you add or remove an identity on the phone (or change a comment) so the change shows up in ssh-add -l immediately.
This button is disabled when no iPhone is paired. While disabled, the cache from the last pair is still served, but new keys cannot appear until you reconnect.
Quit
Standard quit (Cmd+Q). Closes the socket and cleans up ~/.ssh/vmux-agent.sock so a future launch starts fresh. SSH commands running in your terminals will fail at the next signing operation; relaunch vmuxAgent to recover.
What's intentionally not in the menu
A few things you might expect to find here are deliberately elsewhere or absent:
- Pairing button. There isn't one. Multipeer Connectivity discovers and invites peers automatically. Both apps must be running on the same link; pairing happens within seconds.
- Key generation. Keys are generated on the iPhone, not the Mac. See RemoteSignerPhone for the identity store and key creation flow.
- Per-host approval policy. vmuxAgent always forwards to the phone; per-host policy lives on the phone side.
- Settings panel. vmuxAgent has no settings of its own — every knob is on the iPhone or the system clipboard. Future versions may add a small preferences pane for the socket path and APNs configuration.
- Forwarding control. SSH agent forwarding (
-A) is a property of the SSH client, not the agent. See SSH CLI integration.
Quick reference
| Item | Disabled when | Side effect |
|---|---|---|
| Connection line | Never | Updates in real time |
| Certificate line | Never | Auto-renews when phone is reachable |
| Each key entry | Never | None — display only |
| Copy SSH_AUTH_SOCK Command | Never | Writes to system pasteboard |
| Request Certificate | Phone disconnected | Triggers Face ID on the phone |
| Refresh Keys | Phone disconnected | Replaces local cache; persists to disk |
| Quit | Never | Closes socket; current SSH calls fail next op |
Related
- Getting started — first-run walkthrough.
- Keys and certificates — what the cache and certificate hold.
- Troubleshooting — what to do if a button is disabled when it shouldn't be.