A Windows Guy in a Linux World: VS Code and Remote SSH

Christopher Bisset

Read more posts by this author.

Welcome to the final installment of A Windows Guy in a Linux World blog post series where you’ll learn to use VS Code to connect to a remote SSH host. If you have been following along with the series, by now you should already have all of the tools and knowledge to start remotely managing your Linux machines (including editing files).

Check out the previous posts in this series:

The tools covered previously are useful but they don’t feel Windows-like. The Linux tools may feel foreign and difficult to use compared to a native Windows experience. In this final article of a five-part series, you will learn how to edit files natively on your Windows machine using Visual Studio (VS) Code for a more modern experience.

Prerequisites

To follow along with the examples provided in this post, be sure you have the following:

The Need for a Great Editing Environment

Linux does not have a central registry. Unlike Windows, virtually everything about Linux revolves around configuration files. Every change you make in a GUI, every box you tick in a web interface, every configuration change you make, there’s a file somewhere that reflects that setting.

Because configuration files are so important in Linux, you need a great text editor. Linux has a few good ones including the Midnight Commander text editor (known as mcedit) covered earlier.

The Midnight Commander Commandline Text Editor opening ~/.bashrc
The Midnight Commander Commandline Text Editor opening ~/.bashrc

However, this series is for working on Linux from the perspective of a Windows user. Windows has (arguably) the best text editor on the market. Even better: It’s entirely compatible with the Linux remoting protocol (SSH).

Visual Studio Code – Microsoft’s Preferred Text Editor

Microsoft makes an incredibly powerful text editor: Visual Studio Code. VS Code has taken over just about every other text editor in the Microsoft ecosystem to be the primary way to edit files on Windows. You may already be familiar with Visual Studio Code: it’s covered frequently on this site.

Visual Studio Code is technically an Integrated Development Environment (IDE) as well as a syntax-aware editor. This means you can run shell commands directly inside the editor as well as use it for debugging your scripts.

Not only can you use VS Code to work with files locally, but VS Code also supports remote file-editing over SSH. Remote file-editing means that instead of navigating through the command line via an SSH prompt, you can directly open, explore, and edit files without leaving VS Code!

Installing the SSH Extension in Visual Studio Code

VS Code doesn’t come with SSH support out of the box but using the power of the extension marketplace, you can add this functionality. To do so, you need to install the remote SSH extension.

  1. In VS Code, you should see a sidebar on the left that looks like a block. Click that icon to bring up the Extension Marketplace search box.
The sidebar in Visual Studio Code
The sidebar in Visual Studio Code

2. Type ssh to search for the Remote – SSH extension as shown below. The official Microsoft extension should be the top result.

3. Click the green Install button beside the Remote – SSH extension to begin installing it.

The extension marketplace of VSCode
The extension marketplace of VSCode

Once installed, you should immediately see a new icon in the sidebar called Remote Explorer as shown below.

The Remote Explorer Sidebar
The Remote Explorer Sidebar

At this point, you’re now ready to begin adding your SSH session.

Connecting to a Target Server with SSH in VS Code

Let’s now see how you can connect to your remote Linux machine over SSH and edit some files with VS Code!

  1. Click the Remote Explorer icon you just installed to open the remote explorer panel.

2. Click on the + symbol in the SSH Targets box to add a new SSH server to connect to as shown below.

The SSH Targets Option

3. Input ssh <user>@ip on the prompt on your target Linux machine, as described in the pre-requisites. For the example below the user is homelab and the ip is 172.25.179.190.

Adding an SSH target
Adding an SSH target

4. You should now see a blank prompt come up shown below asking where to save the config data. This is the file describing all of the saved connections, in the event we have multiple Linux devices that we connect to. For this example, you can leave the box blank to save in the default location. Press Enter to save the default location (C:\users\<user profile>\.ssh\config).

Choosing your SSH configuration file
Choosing your SSH configuration file

5. Finally, right-click on the newly created SSH target and click Connect to Host in Current Window. This action will connect to the target over SSH and set up VS Code to work remotely.

Connecting to the SSH target
Connecting to the SSH target

If all went well, you should now be able to start configuring SSH immediately in the next section.

If you are getting stuck at this stage, make sure you actually can SSH to your target computer. The easiest way to test is to open a command window (on Windows 10) and test with ssh <user>@<ip>. If that does not work for you, VSCode will not be able to connect either.

Configuring SSH on Your First Connection

Once you’ve connected to the remote SSH server for the first time, you’ll need to do some initial configuration. As you can see below, VS Code will ask for the type of connection you are making (Linux), and prompt for a password. After a short delay you should see the bottom left corner turn green and say SSH: <your IP>.

Demonstration of the first time connection method
Demonstration of the first time connection method

You’re now all set up and ready to begin working with the remote filesystem!

Opening a Remote Folder and Files

Once you’ve connected for the first time, you can then begin opening files on the remote Linux server over SSH. To do so:

  1. Click on the top-left sidebar called the Explorer pane.

2. Click on the blue Open Folder button to open a remote folder.

3. Next, choose a folder to open. In the example below, we’re referencing the /home/<username> folder.

