Authentication Methods

Overview

vmux supports four ways to authenticate with a remote host. You choose the method per host in the connection form or when editing a saved host. Each method maps to a reusable identity that can be shared across multiple hosts.

Password

Traditional password authentication. Enter your password in the connection form and vmux sends it to the remote host during the SSH handshake.

• Passwords are stored in the system Keychain, encrypted at rest by the operating system.
• Passwords are never written to disk in plain text or included in settings exports.
• Deleting a host or identity also removes its Keychain entry.

If you leave the password field empty on a host configured for password auth, the connection will fail.

Device Key (Secure Enclave)

vmux generates a P-256 ECDSA key pair inside the device's Secure Enclave -- a dedicated hardware security chip. The private key never leaves the chip and cannot be exported.

Setup

1. In the connection form, select Secure Enclave as the authentication method.
2. Tap Generate Key. vmux creates the key pair and shows a confirmation.
3. Tap Copy Public Key to copy the public key to your clipboard.
4. Add the public key to ~/.ssh/authorized_keys on the remote host:

echo "ecdsa-sha2-nistp256 AAAA...= vmux@YourDevice" >> ~/.ssh/authorized_keys

You can also generate and manage the key from the SSH Key Manager in the Hosts Window.

For a detailed walkthrough of key generation, server setup, and troubleshooting, see SSH Key Management.

How it works

When you connect to a host configured for Secure Enclave auth, vmux signs the SSH authentication challenge using the hardware key. The server verifies the signature against your authorized_keys file. No password is sent.

Limits

• One key per device. Generating a new key replaces the previous one. Update authorized_keys on your servers after regenerating.
• Device-bound. Each device needs its own key. Keys cannot be transferred between devices.
• ECDSA P-256 only. The server must accept the ecdsa-sha2-nistp256 algorithm. Most modern SSH servers support it by default.

SSH Agent

Connect to a running SSH agent over TCP. This is useful when you want to use keys stored on another machine -- typically your Mac or workstation -- without copying private keys to the headset.

Setup

1. On your Mac or workstation, bridge the SSH agent socket to a TCP port using socat or a similar tool:

socat TCP-LISTEN:4242,reuseaddr,fork UNIX-CONNECT:$SSH_AUTH_SOCK

2. In the vmux connection form, select SSH Agent as the authentication method.
3. Enter the host (IP address or hostname of the machine running socat) and port (e.g., 4242).

vmux connects to the agent over TCP, lists available keys, and uses them for authentication. The agent handles all signing -- private keys stay on the machine running the agent.

Notes

• The default agent port is 4242. Change it to match your socat or bridge configuration.
• The agent host must be reachable from your Apple Vision Pro over the local network.
• Any key type supported by your agent works (Ed25519, RSA, ECDSA, etc.).

Companion App (Remote Signer)

The Remote Signer companion app runs on your iPhone and holds SSH keys in the phone's Secure Enclave. When vmux needs to authenticate, it sends the signing challenge to your phone over the local network. You approve the request on the phone, and the signed response is sent back to vmux.

How it works

1. Open the Remote Signer app on your iPhone.
2. In the vmux connection form, select Remote Signer as the authentication method.
3. Connect to a host. vmux discovers the companion app on the local network and sends the authentication challenge.
4. Approve the signing request on your phone.

Private keys never leave the iPhone. The headset only receives the signed challenge response.

Current limitations

vmux auto-connects to the first open Remote Signer app it discovers on the local network. There is no explicit device picker yet. Make sure only one Remote Signer instance is running on your network during authentication.

For more details on the companion app architecture, see Companion Apps.

Selecting a Method Per Host

When adding or editing a host in the Hosts Window, the Authentication section presents all four methods as selectable cards. Each card shows where the key is stored:

• Password -- "Password saved on this device."
• Secure Enclave -- "Key generated and stored on this device."
• SSH Agent -- "Key stored on your SSH agent."
• Remote Signer -- "Key stored on the companion app."

Tap a card to select it. Method-specific fields appear below (password field, agent host/port, key generation controls, etc.).

Identities

An identity is a reusable authentication configuration. When you save a host with a new authentication method, vmux creates a named identity that can be attached to other hosts.

For example, if you create a Secure Enclave identity called "Work Key", you can select it when adding other hosts instead of configuring the key again. Password identities store the credential in the Keychain once and reuse it across all attached hosts. SSH Agent identities remember the host and port of the agent bridge.

When editing a host, the Identity picker shows all saved identities that match the selected authentication method. You can pick an existing identity or create a new one.

Identity names

The optional Identity name field lets you label the identity for easier recognition (e.g., "Home Lab", "Production"). If you leave it blank, vmux generates a display name from the key comment or authentication method.

Fallback Behavior

vmux uses exactly the authentication method configured on the host profile. There is no automatic fallback chain.

• If a password host has no stored password, the connection fails with a prompt to enter one.
• If a Secure Enclave host has no generated key, the connection fails with a prompt to generate one.
• If an SSH Agent host cannot reach the agent, the connection fails with a timeout.
• If a Remote Signer host cannot discover the companion app, the connection fails with an unavailable error.

Each error message tells you what to do next. You can change the authentication method on any host at any time by editing it in the Hosts Window.