bradley101/nvim-remote-ssh

github github
remote-development
stars 3
issues 1
subscribers 0
forks 0
CREATED

UPDATED


nvim-remote-ssh

CI License: MIT Neovim 0.11+

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

Why this and not...

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

Features

  • Hosts from your ssh config, including ProxyJump / ProxyCommand chains, Include, keys, agents. The system ssh binary does the work.
  • Prompts inside Neovim: passwords, key passphrases, one-time codes and host-key confirmation.
  • Zero-setup servers: on first connect the plugin inspects the server and, after one confirmation, downloads what is missing into a single directory (no root, nothing else touched).
  • Remote buffers (rssh://host/path): atomic saves, permissions kept, conflict detection when the file changed on the server, automatic reload.
  • File explorer with create / rename / copy / delete.
  • Find files and live grep on the server (ripgrep, or grep/find).
  • Symbols and outline from treesitter (functions, methods, classes...).
  • LSP: language servers run on the server and attach to Neovim's built-in client; missing servers can be installed there through mason.
  • Remote terminal and port forwarding.
  • Reconnects after a dropped connection; unsaved edits are never discarded.

Requirements (your machine)

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.

Requirements (the server)

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:

  • Neovim (runs the agent) — skipped when the server already has Neovim 0.10+
  • ripgrep — skipped when the server has rg; optional
  • mason.nvim — installs language servers on request; optional

If the server has no internet access the first login fails with a message saying so. :RemoteSSH uninstall <host> removes the directory again.

Install

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.

Usage

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

Connecting

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.

Sessions

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.

Language servers

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
  },
})

Configuration

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 } },
})

Security notes

  • Downloads are verified against published SHA-256 checksums. A mismatch aborts; if no checksum can be obtained you are asked before continuing. mason.nvim is fetched as a tagged source archive over HTTPS (no checksum is published for it).
  • A changed host key is never accepted automatically.
  • The protocol is one-way: the client sends requests, the agent answers. A compromised server cannot run commands in your Neovim. File contents and language-server messages from the server are, of course, shown to you.

Contributing

Issues and pull requests are welcome. See CHANGELOG.md for what changed in each release. Licensed under the MIT License.

Development

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