Author: Benjamin Wheeler (@benjamin051000)

Visual Studio Code makes development on a remote server incredibly simple. This tutorial goes through the process of connecting Visual Studio Code to a UF-network Linux server for remote development in 5 steps.

Note: In this article, Visual Studio Code may be referred to by its colloquial nickname "VSCode."

Note: This tutorial does not cover X11 forwarding, meaning it will not allow you to run GUI applications on the server. See other wiki articles for connecting to the server.

0. Prerequisites
1. Install VSCode Extensions
2. Add SSH Configuration
3. Connect to the Server
4. Navigate to a Project Folder
5. Install Remote Extensions
6. More Information

• Have Visual Studio Code installed on your computer.
• Optional: If working off-campus (or not on the UF network), UF GatorLink VPN
• Have access to your server via SSH.

VSCode has a Remote Development extension pack by Microsoft that can be used to remote into the server. In the Extensions pane, use the text box to search for either Remote Development or ms-vscode-remote.vscode-remote-extensionpack which will lead you to the exact extension. Install the extension pack.

Note: Only the "Remote - SSH" extension (ms-vscode-remote.remote-ssh) is necessary to remote into the server. However, the Remote Development extension pack also installs two other useful extensions for remote development in Docker containers and WSL instances, which can be useful. If you wish to save a little disk space and startup delay, simply install just the "Remote - SSH" extension.

Next, we will use the extensions to connect to the server. Notice on the left pane, a new "Remote Explorer" icon exists.

In the dropdown at the top of the pane, select "SSH Targets". Hover in the left pane to reveal a ➕ (plus-sign) icon next to the "SSH Targets" title, and press it (see image below). A new window will appear which asks you to enter an ssh command. Enter the following ssh command:

ssh <gatorlink username>@<server hostname>

Replace <gatorlink username> with your gatorlink username (e.g. benjaminwheeler) and the <server hostname> with the hostname of your server.

For example, a valid SSH command would look like: ssh [email protected]

Press Enter/Return, and VSCode will ask which SSH configuration file to update. Choose the file path for your home directory:

• Windows: C:\Users\<username>\.ssh\config
• Linux: /home/<username>/.ssh/config

This saves your SSH configuration to a file so VSCode can remember it later.

After this step, VSCode should prompt you with a popup that states "Host added!" and the Remote Explorer pane should update with a new item with the name of the server you entered.

In the Remote Explorer, hover over the SSH Target you wish to connect to, and an icon to "Connect to Host in a New Window" will appear. Press the icon to connect. A new VSCode window should open up.

As VSCode attempts to connect, it may ask you which type of operating system the Host is. Select Linux. VSCode may also ask for your GatorLink password. If so, enter it and press Enter/Return.

Note: If you get an error while the new window attempts to connect to the server and you are off-campus (or not on a UF network), make sure you have connected to the GatorLink VPN (see above link for tutorial).

You will know the connection was successful if a Terminal pane opens at the bottom of the window and shows a bash prompt that looks like:

[email protected]:~$

Secondly, the bottom left corner of VSCode should read: SSH: <server hostname>, indicating it is connected to a remote host.

At this point, you have successfully connected to the server.

VSCode works almost entirely the same in a remote environment as it does in a local environment. Thus, you can use the Explorer pane on the left to navigate directories and files, edit those files, and use other vscode features in the same way. You can also use the integrated terminal to perform useful tasks, although many of them will not be covered in this tutorial.

While your terminal may be in your home directory (notated by the ~), VSCode most likely is not. To change the folder VSCode is working in, either click File > Open Folder... or Press the top left "Explorer" pane icon and press the Open Folder button in the Explorer pane.

You will be asked to enter the path of the folder. On most UF Linux server, the path to each user's home folder is: /home/UFAD/<gatorlink username>. Type this in and press OK. VSCode will reload into the new folder. You should see the Explorer pane update with folders and files in your personal home directory. Welcome home!

Warning: Please only work in your personal home directory (e.g. /home/UFAD/benjaminwheeler). DO NOT make changes to others' home directories or directories outside your personal home directory! If you are unsure, ask (especially before deleting files).

You are now ready to work on the server! See other wiki pages for various tutorials, including cloning repositories with git, setting up software to use on the server, and more.

Remember the extensions you installed for remote development? Those were installed on your local VSCode instance. You can also install extensions into your remote VSCode (this is because VSCode actually installed a vscode server on your remote server, it's part of the way remote development works).

For example, if you plan on using Python on the server, the Python extension may be helpful to install on the remote instance. Install the Python extension (or search for ms-python.python) (while you are connected to the server) in the same fashion you installed the remote development tools from before. The install button should read Install in SSH: <server hostname>...". Press this button to install the Python extension on the server rather than in on your local VSCode instance.

Note: At this point, you may need to reload the VSCode window by either by clicking the gear icon in the bottom left, pressing Command Palette..., and typing >Developer: Reload Window and pressing Enter. You may also have to Kill your terminal and create a fresh one by pressing the 🗑 (garbage bin) icon in the active terminal and pressing View > Terminal to create a new one.

At this point, two things should change. If you open a Python source file, you should see a Green Play button in the top right. If you see this, the Python extension is working.

For additional instructions and information, visit the Visual Studio Code Official Documentation for Remote Developmen using SSH.