Getting Started

What you will accomplish

By the end of this page, you will have:

1. RemoteSignerPhone installed and notification permission granted.
2. One Secure Enclave identity provisioned, with its OpenSSH public key on your clipboard.
3. The public key appended to a real Linux server's ~/.ssh/authorized_keys.
4. A successful ssh user@host login from your Mac, signed by your iPhone with one Face ID approval.

The whole flow takes about ten minutes the first time. Subsequent identities take well under a minute.

Step 1 — Install and launch

Install RemoteSignerPhone from the App Store on the iPhone you intend to use as your trust anchor. The app icon is a key; the bundle identifier is app.vmux.remotesigner.

On first launch, iOS asks for notifications permission. Tap Allow. Notifications are how you see incoming sign requests when the app is backgrounded, and how the iPhone wakes when paired devices need a signature. If you skipped this prompt, open Settings → Notifications → RemoteSigner and enable Allow Notifications, with Sounds on.

The home screen opens directly to the Remote Signers view. The Overview section will read Provisioned: 0, the Transport section will show Status: Advertising, and APNs Token will be Registered (or Not registered if you do not have internet — that is fine for this walkthrough; APNs only matters once the app is backgrounded).

Step 2 — Provision your first identity

Tap the + button in the top-right, or the large Provision Signer button at the bottom. The New Signer sheet opens with a default label like Phone Key 1 already filled in. Edit if you like — labels are visible to paired Macs and to your own future self in authorized_keys, so something like Doug iPhone or Work key works well.

Tap Create. iOS pops a Face ID prompt to authorize the Secure Enclave key creation. After biometrics succeed, the sheet dismisses, the Status banner reads Created Phone Key 1., and a new row appears under Signers showing the label, fingerprint, and OpenSSH public key.

Behind the scenes, RemoteSignerPhone:

• Generated an ECDSA P-256 private key inside the Secure Enclave, with userPresence and unlocked-this-device-only access flags.
• Stored a non-exportable reference to that key in the iOS Keychain.
• Recorded the public-key OpenSSH string and SHA-256 fingerprint in app metadata.

The private key never touched application memory in raw form.

Step 3 — Copy the public key

Tap the new identity row. The detail screen shows the full OpenSSH public-key line, like:

ecdsa-sha2-nistp256 AAAAE2VjZHNhLXNoYTItbmlzdHAyNTY...= Phone Key 1

Tap Copy Public Key. The Status banner confirms Copied public key for Phone Key 1.

The OpenSSH key string is what you put on the server. The fingerprint shown above it (SHA256:…) is what ssh -v and ssh-keygen -lf will print when verifying — useful for cross-checking that the right key is being offered.

Step 4 — Add the key to a server's authorized_keys

You need somewhere to send the public key. AirDrop to your Mac is the fastest path; alternatives are Messages to yourself, an email draft, or pasting into a Notes file synced through iCloud.

On the server you want to log into, append the line to the user's ~/.ssh/authorized_keys:

echo 'ecdsa-sha2-nistp256 AAAAE2VjZHNhLXNoYTItbmlzdHAyNTY...= Phone Key 1' >> ~/.ssh/authorized_keys
chmod 600 ~/.ssh/authorized_keys

Confirm the file is readable only by your user, and confirm ~/.ssh is 700. Most modern Linux distributions ship sshd with ecdsa-sha2-nistp256 enabled by default; if your server rejects it, check /etc/ssh/sshd_config for any PubkeyAcceptedAlgorithms line that excludes ECDSA and add it back.

Stay on the server's terminal — you will reconnect from the Mac in a moment to verify.

Step 5 — Pair vmuxAgent on the Mac

Now hook up the Mac side so ssh knows where to find your iPhone-held key. Install vmuxAgent and run through its first-launch pairing. In short:

1. Launch vmuxAgent. The menu bar icon appears.

2. From the agent menu, choose Pair iPhone. The Mac broadcasts a Multipeer invitation.

3. On the iPhone, RemoteSignerPhone's Transport section flips from Advertising to Connecting to <Mac name>, then to Connected to <Mac name>.

4. The Mac asks for your shell to use ~/.ssh/vmux-agent.sock as its SSH agent. Add this to your shell rc file:

   export SSH_AUTH_SOCK=~/.ssh/vmux-agent.sock

   Open a new shell so the variable takes effect.

Confirm the agent sees your iPhone-held key:

ssh-add -L

You should see the same ecdsa-sha2-nistp256 … line you copied from the iPhone, with the label as the comment. If ssh-add -L says "The agent has no identities," the iPhone is paired but no identities are enabled — go back to RemoteSignerPhone and check the toggle on the row.

See the vmuxAgent getting started page for the full Mac-side walkthrough including auto-launch and socket troubleshooting.

Step 6 — Sign your first SSH connection

From the Mac:

ssh user@host

Several things happen at once. The Mac's ssh client asks vmuxAgent for a signature. vmuxAgent forwards the request over the encrypted Multipeer link to your iPhone. RemoteSignerPhone shows a Sign Request sheet on the iPhone listing the source device (your Mac), the destination host, and the username. iOS overlays a Face ID prompt automatically when you tap Approve.

Approve. The Secure Enclave produces a signature, the iPhone returns it to the Mac, and ssh completes the handshake. You are now logged in to user@host with no password and no private-key file anywhere on the Mac.

If anything went wrong, the troubleshooting page enumerates every common failure with a fix.

What you have now

• A hardware-bound SSH identity on your iPhone that you can use from any Mac (with vmuxAgent) or Apple Vision Pro (with vmux) on the same local network.
• A public key on the server that authorizes only signatures produced by Face ID approvals on your specific iPhone.
• An auditable per-sign approval trail — you saw the host name before you authorized, and every future signature will prompt the same way.

Where to go next

• Creating identities — when to provision more keys, label conventions, and exporting public keys via AirDrop, share sheet, or paste.
• Approving signing — the per-request UX in detail.
• SSH signing with iPhone (visionOS) — connect to the same server from Apple Vision Pro using the same iPhone-held key.