remote-nvim.nvim

KO | EN

gitlite — search

#ai-agent #cli #pytorch #anthropic #claude-code #awesome #tensorflow #http #command-line #tailwindcss

remote-nvim.nvim

(★ 9)

Remote development in Neovim 🔥

File Explorer

ZIP Download

- - bug_report.md
  - feature_request.md
- - ci.yml
  - docs.yml
  - installation_test.yml
  - pages.yml
  - release.yml
- remote-nvim.txt
- - colors.lua
  - command.lua
  - config.lua
  - constants.lua
  - deprecation.lua
  - detached_registry.lua
  - health.lua
  - init.lua
  - middleclass.lua
  - offline-mode.lua
  - ui.lua
  - utils.lua
- - api.sh
  - core.sh
  - neovim.sh
- free_port_finder.lua
- neovim_download.sh
- neovim_install.sh
- - demo-cover.jpg
- - index.html
- 404.html
- index.html
- main.js
- styles.css
- - command_spec.lua
  - config_spec.lua
  - detached_registry_spec.lua
  - init_spec.lua
  - utils_spec.lua
- init.lua
.editorconfig
.gitignore
.markdownlint.yaml
.pre-commit-config.yaml
.shellcheckrc
AGENTS.md
CHANGELOG.md
CONTRIBUTING.md
lazy.lua
LICENSE
Makefile
neovim.yaml
pyproject.toml
README.md
README.zh-CN.md
remote-nvim-technical-blog.zh-CN.md
repro.lua
selene.toml
TODO.md

# Use via CDN

jsDelivr

jsDelivr serves any public GitHub repository as a CDN with zero setup. Pick a version and a file to get a ready-to-paste link and snippet.

Version

File

Link

Example

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

[中文](README.zh-CN.md) | English

Project site: <https://fangpin.github.io/remote-nvim.nvim/>
Detailed docs: <https://fangpin.github.io/remote-nvim.nvim/docs/>

