https://github.com/user-attachments/assets/18c181f3-b7df-42b0-a2c2-8a186eafef89
Opening a checkout of Neovim's source through two jump hosts: explorer, find files, symbols, hover and go-to-definition from a language server on the server, live grep, a remote terminal, and reopening the workspace from the recent list.
Work on a remote machine from your local Neovim, the way VS Code Remote-SSH does: your editor, config and plugins stay local; files, search and language servers live on the server.
local Neovim (UI, buffers, treesitter, your plugins)
│ one shared OpenSSH connection (ProxyJump etc. from ~/.ssh/config)
▼
remote agent (headless Neovim) ── file I/O, file watching, ripgrep,
language servers, mason
| Your config | What runs where | |
|---|---|---|
| sshfs / a mounted folder | local | Neovim, search and language servers run locally and read every file over the network: slow grep, slow LSP indexing |
netrw scp:// |
local | file transfer only; no project search, no remote LSP |
| Neovim over ssh on the server | the server's | your config and plugins have to be installed there; every keystroke waits on the network |
| nvim-remote-ssh | local | UI local; file I/O, ripgrep, file watching and language servers on the server |
ProxyJump / ProxyCommand
chains, Include, keys, agents. The system ssh binary does the work.rssh://host/path): atomic saves, permissions kept,
conflict detection when the file changed on the server, automatic reload.| Dependency | Required | Used for |
|---|---|---|
| Neovim 0.11+ | yes | |
OpenSSH client (ssh), 8.4+ recommended |
yes | all transport |
| telescope.nvim + plenary.nvim | recommended | pickers (falls back to vim.ui.select / quickfix) |
| treesitter parsers for your languages | for symbols | e.g. via nvim-treesitter |
nvim-lspconfig or your own vim.lsp.config() entries |
for LSP | server definitions |
Linux, macOS or WSL. Native Windows is not supported.
Linux or macOS, a POSIX sh, tar, gzip, curl or wget, and internet
access for the first connect. Everything else is installed automatically into
~/.local/share/nvim-remote-ssh:
rg; optionalIf the server has no internet access the first login fails with a message
saying so. :RemoteSSH uninstall <host> removes the directory again.
lazy.nvim:
{
"bradley101/nvim-remote-ssh",
dependencies = { "nvim-telescope/telescope.nvim", "nvim-lua/plenary.nvim" },
lazy = false,
opts = {},
}
lazy = false matters if your lazy.nvim setup lazy-loads by default (LazyVim
and other distributions set defaults.lazy = true): without it the plugin
stays under "Not Loaded" and :RemoteSSH does not exist. Loading is cheap;
nothing connects until you run a command. To lazy-load instead, use
cmd = "RemoteSSH", event = "BufReadCmd rssh://*" in place of lazy = false.
:RemoteSSH open " pick a host, then a folder
:RemoteSSH open myhost ~/src/project
| Command | |
|---|---|
:RemoteSSH open [host] [folder] |
connect and open a workspace |
:RemoteSSH connect [host] |
connect only |
:RemoteSSH recent |
recently opened workspaces |
:RemoteSSH files |
find a file |
:RemoteSSH reindex [host] |
list the workspace's files again |
:RemoteSSH grep [pattern] |
live grep (with a pattern: results to quickfix) |
:RemoteSSH symbols / outline |
symbols of the current buffer |
:RemoteSSH tree |
toggle the explorer (? inside it lists its keys) |
:RemoteSSH terminal |
shell in the workspace folder |
:RemoteSSH forward 8080[:3000] / unforward |
forward a local port |
:RemoteSSH disconnect / reconnect |
|
:RemoteSSH info / log |
state and diagnostics |
:RemoteSSH setup <host> |
retry optional downloads that failed |
:RemoteSSH uninstall <host> |
remove everything installed on the server |
While a remote workspace is in use, telescope's own find_files, live_grep
and grep_string search that workspace, so existing mappings such as
<leader>ff keep working; from a local file's buffer they search locally as
before. Set telescope = { override_builtins = false } to turn this off.
Finding files is instant after the first time: the workspace's files are
listed once, in the background, when it is opened, and the server watches its
folders so files created, deleted or moved there (from the explorer, a
terminal, git checkout, a build) are added to or removed from the list as
they change. Folders left out of the listing (.git, and with ripgrep
whatever .gitignore excludes) are not watched. If the server cannot watch
(more than search.max_files files, or its inotify watch limit is reached),
the cached list is still used and refreshed in the background every 30
seconds. :RemoteSSH reindex lists the files again from scratch, for example
after editing .gitignore; search = { file_cache = false } lists them on
every search instead.
The pickers are also available as :Telescope remote_ssh {hosts,recent,files,live_grep,symbols}. require("remote-ssh").statusline()
returns a string for your statusline. :checkhealth remote-ssh checks both
ends.
While a connection is being set up a small window shows the current step
("Connecting via jump1 → jump2", "Authenticating as me@host", "Inspecting
server", ...) and how long it has taken, so a slow chain of jump hosts does
not look like a hang. Turn it off with ui = { progress = false }.
Passwords, key passphrases, host key confirmations and other questions are
asked in a dialog in the middle of the screen, and the rest of the screen is
darkened while one of these windows is showing (a terminal cannot blur, so it
is dimmed; this needs termguicolors). ui = { dialogs = false } goes back
to the command line, and ui = { dim = 0 } turns the darkening off (default
40, up to 100). The dialogs use the highlight groups RemoteSSHDialogField,
RemoteSSHDialogChoice, RemoteSSHDialogHint and RemoteSSHBackdrop.
Connections to jump hosts are shared, also between Neovim windows: once a
jump host is connected (as a workspace of its own, or on the way to another
server), further servers behind it do not ask for its password again, however
many hops there are. A shared connection is closed by its last user, so
closing the jump host's window does not cut off a server behind it. ssh = { share_jump_hosts = false } leaves jump hosts entirely to ssh.
If this Neovim already has local files open, or is already used for another
remote host, :RemoteSSH open starts the
workspace in a Neovim of its own, in a new terminal window, instead of mixing
remote buffers into what is there. That works out of the box inside tmux,
WezTerm, kitty, Alacritty, iTerm2 and Terminal.app; elsewhere set how to open a terminal window:
opts = {
open = {
window = "auto", -- or "ask", or "same" to never do this
cmd = { "gnome-terminal", "--" } -- the nvim command is appended
},
}
When no way to open a window is known, the workspace opens in the current Neovim as before.
The new Neovim is started as nvim rssh-open://host/folder, which you can
also run yourself. Because that is a file argument, session plugins that
restore the last session on a plain nvim leave the new window alone.
Remote files saved in a session (:mksession, or any session plugin) are
restored: Neovim starts without waiting, the buffers show up empty for a
moment, and once the host is reconnected their contents, cursor positions,
workspace, language servers and (if it was showing) the explorer come back.
If the connection fails, :RemoteSSH reconnect <host> loads them.
nvim rssh://host/path/file works the same way.
Servers you enabled with vim.lsp.enable() are started on the server for
remote buffers, using the same definitions. When a server's executable is
missing there you are asked once whether to install it through mason; packages
that need a runtime (Node, Go, ...) need that runtime on the server.
require("remote-ssh").setup({
lsp = {
servers = { "lua_ls", "clangd" }, -- default: all enabled servers
configs = { clangd = { cmd = { "clangd-18" } } }, -- remote-only overrides
},
})
Defaults are in lua/remote-ssh/config.lua.
Commonly changed:
require("remote-ssh").setup({
remote = {
dir = nil, -- install directory on servers
use_system_nvim = true, -- reuse the server's nvim when new enough
confirm_install = true, -- ask once per host before downloading
},
sources = { ... }, -- download URLs and versions (for mirrors)
files = { watch = true, max_size = 50 * 1024 * 1024 },
search = { file_cache = true, max_files = 200000 },
reconnect = { auto = true, delays = { 2, 5, 15 } },
})
Issues and pull requests are welcome. See CHANGELOG.md for what changed in each release. Licensed under the MIT License.
tests/run.sh
runs the suite against a throwaway local sshd (needs root, sshd, rg,
python3): direct, jump-host and password logins, connection errors, the
installer (served from a local fake release server), remote buffers, search,
symbols, LSP through a fake language server, the explorer, port forwarding
and reconnects.
Not yet covered by automated tests: the Telescope front-ends, downloads from
the real GitHub release URLs, the real mason.nvim, macOS servers, and the
Neovim 0.11+ discovery of servers enabled with vim.lsp.enable() (the suite
passes lsp.configs explicitly so it can also run on older Neovim builds).