nvrh

https://github.com/user-attachments/assets/3cc9be58-ddce-4eaa-97bc-fd6ee8b0b942

nvrh (Neovim Remote Helper) aims to provide a simple way of working with a remote Neovim instance, like you would with VSCode Remote.

Installation

Download the nvrh binary for your platform / architecture from the latest release.

Rename the downloaded file to nvrh and put it somewhere on your PATH for convenience.

Features

• Start Neovim on a remote machine.
• Tunnel the connection between your local and remote machines.
• Start your editor locally, talking to your remote Neovim instance.
• Provide an easy way to tunnel ports.
• Provide an easy way to open URLs on your local machine.

Usage

nvrh client open

This will open a new Neovim instance on your remote machine and tunnel the socket to your local machine.

NAME:
   nvrh client open - Open a remote nvim instance in a local editor
USAGE:    nvrh client open [options] <server> [remote-directory]
CATEGORY:    client
OPTIONS:    --ssh-path string                                Path to SSH binary. 'binary' will use the default system SSH binary. 'internal' will use the internal SSH client. Anything else will be used as the path to the SSH binary [$NVRHCLIENTSSH_PATH] (default: "binary")    --use-ports                                      Use ports instead of sockets. Defaults to true on Windows [$NVRHCLIENTUSE_PORTS] (default: false)    --debug                                          (default: false) [$NVRHCLIENTDEBUG]    --server-env string [ --server-env string ]      Environment variables to set on the remote server [$NVRHCLIENTSERVER_ENV]    --local-editor string [ --local-editor string ]  Local editor to use. {{SOCKETPATH}} will be replaced with the socket path [$NVRHCLIENTLOCALEDITOR] (default: "nvim", "--server", "{{SOCKET_PATH}}", "--remote-ui")    --nvim-cmd nvim [ --nvim-cmd nvim ]              Command to run nvim with. Defaults to nvim [$NVRHCLIENTNVIM_CMD] (default: "nvim")    --ssh-arg string [ --ssh-arg string ]            Additional arguments to pass to the SSH command [$NVRHCLIENTSSH_ARG]    --enable-automap-ports                           Enable automatic port mapping (default: true) [$NVRHCLIENTAUTOMAP_PORTS]    --insecure-direct-connect string                 Opens a public port on the server and connects directly to it. Use 'true' to connect to the server you're already passing    --use-nvim-embed                                 Whether to use --embed instead of --headless (default: false)    --help, -h                                       show help

nvrh client reconnect

Reconnect to an existing nvrh session.

NAME:
   nvrh client reconnect - Reconnect to an existing remote nvim instance
USAGE:    nvrh client reconnect [options] <server> <session-id>
CATEGORY:    client
OPTIONS:    --ssh-path string                                Path to SSH binary. 'binary' will use the default system SSH binary. 'internal' will use the internal SSH client. Anything else will be used as the path to the SSH binary [$NVRHCLIENTSSH_PATH] (default: "binary")    --use-ports                                      Use ports instead of sockets. Defaults to true on Windows [$NVRHCLIENTUSE_PORTS] (default: false)    --debug                                          (default: false) [$NVRHCLIENTDEBUG]    --local-editor string [ --local-editor string ]  Local editor to use. {{SOCKETPATH}} will be replaced with the socket path [$NVRHCLIENTLOCALEDITOR] (default: "nvim", "--server", "{{SOCKET_PATH}}", "--remote-ui")    --ssh-arg string [ --ssh-arg string ]            Additional arguments to pass to the SSH command [$NVRHCLIENTSSH_ARG]    --insecure-direct-connect string                 Opens a public port on the server and connects directly to it. Use 'true' to connect to the server you're already passing    --help, -h                                       show help

nvrh client from-neovim

NAME:
   nvrh client from-neovim - Attach a running local neovim UI to a remote nvim instance via SSH
USAGE:    nvrh client from-neovim [options] <original-server> <server> [remote-directory]
CATEGORY:    client
OPTIONS:    --ssh-path string                            Path to SSH binary. 'binary' will use the default system SSH binary. 'internal' will use the internal SSH client. Anything else will be used as the path to the SSH binary [$NVRHCLIENTSSH_PATH] (default: "binary")    --use-ports                                  Use ports instead of sockets. Defaults to true on Windows [$NVRHCLIENTUSE_PORTS] (default: false)    --debug                                      (default: false) [$NVRHCLIENTDEBUG]    --server-env string [ --server-env string ]  Environment variables to set on the remote server [$NVRHCLIENTSERVER_ENV]    --nvim-cmd nvim [ --nvim-cmd nvim ]          Command to run nvim with. Defaults to nvim [$NVRHCLIENTNVIM_CMD] (default: "nvim")    --ssh-arg string [ --ssh-arg string ]        Additional arguments to pass to the SSH command [$NVRHCLIENTSSH_ARG]    --enable-automap-ports                       Enable automatic port mapping (default: true) [$NVRHCLIENTAUTOMAP_PORTS]    --insecure-direct-connect string             Opens a public port on the server and connects directly to it. Use 'true' to connect to the server you're already passing    --use-nvim-embed                             Whether to use --embed instead of --headless (default: false)    --help, -h                                   show help

Neovim Plugin

If your Neovim UI supports :connect, you can add nvrh to get an :NvrhConnect command that will connect your currently running Neovim UI to a remote.

vim.pack.add({
  {
    src = 'https://github.com/mikew/nvrh',
    version = vim.version.range('*'),
  },
})

Then

:NvrhConnect my-remote-server path/to/project

Launch a different editor

By default nvrh runs nvim, but you can run something else with --local-editor. This example runs nvim-qt:

nvrh client open \
  --local-editor nvim-qt,--nofork,--server,{{SOCKET_PATH}}

Configuration

nvrh can be configured with:

• Environment variables (see --help to see what's supported)
• A configuration file at ~/.config/nvrh/config.yml
• Command line arguments (see --help)

default:
  ssh-path: internal
local-editor:     - nvim-qt     - --nofork     - --server     - "{{SOCKET_PATH}}"
server-env:     - FOO=bar
servers:   my-remote-server:     nvim-cmd:       - /home/linuxbrew/.linuxbrew/bin/nvim
my-remote-server-requiring-ssh:     ssh-path: binary
my-remote-windows-server:     nvim-cmd:       - mise       - exec       - --       - nvim

Tunneling Ports

https://github.com/user-attachments/assets/6de3dfdc-d9bc-4668-be66-cbcf2071fa82

nvrh can tunnel ports between your local and remote machine. This happens either automatically by scanning the output of terminal buffers, or manually with the :NvrhTunnelPort command.

:NvrhTunnelPort 8080
:NvrhTunnelPort 4000

Opening URLs

https://github.com/user-attachments/assets/7a0f8418-828d-4a5f-86cb-026d5d6fd182

nvrh can open URLs on your local machine from your remote Neovim instance. There's a few ways to trigger this:

• vim.ui.open, so gx and :Open https://example.com will work.
• The BROWSER environment variable for process started from Neovim.
• The :NvrhOpenUrl command.

Editing Files

https://github.com/user-attachments/assets/fceb311e-dd80-4ad1-8075-99e4418044fc

nvrh sets the $EDITOR environment variable on the remote machine, so something like git commit will open the file in your current remote session. This also works for UIs that have an "Open in Editor" feature.

Windows Support

https://github.com/user-attachments/assets/e3e542db-4858-40c6-bb90-a6f3fc642087

nvrh supports Windows both locally and remote. If running on Windows, or if nvrh detects the remote machine is Windows --use-ports will default to true.