A minimal, blazing 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.

• Works anywhere you have SSH access. Nothing extra is 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.

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

• 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.

To use sshfs.yazi on macOS, follow these steps:

1. Install macFUSE Download and install macFUSE from the official site: https://macfuse.github.io/

2. Install SSHFS for macFUSE Use the official SSHFS releases compatible with macFUSE: https://github.com/macfuse/macfuse/wiki/File-Systems-%E2%80%90-SSHFS

3. Install Yazi On macOS via Homebrew:

   brew install yazi

Install the plugin via Yazi's package manager:

ya pkg add uhs-robert/sshfs

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

require("sshfs"):setup()

Add this to your ~/.config/yazi/keymap.toml for a conflict-free approach that works well with other plugins:

[mgr]
prepend_keymap = [
  { on = ["M","s"], run = "plugin sshfs -- menu",            desc = "Open SSHFS options" },
]

The M s menu provides access to all SSHFS functions:

• m → Mount & jump
• u → Unmount
• j → Jump to mount
• a → Add host
• r → Remove host
• h → Go to mount home
• c → Open ~/.ssh/config

If you prefer direct keybinds, you may also set your own using our API. Here are the available options from the default preset:

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

• SSHFS Menu (M s): Opens an interactive menu with all SSHFS options
  • 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.
  • Unmount (M u): Choose an active mount to unmount it.
  • Jump to mount (M j): Jump to any active mount from another tab or location
  • 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 home directory (M h): Jump to the mount home directory.

• 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.

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

require("sshfs"):setup({
  -- Mount directory
  mount_dir = os.getenv("HOME") .. "/mnt",

  -- Password authentication attempts before giving up
  password_attempts = 3,

  -- Default mount point: Go to home, root, or always ask where to go
  default_mount_point = "auto" -- home | root | auto

  -- SSHFS mount options (array of strings)
  -- These options are passed directly to the sshfs command
  sshfs_options = {
    "reconnect",                      -- Auto-reconnect on connection loss
    "ConnectTimeout=5",               -- Connection timeout in seconds
    "compression=yes",                -- Enable compression
    "ServerAliveInterval=15",         -- Keep-alive interval (15s × 3 = 45s timeout)
    "ServerAliveCountMax=3",          -- Keep-alive message count
    -- "dir_cache=yes",               -- Enable directory caching (default: yes)
    -- "dcache_timeout=300",          -- Cache timeout in seconds
    -- "dcache_max_size=10000",       -- Max cache size
    -- "allow_other",                 -- Allow other users to access mount
    -- "uid=1000,gid=1000",           -- Set file ownership
    -- "follow_symlinks",             -- Follow symbolic links
  },

  -- Picker UI settings
  ui = {
    -- Maximum number of items to show in the menu picker.
    -- If the list exceeds this number, a different picker (like fzf) is used.
    menu_max = 15, -- Recommended: 10–20. Max: 36.

    -- Picker strategy:
    -- "auto": uses menu if items <= menu_max, otherwise fzf (if available) or a filterable list
    -- "fzf": always use fzf if available, otherwise fallback to a filterable list
    picker = "auto", -- "auto" | "fzf"
  },
})

All sshfs options are specified in the sshfs_options array. You can learn more about sshfs mount options here.

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

Here are some common sshfs option combinations:

-- Minimal reliable setup
require("sshfs"):setup({
  sshfs_options = {
    "reconnect",
    "ServerAliveInterval=15",
    "ServerAliveCountMax=3",
  },
})

-- Performance optimized
require("sshfs"):setup({
  sshfs_options = {
    "reconnect",
    "compression=yes",
    "cache_timeout=300",
    "ConnectTimeout=10",
    "dir_cache=yes",
    "dcache_timeout=600",
  },
})

-- Multi-user access
require("sshfs"):setup({
  sshfs_options = {
    "reconnect",
    "allow_other",
    "uid=1000,gid=1000",
    "umask=022",
    "ServerAliveInterval=30",
  },
})