Editing files stored on a remote server doesn’t need to be a clunky mess of shell commands and basic text editors. Visual Studio Code is one of the most popular developer IDEs and an officially supported extension lets you add SSH connections to your workspace.
The Remote – SSH extension can connect to network servers, list their directory structure, and open and edit files. Almost all Visual Studio Code features are available including IntelliSense code completion, built-in debugging, and third-party extensions.
Getting Started
Begin by adding the Remote – SSH extension to your editor. Press Ctrl+Shift+P to open the command palette and type “install”. The extensions sidebar will appear on the left. Search for “remote – ssh” and install the matching extension. It’s published and supported by Microsoft.
Now you need to connect to your SSH server. The extension works with hosts running Ubuntu, Debian, CentOS, RHEL, and Raspbian. Windows servers are supported too, provided Microsoft’s official OpenSSH server is used. macOS hosts need to have the operating system’s Remote Login feature enabled.
Before continuing, make sure you’ve copied your local SSH public key over to your server’s authorized_keys file. VS Code doesn’t fully support password-based authentication; although it will work, you’ll need to re-enter your password each time a command is run.
Press Ctrl+Shift+P to display the Command Palette. Search for “remote explorer” and run the “View: Show Remote Explorer” command to bring up the remote side panel. Select “SSH Targets” from the dropdown at the top if it’s not already selected.
Hover over the “SSH Targets” heading in the side panel. Click the plus button to create a new connection. A popup will appear letting you input your server’s details. This should be a complete SSH connection command with the -A flag to enable agent forwarding. This lets you use your local keys when running subsequent SSH commands on the server.
You’ll be prompted to choose an SSH configuration file to write to. You can choose from your default user file, the system settings file, or a custom location. Selecting the default in your home directory is usually the best option if you’re unsure.
Your new host will be added to the Remote Explorer sidebar. Click the folder icon next to its name to open a connection in a new Visual Studio Code window. First run setup may take a few moments while Visual Studio configures the remote host and enables its server component.
Using Remote Connections
After the setup completes, you’ll find yourself in a regular Visual Studio Code window that runs operations against your selected host. Click the “Open Folder” button in the top-left of the sidebar to find a directory on your server. You may be prompted to acknowledge a Workspace Trust prompt; if so, click “yes” to mark the directory as trusted and enable all editor features.
Now you’ll see the server-side directory show up in VS Code’s regular Explorer pane. You can open files, view their contents, and edit them using the familiar workflow. If you’re working in a Git repository, you can use the built-in source control features to stage and commit changes as usual.
Directories with .vscode files enable features such as builds and debugging. VS Code can execute the contents of remote directories, giving you a complete development experience. Press F5 to start your app if a build system is defined. You can set breakpoints and step through your code in the same way as local projects.
The VS Code Terminal panel at the bottom of your window will connect to the selected host too. You can use this to execute commands on your remote server.
Once you’ve opened a directory once, it will show up in the Remote Explorer sidebar in the future. Click its name below the SSH host to launch a new VS Code window straight to that remote directory.
How Does It Work?
The remote capabilities work by installing a VS Code server component onto your remote machine. This happens automatically the first time you connect. The server monitors the filesystem, applies changes, and launches processes requested by the editor.
The server is necessary so VS Code has full filesystem access and the ability to execute code and run debugging on your host. You don’t normally need to interact with the server process as its fully managed by your editor client. You can restart it from the command palette if you need to.
Extensions in your .vscode file will be installed on the remote host too. This gives them the same no-compromises access to your files so most extensions will work without issues.
When you’re editing within VS Code, you get near-native performance with few overheads. Requests to read and write files are relayed from your VS Code editor window to the server process on the remote host. This interacts with the filesystem to supply requested data and enact any necessary changes.
Unlike other remote-editing extensions, this one focuses on providing a full remote development experience, not just simple file editing. The inclusion of the server component is vital to this approach as the core editor features stay close to the code. They’re decoupled from the editing window you see and interact with.
Configuring the Extension
The extension has several settings you can access via the “Remote-SSH: Settings” command. At the top of the page, you can specify the path to a custom SSH configuration file and add a default connection timeout. This stops Visual Studio hanging for too long when a remote host goes unresponsive. Further down the page, the “Max Reconnection Attempts” setting lets you change Visual Studio’s behavior when a connection fails.
The “Default Extensions” setting allows you to add VS Code extensions that will be installed on all remote SSH hosts. These extensions will be available universally, even if you’ve not added them to your active project’s .vscode file.
The following checkboxes control automatic agent forwarding. These correspond to default SSH client settings in your SSH configuration file.
Further settings let you customize how VS Code exposes and connects to the remote server. You can choose to use a socket instead of a port, pool connections across open windows, and use a custom SSH binary path. These settings are environment-specific; each one’s accompanied by a description of its intended use.
Summary
VS Code’s Remote SSH extension simplifies working with files on remote hosts. You get a first-class development experience without manually synchronizing files between machines.
The workflow enhances the utility of remote development environments. You could configure your toolchain on a single server and let developers remote into it. VS Code is more reliable, performant, and powerful than traditional approaches such as mounting the remote file system locally or using remote access software like VNC.
Besides SSH connections, VS Code also understands Docker containers, the Windows Subsystem for Linux, and GitHub Codespaces. You get all the features of the VS Code editor no matter where your code lives, giving you more flexibility when setting up a new environment.
