🧲 sshfs.yazi

A minimal, fast SSHFS integration for the Yazi terminal file‑manager.

Mount any host from your ~/.ssh/config, or add custom hosts, and browse remote files as if they were local. Jump between your local machine and remote mounts with a single keystroke.

yazi-sshfs-demo.mp4

Note

Linux Only (for now!)

This plugin currently supports Linux only. If you're interested in helping add support for other platforms, check out the open issues:

• Add macOS support
• Add Windows support

If you have some Lua experience (or want to learn), I’d be happy to walk you through integration and testing. Pull requests are welcome!

🤔 Why SSHFS?

• Works anywhere you have SSH access. No VPN, NFS or Samba needed – only port 22.
• Treat remote files like local ones. Run vim, nvim, sed, preview images / videos directly, etc.
• User‑space, unprivileged. No root required; mounts live under your chosen mount directory or the default (~/mnt).
• Bandwidth‑friendly. SSH compression, connection timeout, and reconnect options are enabled by default.
• Quick Loading and Operations. Load / edit files quickly without any lag and use all the tools from your local machine.

Perfect for tweaking configs, deploying sites, inspecting logs, or just grabbing / editing / deleting files remotely.

🧠 What it does under the hood

This plugin serves as a wrapper for the sshfs command, integrating it seamlessly with Yazi. It automatically reads hosts from your ~/.ssh/config file. Additionally, it maintains a separate list of custom hosts in ~/.config/yazi/sshfs.list.

The core default sshfs command used is as follows (you may tweak these options and the mount directory with your setup settings):

sshfs user@host: ~/mnt/alias -o reconnect,compression=yes,ServerAliveInterval=15,ServerAliveCountMax=3

✨ Features

• One‑key mounting – remembers your SSH hosts and reads from your ssh_config.
• Jump/Return workflow – quickly copy files between local & remote.
• Uses sshfs directly.
• Mount‑points live under your chosen mount directory (default: ~/mnt), keeping them isolated from your regular file hierarchy.

📋 Requirements

Software	Minimum	Notes
Yazi	>=25.5.31	tested on 25.6+
sshfs	any	sudo dnf/apt/pacman install sshfs
fusermount	from FUSE	Usually pre-installed on Linux
SSH config	working hosts	Hosts come from ~/.ssh/config

📦 Installation

Install the plugin via Yazi's package manager:

# via Yazi’s package manager
ya pack -a uhs-robert/sshfs

Then add the following to your ~/.config/yazi/init.lua to enable the plugin with default settings:

require("sshfs"):setup()

⚙️ Configuration

To customize plugin behavior, you may pass a config table to setup() (default settings are displayed):

require("sshfs"):setup({
  -- Mount directory
  mount_dir = "~/mnt"

  -- Set connection timeout when connecting to server (in seconds).
  connect_timeout = 5,

  -- Enable or disable compression.
  compression = true,

  -- Interval to send keep-alive messages to the server.
  server_alive_interval = 15,

  -- Number of keep-alive messages to send before disconnecting.
  server_alive_count_max = 3,

  -- Enable or disable directory caching.
  dir_cache = false,

  -- Directory cache timeout in seconds.
  -- Only applies if dir_cache is enabled.
  dcache_timeout = 300,

  -- Maximum size of the directory cache.
  -- Only applies if dir_cache is enabled.
  dcache_max_size = 10000,
})

These configuration options apply to the sshfs command. You can learn more about sshfs mount options here.

In addition, sshfs also supports a variety of options from sftp and ssh_config.

🎹 Key Mapping

Add the following to your ~/.config/yazi/keymap.toml. You can customize keybindings to your preference.

[mgr]
prepend_keymap = [
  { on = ["M","a"], run = "plugin sshfs -- add",             desc = "Add SSH host" },
  { on = ["M","r"], run = "plugin sshfs -- remove",          desc = "Remove SSH host" },
  { on = ["M","m"], run = "plugin sshfs -- mount --jump",    desc = "Mount & jump" },
  { on = ["M","u"], run = "plugin sshfs -- unmount",         desc = "Unmount SSHFS" },
  { on = ["M","c"], run = "cd ~/.ssh/",                      desc = "Go to ssh config" },
  { on = ["g","m"], run = "plugin sshfs -- jump",            desc = "Jump to mount" },
]

🚀 Usage

• Mount (M m): Choose a host and select a remote directory (~ or /). This works for hosts from your~/.ssh/config and any custom hosts you've added.
• Add host (M a): Enter a custom host (user@host) for Yazi-only use (useful for quick testing or temp setups). For persistent, system-wide access, updating your .ssh/config is recommended.
• Remove host (M r): Select and remove any Yazi-only hosts that you've added.
• Jump to mount (g m): Jump to any active mount from another tab or location.
• Unmount (M u): Choose an active mount to unmount it.

💡 Tips and Performance

• If key authentication fails, the plugin will prompt for a password up to 3 times before giving up.
• SSH keys vastly speed up repeated mounts (no password prompt), leverage your ssh_config rather than manually adding hosts to make this as easy as possible.

📜 License

This plugin is released under the MIT license. Please see the LICENSE file for details.