SSH config & keys

obsidian-remote-ssh uses your existing SSH credentials (key files, agent) — it does not maintain its own keychain.

Authentication methods

Picked per profile in Settings → Profile → Authentication:

Method	Settings field	Use when
Private key file (default)	Private key path → ~/.ssh/id_ed25519 etc.	Most common; tilde-expanded at runtime
SSH agent	(no path needed)	You run ssh-agent (most macOS / WSL setups; OpenSSH on Windows via ssh-agent service); plugin asks the agent to sign
Password	(none stored)	Fallback when keys are not an option; plugin prompts for password each connect; never persisted

Passphrase-protected keys: if your agent has the unlocked key, agent auth works transparently. Otherwise the plugin prompts for the passphrase per connect.

What the plugin reads from ~/.ssh/

Currently:

• The key file you point at (~/.ssh/id_ed25519, ~/.ssh/id_rsa, etc.) — supports ed25519, rsa, ecdsa.
• ssh-agent socket via SSH_AUTH_SOCK (Linux/macOS) or the OpenSSH agent service on Windows.
• ~/.ssh/config — the profile form has an Import from SSH config dropdown that lists Host blocks and pre-fills the profile fields (host, port, user, identity file).
• NOT used: ~/.ssh/known_hosts. The plugin manages its own — see Host keys.

Known-host trust (TOFU)

First connection to a new host shows a host-key fingerprint dialog. Trusting writes the fingerprint into the plugin’s own known-host store. On subsequent connects, the fingerprint is verified silently. A mismatch on a known host opens a mismatch dialog. This is independent of ~/.ssh/known_hosts to keep the plugin’s trust scope explicit.

Common setups

macOS / Linux with ssh-agent

eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_ed25519

In the plugin: pick Authentication: SSH agent. Done.

Windows

Get-Service ssh-agent | Set-Service -StartupType Automatic
Start-Service ssh-agent
ssh-add $HOME\.ssh\id_ed25519

Then pick Authentication: SSH agent in the plugin.

Hardware key (YubiKey, Secure Enclave)

Anything ssh-agent can sign with works. Set up your hardware key with your normal SSH workflow first, then pick SSH agent in the plugin.

Troubleshooting

Symptom	Likely cause
Permission denied (publickey)	Wrong path / key not authorized on remote / agent does not have the key
Connection timeout	Network unreachable, or remote sshd is on a non-22 port — set Port explicitly
Bad host key	Remote host key changed; see mismatch flow
Plugin asks for password every connect, even with SSH agent	Agent is not running or SSH_AUTH_SOCK is not set in Obsidian’s environment

For deeper diagnostics: Settings → Advanced → Debug logging on, then re-connect and check the Obsidian developer console.

Next: Jump hosts.