Tunnelyard Support

Tunnelyard runs in the App Store sandbox, so it can only read folders you pick. Use Allow Access to ~/.ssh… in the welcome guide, or Grant Access… in any tunnel’s Authentication section. In the panel that opens:

1. The panel opens on your .ssh folder. Click Grant Access.
2. If it shows another folder: press ⌘⇧H to go to your home folder, ⌘⇧. if hidden folders aren’t visible, select .ssh and click Grant Access.

Access is read-only and is remembered across launches. Tunnelyard then uses the aliases, HostName, User, Port, IdentityFile and ProxyJump from your ~/.ssh/config, and your existing key files. It never writes there. You can remove it anytime with Revoke in the Authentication section.

In the tunnel’s Authentication section, click Import Key… and choose the private key file (the one without .pub, for example id_ed25519). Supported: Ed25519, ECDSA and RSA keys in OpenSSH format, with or without a passphrase. The key is copied into your macOS Keychain, so the tunnel keeps working even without ~/.ssh access. Remove Key from Keychain deletes that copy.

• Older PEM keys (BEGIN RSA PRIVATE KEY): convert a copy to the OpenSSH format with ssh-keygen -p -f <key>.
• PuTTY keys: export them from PuTTYgen as an OpenSSH key.
• Passphrase-protected ECDSA keys aren’t supported yet: use an Ed25519 key, or import an unencrypted copy (it is stored in your Keychain).

Tunnelyard can currently sign with RSA only using ssh-rsa (SHA-1) signatures. OpenSSH 8.8 and newer servers refuse those by default, so an RSA key may fail with “rejected the RSA key”. Ed25519 or ECDSA keys work with all current servers. We recommend Ed25519:

ssh-keygen -t ed25519 -C "you@mac"

Then add the new .pub line to ~/.ssh/authorized_keys on the server (for example with ssh-copy-id -i ~/.ssh/id_ed25519.pub user@server in Terminal) and select or import the new key in Tunnelyard.

Tunnelyard remembers each server’s host key the first time you trust it. If the server later offers a different key, it refuses to connect, because this can mean someone is intercepting the connection. It is also normal after the server is reinstalled, rebuilt or its keys are rotated.

1. Ask the server’s administrator, or check on the server itself: ssh-keygen -lf /etc/ssh/ssh_host_ed25519_key.pub.
2. If the fingerprint matches the one Tunnelyard shows, choose Replace Trusted Key…. You can also remove a trusted key in the tunnel’s Host Key section with Forget.
3. If it doesn’t match, don’t connect.

Tunnelyard keeps its own list of trusted keys; it doesn’t read or change ~/.ssh/known_hosts.

Another app (or another tunnel) is already listening on that port on your Mac, often a local database or a second copy of the same tunnel. Tunnelyard checks before connecting and suggests the next free port: click Use … to switch, or change the local port in Port Forwarding. To see what holds the port, run in Terminal: lsof -nP -iTCP:5432 -sTCP:LISTEN (replace 5432 with your port).

• No ssh-agent. Tunnelyard can’t use keys loaded in ssh-agent, 1Password’s or another agent. Import the key, or grant ~/.ssh access so it reads the key file.
• No hardware keys. YubiKey/FIDO (sk-ssh-ed25519, sk-ecdsa), smart cards and PKCS#11 aren’t supported.
• No external commands. ProxyCommand and Match blocks in ~/.ssh/config are ignored. ProxyJump works, as do HostName, User, Port, IdentityFile, Include and the forward lines.
• Its own SSH client. Tunnelyard doesn’t run /usr/bin/ssh, so ~/.ssh/known_hosts isn’t shared and some OpenSSH-only options aren’t available.
• System settings stay untouched. For a SOCKS tunnel, Tunnelyard shows the commands to route the whole Mac through it; you run them yourself in Terminal.

Yes. If the network drops or the server stops answering, it reconnects automatically and keeps the local ports ready. The tunnel’s Health section shows uptime, traffic and the last problem (shown dimmed once the tunnel is connected again). Options like Auto-connect on launch and Survive brief network drops are in the tunnel’s settings; Launch at Login is in Preferences.

On your Mac only: tunnels in the app’s container, keys and saved passwords in your Keychain. Tunnelyard collects no data. See the privacy policy.