You may get a prompt to enter your password again when selecting the folder.

Opening a base folder for the explorer sidebar
Opening a base folder for the explorer sidebar

Once you have opened a folder, you should get a visual representation of the remote folder’s contents in the File Explorer panel shown below.

The base folder in the File Explorer panel is referred to as your workspace. The workspace is the folder you opened in the previous step. You can see below that the File Explorer panel now shows the contents of the folder you opened in the last step.

You can now open any file (like the .bashrc file in the screenshot) and VS Code will automatically display it in the main panel, complete with syntax highlighting!

VSCode exploring a remote SSH target
VSCode exploring a remote SSH target

You can technically open the root folder (/) as the workspace, and therefore have access to the entire filesystem (read more on the filing system in the second part of this series). However, VS Code will have issues automatically watching for changes if the target workspace is too large. VSCode will throw a warning, and you may have to manually refresh to see filesystem changes.

Picking a Different Working Folder

What if you open a folder and the files you need to work with are in a different folder? In this case, you can open another “base” folder or even add folders to your workspace.

If you’d like to open a completely separate folder (closing the last one), you can do so by navigating to the File menu, clicking on Open Folder, and choosing your new folder. This action will close VS Code and open a new workspace.

If you’d like to keep the other folder open and add another folder to your workspace, navigate to the File menu again and this time, click on Add Folder to Workspace. From here you can add new folders to the existing workspace.

You can see an explanation of this in the screenshot below.

The different workspace options available
The different workspace options available

Now that you have learned how to connect to a target and open up the explorer window at a folder, lets look at what you can actually do with the file explorer.

Transferring Files Between your Host and Target

VS Code is incredibly powerful, and the explorer pane is useful for more than just browsing and editing remote files. You can also use it to upload and download files directly to your server!

Uploading and downloading files is as simple as a drag and drop. For example, to upload a local file to the remote server:

  1. Navigate to the local folder that contains the file(s) you’d like to upload to the remote server.
  2. Drag the file(s) from the local Windows explorer window to the File Explorer pain in VS Code.

Done!

To download a file:

  1. Navigate to the file(s) you’d like to download from the remote server.
  2. Select the file(s), right-click on them and choose Download.
  3. Pick a place to save them to and voila, you’ve downloaded the file(s).

You can see these steps in action below.

Utilizing the upload feature of VSCode
Utilizing the upload feature of VSCode

You can also cut, copy, drag-and-drop, create new files/folders, and do most of what you expect out of an explorer window. It all happens remotely on the server.

VS Code still has one SSH trick up its sleeve; you can also use VS Code as a standard SSH terminal too!

While connected to an SSH target, click on the View menu and choose Terminal as shown below. VS Code will open a remote SSH session.

The VSCode Terminal Option
The VSCode Terminal Option

You can do everything in the terminal you can do by using SSH directly. That even includes using Midnight Commander, complete with mouse support! You can see Midnight Commander being launched below.

Opening Midnight Commander inside of VS Code
Opening Midnight Commander inside of VS Code

VS Code is using the native windows SSH client under the hood (7.7p1 as of Windows 10 v2009). To get mouse support, you’ll need the Microsoft SSH client (8.1p1 as of this article’s writing). You can read about that more in Part IV of this series.

Editing Protected Configs and Modifying Protected Files

There is one drawback about using VS Code compared to the command line: It will not modify files that require administrative rights to change. These are files that you have to open up with sudo to edit. You can get around this problem in two ways:

sudo is the way to elevate commands in Linux. It is equivalent to UAC in Windows. Rather than opening an elevated command prompt, you run commands with sudo in front.

Just like a normal SSH window, you can also run sudo commands within the VS Code Terminal. VS Code, however, cannot save files that require administrative rights to change. But you can use a tool called Midnight Commander (with sudo to create an explorer window inside the VSCode command line with administrative rights.

In the remote SSH session VS Code terminal, run sudo mc to open the Midnight Commander file management tool. Once in here, navigate to the protected files you’d like to edit and change them as you’d like. You should have no problem doing so.

Actions are shown below.

Using sudo mc inside VSCode for administrative changes
Using sudo mc inside VSCode for administrative changes

The drawback of using sudo mc for administrative changes is fairly large: You are entirely restricted to using the VS Code terminal. This means that most of the graphical features of VS Code such as the explorer pane, and even the main editing window, cannot be used. You are entirely restricted to the terminal window for navigation.

Using the Midnight Commander workaround in VS Code will work but you shouldn’t be editing protected files that often. Using sudo mc should only be required to make a small change or perform a once-off configuration.

If you have files that you are working on regularly, you should be included in the ownership or group for that folder. Doing so negates the need for administrative rights to be required.

Related post: Setting up an SSH Key Exchange Connection with VS Code and SSH

Wrap-Up

Thanks to everyone who stuck through this five-part series. With the configuration of VS Code, you now should be ready to continue your journey through the Linux world.

With the concepts down, you now have a strong foundation to start branching off into the more practical parts of Linux: running servers, learning docker, and setting up your own infrastructure. Stay tuned, and expect lots more Linux related projects to pop up here in the future!

Looks like you're offline!