Adds support for [remote development](https://code.visualstudio.com/docs/remote/remote-overview)
and [devcontainers](https://code.visualstudio.com/docs/devcontainers/containers)
to Neovim (just like VSCode). Read in the [FAQ](#faq) at the end of this document why you would prefer
using remote-nvim instead of SSH into remote + local neovim.

## ✨ Features

| Remote mode                   | Current support     |
| ----------------------------- | ------------------- |
| SSH (using password)          | _Fully supported_ ✅ |
| SSH (using SSH key)           | _Fully supported_ ✅ |
| SSH (using `ssh_config` file) | _Fully supported_ ✅ |
| Docker image [^1]             | _Fully supported_ ✅ |
| Docker container [^1]         | _Fully supported_ ✅ |
| Devcontainer [^1]             | _Fully supported_ ✅ |

### Implemented features

- **Offline mode** - If the remote does not have access to GitHub, Neovim release can be locally
  downloaded and then transferred to the remote. For more details, see [Offline mode](#-offline-mode).
- **Alternate install methods** - If Neovim is not available for your OS and/or arch, you can
  build it from source or use Neovim installed globally on remote. Make sure you have the pre-requisites mentioned
  in [BUILD.md](https://github.com/neovim/neovim/blob/master/BUILD.md) already installed on remote so that the
  build process does not break.

#### ✨ Other noice features

- Automatically install and launch Neovim
- No changes to your remote environment
- Can copy over and sync your local Neovim configuration to remote
- Saves your past sessions automatically so you can easily reconnect
- Easily cleanup the remote machine once you are done with a single command

See [#126](https://github.com/amitds1997/remote-nvim.nvim/issues/126) for the list of planned but not yet implemented
features.

## 📜 Requirements

### OS support

| Support level           | OS                         |
| ----------------------- | -------------------------- |
| ✅ **Supported**         | Linux, MacOS, FreeBSD [^2] |
| 🟡 **Not supported yet** | Windows, WSL               |

### Local machine 💻

- OpenSSH client
- Neovim >= 0.9.0 (as `nvim`)
- Binaries
  - `curl`
  - `rsync`
  - `tar` (optional; if you use compressed uploads)
  - [`devpod`](https://devpod.sh/docs/getting-started/install#optional-install-devpod-cli) >= 0.5.0 (optional; if you want to use devcontainer)
- Connectivity to [neovim repo](https://github.com/neovim/neovim) on GitHub

Connectivity to [neovim repo](https://github.com/neovim/neovim) on GitHub is not needed when using
[Offline mode (No GitHub)](#offline-on-remote-and-local-machine) but it comes with
it's own trade offs.

### Remote machine ☁️

- OpenSSH-compliant SSH server
- `bash` shell must be available
- Connectivity to [neovim repo](https://github.com/neovim/neovim) on GitHub
- Binaries
  - `bash`
  - `curl` or `wget`
  - `rsync`

Connectivity to [neovim repo](https://github.com/neovim/neovim) on GitHub is not needed when using
[Offline mode](#-offline-mode).

## 📥 Installation

Using [lazy.nvim](https://github.com/folke/lazy.nvim)

```lua
{
   "fangpin/remote-nvim.nvim",
   version = "*", -- Pin to GitHub releases
   dependencies = {
       "nvim-lua/plenary.nvim", -- For standard functions
       "MunifTanjim/nui.nvim", -- To build the plugin UI
       "nvim-telescope/telescope.nvim", -- For picking b/w different remote methods
   },
   config = true,
}
```

_Ensure you have [devpod](https://devpod.sh/docs/getting-started/install#optional-install-devpod-cli) >= 0.5.0
installed for any devcontainer-related features to work_

If you use any other plugin manager, ensure that you call `require("remote-nvim").setup()`.

> [!NOTE]
>
> Run `:checkhealth remote-nvim` to ensure necesssary binaries are available. If missing,
> parts of the plugin might be broken.

## ⚙️ Advanced configuration

Below is the default configuration. Set only things that you wish to change in your `setup()` call.
Please read the associated comments before changing the value.

```lua
 {
  -- Configuration for devpod connections
  devpod = {
    binary = "devpod", -- Binary to use for devpod
    docker_binary = "docker", -- Binary to use for docker-related commands
    ---@diagnostic disable-next-line:param-type-mismatch
    ssh_config_path = utils.path_join(utils.is_windows, vim.fn.stdpath("data"), constants.PLUGIN_NAME, "ssh_config"), -- Path where devpod SSH configurations should be stored
    search_style = "current_dir_only", -- How should devcontainers be searched
    -- For dotfiles, see https://devpod.sh/docs/developing-in-workspaces/dotfiles-in-a-workspace for more information
    dotfiles = {
        path = nil, -- Path to your dotfiles which should be copied into devcontainers
        install_script = nil -- Install script that should be called to install your dotfiles
    },
    gpg_agent_forwarding = false, -- Should GPG agent be forwarded over the network
    container_list = "running_only", -- How should docker list containers ("running_only" or "all")
  },
  -- Configuration for SSH connections
  ssh_config = {
    ssh_binary = "ssh", -- Binary to use for running SSH command
    rsync_binary = "rsync", -- Binary to use for running rsync copy commands
    ssh_config_file_paths = { "$HOME/.ssh/config" }, -- Which files should be considered to contain the ssh host configurations. NOTE: `Include` is respected in the provided files.

-- These are useful for password-based SSH authentication.
    -- It provides parsing pattern for the plugin to detect that an input is requested.
    -- Each element contains the following attributes:
    -- match - The string to match (plain matching is done)
    -- type - Supports two values "plain"|"secret". Secret means when you provide the value, it should not be stored in the completion history of Neovim.
    -- value - Default value for the prompt
    -- value_type - "static"|"dynamic". For things like password, it would be needed for each new connection that the plugin initiates which could be obtrusive.
    -- So, we save the value (only for current session's interval) to ease the process. If set to "dynamic", we do not save the value even for the session. You have to provide a fresh value each time.
    ssh_prompts = {
      {
        match = "password:",
        type = "secret",
        value_type = "static",
        value = "",
      },
      {
        match = "continue connecting (yes/no/[fingerprint])?",
        type = "plain",
        value_type = "static",
        value = "",
      },
      -- There are other values here which can be checked in lua/remote-nvim/init.lua
    },
  },

-- Path to the script that would be copied to the remote and called to ensure that neovim gets installed.
  -- Default path is to the plugin's own ./scripts/neovim_install.sh file.
  neovim_install_script_path = utils.path_join(
    utils.is_windows,
    vim.fn.fnamemodify(debug.getinfo(1).source:sub(2), ":h:h:h"),
    "scripts",
    "neovim_install.sh"
  ),

-- Modify the UI for the plugin's progress viewer.
  -- type can be "split" or "popup". All options from https://github.com/MunifTanjim/nui.nvim/tree/main/lua/nui/popup and https://github.com/MunifTanjim/nui.nvim/tree/main/lua/nui/split are supported.
  -- Note that some options like "border" are only available for "popup".
  progress_view = {
    type = "popup",
  },

-- Offline mode configuration. For more details, see the "Offline mode" section below.
  offline_mode = {
    -- Should offline mode be enabled?
    enabled = false,
    -- Do not connect to GitHub at all. Not even to get release information.
    no_github = false,
    -- What path should be looked at to find locally available releases
    cache_dir = utils.path_join(utils.is_windows, vim.fn.stdpath("cache"), constants.PLUGIN_NAME, "version_cache"),
  },

-- Remote configuration
  remote = {
    app_name = "nvim", -- This directly maps to the value NVIM_APPNAME. If you use any other paths for configuration, also make sure to set this.
    reconnect = {
      enabled = false, -- Automatically relaunch the remote Neovim session if the SSH job exits unexpectedly.
      max_attempts = 5, -- Maximum reconnect attempts for a single unexpected disconnect.
      backoff_ms = 2000, -- Base delay between reconnect attempts. The delay increases by this value on each attempt.
    },
    detach = {
      enabled = false, -- Launch SSH remote servers in detached mode so :RemoteDetach/:RemoteReattach can keep the server alive.
    },
    -- List of directories that should be copied over
    copy_dirs = {
      -- What to copy to remote's Neovim config directory
      config = {
        base = vim.fn.stdpath("config"), -- Path from where data has to be copied
        dirs = "*", -- Directories that should be copied over. "*" means all directories. To specify a subset, use a list like {"lazy", "mason"} where "lazy", "mason" are subdirectories
        -- under path specified in `base`.
        compression = {
          enabled = false, -- Should compression be enabled or not
          additional_opts = {} -- Any additional options that should be used for compression. Any argument that is passed to `tar` (for compression) can be passed here as separate elements.
        },
      },
      -- What to copy to remote's Neovim data directory
      data = {
        base = vim.fn.stdpath("data"),
        dirs = {},
        compression = {
          enabled = true,
        },
      },
      -- What to copy to remote's Neovim cache directory
      cache = {
        base = vim.fn.stdpath("cache"),
        dirs = {},
        compression = {
          enabled = true,
        },
      },
      -- What to copy to remote's Neovim state directory
      state = {
        base = vim.fn.stdpath("state"),
        dirs = {},
        compression = {
          enabled = true,
        },
      },
    },
  },

-- You can supply your own callback that should be called to create the local client. The default implementation
  -- starts a terminal remote UI with `nvim --remote-ui`.
  -- Two arguments are passed to the callback:
  -- port: Local port at which the remote server is available
  -- workspace_config: Workspace configuration for the host. For all the properties available, see https://github.com/amitds1997/remote-nvim.nvim/blob/main/lua/remote-nvim/providers/provider.lua#L4
  -- A sample implementation using WezTerm tab is at: https://github.com/amitds1997/remote-nvim.nvim/wiki/Configuration-recipes
  client_callback = function(port, _)
    require("remote-nvim.ui").float_term(("nvim --server localhost:%s --remote-ui"):format(port), function(exit_code)
      if exit_code ~= 0 then
        vim.notify(("Local client failed with exit code %s"):format(exit_code), vim.log.levels.ERROR)
      end
    end)
  end,

-- Plugin log related configuration [PREFER NOT TO CHANGE THIS]
  log = {
    -- Where is the log file
    filepath = utils.path_join(utils.is_windows, vim.fn.stdpath("state"), ("%s.log"):format(constants.PLUGIN_NAME)),
    -- Level of logging
    level = "info",
    -- At what size, should we truncate the logs
    max_size = 1024 * 1024 * 2, -- 2MB
  },
}
```

</details>

## 🎥 Demos

> [!TIP]
>
> By default, this plugin launches your remote neovim client in a popup window.
> This _mostly_ works fine. For a better experience though, it is recommended
> that you add a custom callback to launch your Neovim client [in a separate
> tab/window for your terminal](https://github.com/amitds1997/remote-nvim.nvim/wiki/Configuration-recipes)
> or [GUI app](https://github.com/amitds1997/remote-nvim.nvim/issues/118#issuecomment-2100529883).

<details>
<summary>How to connect to saved host using SSH config file</summary>

[Remote with SSH
config file](https://github.com/amitds1997/remote-nvim.nvim/assets/29333147/6cd2f3fc-3dcc-482f-a6ae-373084d36ca5)

</details>

<details>
<summary>How to connect to SSH server with password based auth</summary>

[Remote with
password](https://github.com/amitds1997/remote-nvim.nvim/assets/29333147/be9bfc0c-6a7c-4304-a68d-3b75256afea6)

</details>

<details>
<summary>Launch current `.devcontainer` based project in a devcontainer</summary>

[Launch a local .devcontainer project in a
devcontainer](https://github.com/amitds1997/remote-nvim.nvim/assets/29333147/1a274a93-f1ab-4369-90e6-bbe0efcd71c9)

</details>

<details>
<summary>Launch a docker image as a devcontainer</summary>

[Launch docker image as a
devcontainer](https://github.com/amitds1997/remote-nvim.nvim/assets/29333147/98352663-a145-4948-93f7-70d5403c7ef4)

</details>

<details>
<summary>Attach to a running docker container</summary>

[Attach to a running docker
container](https://github.com/amitds1997/remote-nvim.nvim/assets/29333147/4fda15fa-e2ca-45b1-811b-c87472278835)

</details>

<details>
<summary>Launch a remote repo as a devcontainer</summary>

[Launch git repo in a
devcontainer](https://github.com/amitds1997/remote-nvim.nvim/assets/29333147/5d4b294e-7269-4bbb-a168-cd9dcdb6686e)

</details>

<details>
<summary>Launch any git branch in a devcontainer</summary>

[Launch git branch in a
devcontainer](https://github.com/amitds1997/remote-nvim.nvim/assets/29333147/ba6c0db9-f3c0-403a-b62d-b1e5ac7762ef)

</details>

<details>
<summary>Launch any git commit in a devcontainer</summary>

[Launch git commit in a
devcontainer](https://github.com/amitds1997/remote-nvim.nvim/assets/29333147/926b076b-45ec-4603-bd27-13dc270c7e51)

</details>
<details>
<summary>Launch PR in a devcontainer</summary>

[Launch any git repo-based PR in a
devcontainer](https://github.com/amitds1997/remote-nvim.nvim/assets/29333147/29aaa26b-697b-4ee1-962d-75cc70299ae5)

</details>

<details>
<summary>Connect to any existing devpod workspace</summary>

[Launch any existing devpod workspace inside a
devcontainer](https://github.com/amitds1997/remote-nvim.nvim/assets/29333147/a43f932e-264a-4819-ab54-83348a82a5b1)

</details>

<details>
<summary>Stop running Neovim server</summary>

This continues from the _How to connect to saved host using SSH config file_ demo above.

[Stop running remote Neovim
session](https://github.com/amitds1997/remote-nvim.nvim/assets/29333147/b2603583-c80a-41e5-b94e-9e80c56d557c)

Alternatively, just exit from the Neovim instance using which you launched the server.

</details>

<details>
<summary>Get information about any Remote Neovim launched session</summary>

[Get information about Remote
Neovim session](https://github.com/amitds1997/remote-nvim.nvim/assets/29333147/ceb24934-a132-4d0c-8172-7ba58679c467)

</details>

<details>
<summary>Delete this plugin's created resources from the remote machine</summary>

This deletes the resources created during the _How to connect to saved host using SSH config file_ demo above.

[Delete all resources created by
this plugin](https://github.com/amitds1997/remote-nvim.nvim/assets/29333147/3896dda5-b73f-47e4-8e56-72f661e1a623)

</details>

<details>
<summary>Delete saved configuration about a remote host</summary>

We disabled connectivity to the host we connected to in _How to connect to SSH server with password based auth_
to replicate this scenario.

[Delete saved remote
configuration](https://github.com/amitds1997/remote-nvim.nvim/assets/29333147/a7f2a9b0-3d04-4c7b-9cea-4fa2a2efdf15)

</details>

<details>
<summary>Youtube video going over an older version of the plugin</summary>

[![Tutorial for remote-nvim.nvim plugin v0.0.1](http://img.youtube.com/vi/5qbDq1lGEx4/0.jpg)
](http://www.youtube.com/watch?v=5qbDq1lGEx4 "Remote development on Neovim using
remote-nvim.nvim")

</details>

## 🤖 Available commands

| Command                 | What does it do?                                                                                                                                            |
| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `:RemoteStart`          | Connect to a remote instance. If remote neovim server is already running, allows users to launch local client?                                              |
| `:RemoteStop`           | Stop running Neovim server and close session                                                                                                                |
| `:RemoteInfo`           | Get information and Runtime diagnostics about any sessions created in the current Neovim run. Opens up the Progress Viewer.                                 |
| `:RemoteCleanup`        | Delete workspace and/or entire remote neovim setup from the remote instance. Also, cleanups the configuration for the remote resource.                      |
| `:RemoteConfigDel`      | Delete record of remote instance that no longer exists from saved session records. Prefer `:RemoteCleanup` if you can still connect to the remote instance. |
| `:RemoteLog`            | Open the plugin log file. This is most useful when debugging. `:RemoteInfo` should surface all information needed. If not, open an issue.                   |
| `:RemoteClipboardCheck` | Diagnose clipboard setup for an active remote session, including OSC 52 availability, provider state, and attached UI count.                                |
| `:RemoteDetach`         | Detach an active SSH session while leaving the remote Neovim server running.                                                                                |
| `:RemoteReattach`       | Reconnect to a detached SSH session after validating the remote server.                                                                                     |
| `:RemoteKillDetached`   | Kill or clear a detached SSH session record.                                                                                                                |

For demos about the commands, see the [demos](#-demos) section.

### SSH workspace working directory

When creating an SSH workspace, `remote-nvim` asks for an optional remote working directory. If provided, the value is
saved in the workspace record and reused on later `:RemoteStart` runs. The remote headless Neovim server is launched
with that directory as its current directory, which helps tools like language servers discover project files such as
`go.mod`.

Leave the prompt blank to keep the remote shell's default startup directory, usually `$HOME`.

### Automatic reconnect

`remote.reconnect` can automatically relaunch the current workspace when the remote Neovim SSH job exits unexpectedly,
for example after a transient network drop. It does not trigger when you explicitly stop the session with
`:RemoteStop`.

```lua
require("remote-nvim").setup({
  remote = {
    reconnect = {
      enabled = true,
      max_attempts = 5,
      backoff_ms = 2000,
    },
  },
})
```

This is a best-effort reconnect: the plugin relaunches the workspace and local client. It does not yet keep the remote
Neovim server alive independently from the SSH tunnel.

### Detached SSH sessions

SSH sessions can be detached explicitly with `:RemoteDetach` after enabling `remote.detach.enabled`. Detach stops the
local forwarding job and client, but keeps the remote headless Neovim server running. Use `:RemoteReattach` to validate
the saved PID and remote port, recreate the local tunnel, and launch the local client again.

Detached sessions are stored under `stdpath("data")/remote-nvim/detached.json`. If validation fails, the record is
marked stale. Use `:RemoteKillDetached` to kill a detached server or clear a stale record.

Detach is SSH-only in this release. Devpod, Docker image, and Docker container sessions report a clear
unsupported-provider warning.

### Local clipboard in the terminal client

The default local client is `nvim --remote-ui`, even when `:RemoteStart` is run from Neovide. This keeps the terminal UI
behavior for scrolling, fonts, and rendering while still allowing remote yanks to reach the local clipboard.

To make that work, the remote server installs a small startup hook that uses a copy-only OSC 52 clipboard provider for
terminal UI clients. This means yanking with `yy`, visual mode `y`, or any operation that writes to the `+` register can
update the local clipboard without requiring clipboard tools on the remote host. Paste falls back to the most recent
cached yank instead of querying the terminal clipboard, since many terminals do not support OSC 52 reads. The startup hook
runs during startup and UI attach, then retries a few times so delayed user configuration and lazy-loaded plugins do not
accidentally leave the remote server without the OSC 52 provider.

When the default client is launched from Neovide, `remote-nvim` also reloads the local Neovide clipboard provider before
opening the nested terminal UI. This lets OSC 52 writes from the remote UI flow through the local terminal buffer into
Neovide's system clipboard bridge.

For terminal clients without an existing local clipboard provider, `remote-nvim` installs a local OSC 52 fallback before
opening the nested terminal UI. This lets Neovim's terminal buffer handle OSC 52 writes from the remote UI and forward
them to terminals such as Warp that support OSC 52 clipboard writes.

If you override `client_callback` to launch a GUI client such as Neovide, the startup hook preserves Neovide's clipboard
provider when it is available.

#### Clipboard troubleshooting

After connecting to a remote session, run `:RemoteClipboardCheck`. If multiple sessions are active, choose one from the
picker or pass the host ID directly:

```vim
:RemoteClipboardCheck my-host
```

A healthy terminal-client setup should report:

- `clipboard option` includes `unnamedplus`
- `clipboard provider` is `remote-nvim OSC 52` or a preserved Neovide provider
- `osc52 available` is `true`
- `copy +/*` reports `function/function`
- `attached UIs` is at least `1`

To verify manually, yank text in the remote UI with `yy` or `"+y`. The text should appear in your local system clipboard.
If diagnostics look healthy but the clipboard does not update, check whether your terminal or terminal multiplexer allows
OSC 52 clipboard writes. In tmux, for example, enable clipboard forwarding with:

```tmux
set -g set-clipboard on
```

If `:RemoteClipboardCheck` reports missing copy functions, missing OSC 52 support, or no attached UIs, restart the remote
session so the startup hook can run again and check `:RemoteLog` for setup errors.

### Faster repeated startup

On repeated `:RemoteStart` runs, `remote-nvim` checks whether the selected remote Neovim binary is already installed and
runnable. If it is, the plugin skips the chmod/install script path and goes straight to launching the remote server.
Script checksum checks and configured Neovim config sync still run, so fresh hosts and local config changes continue to
work.

## 🥨 Integration with statusline

The plugin sets the variable `vim.g.remote_neovim_host` to `true` on the remote Neovim instance. This can be used to add
useful information regarding the remote system to your statusline.

Here's an example about adding a component in [lualine.nvim](https://github.com/nvim-lualine/lualine.nvim) to show the
remote hostname when connected to a remote instance.

```lua
lualine_b = {
    ..., -- other components
    {
        function()
        return vim.g.remote_neovim_host and ("Remote: %s"):format(vim.uv.os_gethostname()) or ""
        end,
        padding = { right = 1, left = 1 },
        separator = { left = "", right = "" },
    },
    ..., -- other componenents
}
```

## 📴 Offline mode

There are two types of offline modes available:

1. Offline on remote
2. Offline on remote and local machine

The plugin connects to [neovim/neovim](https://github.com/neovim/neovim) repo on GitHub twice. First time, it tries to
fetch the latest releases available for Neovim that can be installed to the remote. The second time, on the
remote machine, it connects to download the Neovim release.

### Offline on remote

On enabling this, Neovim release will be downloaded locally and then copied over to the remote. Plugin would
connect to GitHub once to get the list of Neovim versions available. To enable this,

```lua
require("remote-nvim").setup({
  -- Add your other configuration parameters as usual
  offline_mode = {
    enabled = true,
    no_github = false,
  },
})
```

### Offline on remote and local machine

On enabling this, GitHub will not be connected with at all. This is useful for scenarions when you face connection
issues with GitHub. _**This is an advanced scenario so make sure that you actually need it**_.

It assumes that you already have Neovim releases available locally along with their checksum files. Note that, _release
names are expected to follow a certain pattern._ So, please use the provided script to download releases and drop them
in the cache directory where the plugin would read from. If no releases are available, the plugin would not be able to
proceed further.

**Steps for downloading releases:** This command is run from the plugin's root. You can run it from anywhere as long as
you have the correct path to the script. Adjust script path as per where the plugin gets installed on your system.
Alternatively, you can also clone the repo at a separate location and run this script from inside the cloned repo.

```bash
./scripts/neovim_download.sh -v <version> -d <cache-dir> -o <os-type> -a <arch-type> -t <release-type>

# <version> can be stable, nightly or any Neovim release provided like v0.9.4
# <cache-dir> is the path in which the Neovim release and it's checksum should be downloaded. This should be same as the cache_dir plugin configuration value else it won't be
# detected by the plugin. See configuration below.
# <os-type> specifies which OS's binaries should be downloaded. Supported values are "Linux" and "macOS"
# <arch-type> is the host's architecture. Can be `x86_64` or `arm64`
# <release-type> is type of release to download. Can be `binary` or `source`
```

To enable this,

```lua
require("remote-nvim").setup({
 -- Add your other configuration parameters as usual
 offline_mode = {
 enabled = true,
 no_github = true,
 -- Add this only if you want to change the path where the Neovim releases are downloaded/located.
 -- Default location is the output of :lua= vim.fn.stdpath("cache") .. "/remote-nvim.nvim/version_cache"
 -- cache_dir = <custom-path>,
 },
})
```

#### Copying additional directories to remote neovim

Above process would prevent the plugin (remote-nvim.nvim) from connecting to GitHub, but nothing is stopping the
plugins defined in your configuration from connecting to the internet. To prevent this, you can copy your other
Neovim directories onto the remote to prevent at least your plugin manager from doing so since all your dependencies
would already be in their right locations. Note: _some plugins such as nvim-treesitter might still connect to the
internet and there is nothing this plugin can do to restrict that (and neither does this plugin aim to do that)_.
In such cases, you have 3 alternatives:

1. Turn off the plugin
2. Make configuration changes (if possible) for it to not connect to internet
3. Find an alternative to that plugin

To turn off the plugin only on remote instances, one simple condition would be to check if Neovim is running in
`headless` mode (That's how this plugin launches your remote neovim instance).

With that out of the way, let's focus on how you can copy additional Neovim directories onto remote.

```lua
require("remote-nvim").setup({
  remote = {
    copy_dirs = {
      data = {
        base = vim.fn.stdpath("data"), -- Path from where data has to be copied. You can choose to copy entire path or subdirectories inside using `dirs`
        dirs = { "lazy" }, -- Directories inside `base` to copy over. If this is set to string "*"; it means entire `base` should be copied over
        compression = {
          enabled = true, -- Should data be compressed before uploading
          additional_opts = { "--exclude-vcs" }, -- Any arguments that can be passed to `tar` for compression can be specified here to improve your compression
        },
      },
      -- cache = {
      --   base = vim.fn.stdpath("cache"),
      --   dirs = {},
      --   compression = {
      --     enabled = true,
      --   },
      -- },
      -- state = {
      --   base = vim.fn.stdpath("state"),
      --   dirs = {},
      --   compression = {
      --     enabled = true,
      --   },
      -- },
    },
  },
})
```

The above configuration indicates that the `lazy` directory inside your Neovim `data` directory should be copied over
onto the remote in it's `data` directory. You can similarly specify what should be copied inside the `data`, `state`,
`cache` or `config` directory on remote.

If specified directories are going to contain a lot of data, it's _highly recommended_ to enable compression when
uploading by setting `compression.enabled` to `true` for those particular uploads.

## ⚠️ Caveats

- Launched neovim server is bound to the Neovim instance from which it is launched. If you close the instance,
 the remote Neovim server will also get closed. This has been done to ensure proper cleanup of launched sessions
 and prevent orphan Neovim servers.
- The current implementation launches a headless server on the remote machine and then launches a TUI to connect
 to it. This means that if you quit the TUI using regular operations, the server also gets closed. If you just want
 to close the TUI, that is currently not possible. You can read more in [this Neovim
 discussion](https://github.com/neovim/neovim/issues/23093).
- Neovim versions `< v0.9.2` are incompatible with versions `>= v0.9.2` due to a breaking UI change introduced in
 `v0.9.2`. For more information, read the [release notes for
 v0.9.2](https://github.com/neovim/neovim/releases/tag/v0.9.2).

## FAQ

### Why can remote tools be missing even though they are configured in my shell?

`remote-nvim` runs commands on the remote host over SSH and launches a headless Neovim server from that remote
command environment. This is usually a non-interactive, non-login shell, so interactive startup files such as
`~/.zshrc` are not guaranteed to be loaded.

Put binary `PATH` setup that remote Neovim needs in a startup file that is loaded for non-interactive shells. For
example, if `zsh` is your remote login shell and `fzf` is installed under `~/.fzf/bin`, put only the path setup in
`~/.zshenv`:

```sh
export PATH="$HOME/.fzf/bin:$PATH"
```

Keep `fzf` shell integration, key bindings, and completion setup in `~/.zshrc`. Those parts are for interactive
shell sessions; `remote-nvim` only needs the `fzf` executable to be visible to the remote headless Neovim process.

### Why would I use this plugin instead of the usual ssh + nvim?

This plugins provide some additional nice-to have features on top:

- Automatically installs Neovim on remote
- Does not mess with the global configuration and instead just writes everything to a single directory on remote
- Can copy over your local Neovim configuration to remote
- Allows easy re-connection to past sessions
- Makes it easy to clean up remote machine changes once you are done
- It launches Neovim server on the remote server and connects a UI to it locally.

You can read more in [this Neovim discussion](https://github.com/amitds1997/remote-nvim.nvim/discussions/145)

## 🌟 Credits

**_A big thank you to the amazing Neovim community for Neovim and the plugins! ❤️_**

## 📓 Footnotes

[^1]: _Ensure you have [devpod](https://devpod.sh/docs/getting-started/install#optional-install-devpod-cli) >= 0.5.0 installed for this to work_

[^2]: _Supports building from source or using already installed Neovim on remote host_

remote-nvim.nvim

Owner Repos

File Explorer

# Use via CDN

Was this content helpful?

Recent Feedback

remote-nvim.nvim

Owner Repos

File Explorer

# Use via CDN

Was this content helpful?

Recent Feedback

Download README