Developing on Remote Machines using SSH and Visual Studio Code
the visual studio code remote – ssh extension allows you to open a remote folder on any remote machine, virtual machine, or container with an ssh server running and take full advantage of vs code’s feature set . once connected to a server, you can interact with files and folders anywhere on the remote file system.
The source code does not need to be on your local machine to get these benefits, as the extension executes commands and other extensions directly on the remote machine.
This enables vs code to provide a local quality development experience, including full intelligence (completions), code navigation, and debugging, regardless of where your code is hosted.
starting
note: After reviewing this topic, you can start with the introductory ssh tutorial.
system requirements
local: an openssh compatible ssh client must also be installed.
remote ssh host: an ssh server running on:
- x86_64 debian 8+, ubuntu 16.04+, centos/rhel 7+.
- armv7l (aarch32) raspberry pi os (formerly called raspbian) stretch/9+ (32-bit).
- armv8l (aarch64) ubuntu 18.04+ (64 bit).
- windows 10/server 2016/2019 (1803+) using openssh official server.
- macos 10.14+ (mojave) ssh hosts with remote login enabled.
- 1gb ram required for remote hosts, but at least 2gb ram and 2 core cpu recommended.
Other glibc based linux distributions for x86_64, armv7l (aarch32), and armv8l (aarch64) should work if they have the necessary prerequisites. see the remote development with linux article for prerequisites and tips for getting community-supported distributions up and running.
Although support for armv7l (aarch32) and armv8l (aarch64) is available, some extensions installed on these devices may not work due to the use of native x86 code in the extension.
installation
To get started, you need:
-
Install an openssh compatible ssh client if one doesn’t already exist.
Install visual studio code or visual studio code insiders.
Install the remote development extension pack.
ssh server configuration
-
If you don’t have an ssh host configured, follow the instructions for linux, windows 10/server (1803+) or macos ssh host or create a vm in azure.
Optional: If multiple users will be accessing your linux or macos ssh host at the same time, consider enabling remote.ssh: remote server listens on socket in vs code the user settings to improve security.
in the configuration editor:
see the tips and tricks article for more information.
Optional: Even if password-based authentication is supported, we recommend configuring key-based authentication for your host. see the tips and tricks article for more details.
connect to a remote host
To connect to a remote host for the first time, follow these steps:
-
verify that you can connect to the ssh host by running the following command from a terminal/powershell window replacing [email protected] as appropriate.
in vs code, select remote-ssh: connect to host… from the command palette (f1, ⇧⌘p (windows, linux ctrl+shift+p)) and use the same [email protected] as in step 1.
if vs code cannot automatically detect the type of server you are connecting to, you will be prompted to select the type manually.
Once you select a platform, it will be stored in the vs code configuration in the remote.ssh.remoteplatform property so you can change it at any time.
After a moment, vs code will connect to the ssh server and configure itself. vs code will keep you updated with a progress notification and you will be able to see a detailed log on the remote output channel – ssh.
tip: Does the connection hang or fail? see the troubleshooting tips for information on how to resolve common problems.
If you see errors about ssh file permissions, see the section on how to fix ssh file permission errors.
after connecting, you will be in an empty window. you can always check the status bar to see which host you’re connected to.
Clicking the status bar item will bring up a list of remote commands while connected.
You can then open any folder or workspace on the remote machine using file > open… or file > open workspace… just as you would locally!
From here, install any extensions you want to use when connected to the host and start editing!
note: on armv7l / armv8l glibc ssh hosts, some extensions may not work due to x86 compiled native code within the extension.
open a folder on a remote ssh host in a container
If you are using a linux or macos ssh host, you can use the remote container extensions – ssh and remote together to open a folder on your remote host inside a container. you don’t even need to have a docker client installed locally.
to do it:
- Follow the installation steps for the remote containers extension on your remote host.
- Optional: Configure ssh key-based authentication on the server so that you don’t need to enter your password multiple times.
- follow the quick start for remote control: ssh extension to connect to a host and open a folder there.
- use the control remote- containers: reopen container command from command palette (f1, ⇧⌘p (windows, linux ctrl+shift+p)).
the rest of the remote container quickstart applies as-is. you can learn more about the remote containers extension in its documentation. You can also see the Developing on a remote docker host article for other options if this model doesn’t meet your needs.
disconnect from a remote host
To close the connection when you finish editing files on the remote host, select file > close the remote connection to disconnect from the host. the default configuration does not include a keyboard shortcut for this command. you can also just exit the vs code to close the remote connection.
remember hosts and advanced settings
If you have a set of hosts that you use frequently or need to connect to a host using some additional options, you can add them to a local file that follows the ssh configuration file format.
To make setup easier, the plugin can guide you through adding a host without having to manually edit this file.
start by selecting remote-ssh: add new ssh host… from the command palette (f1, ⇧⌘p (windows, linux ctrl+shift+p)) or clicking add new in the remote browser ssh in the activity bar.
then you will be prompted to enter your ssh connection information. you can enter a hostname:
or the full ssh command you would use to connect to the host from the command line:
Finally, you will be prompted to choose a configuration file to use. you can also set the “remote.ssh.configfile” property in your user settings.json file if you want to use a different config file than the ones listed. the extension takes care of the rest!
for example, entering ssh -i ~/.ssh/id_rsa-remote-ssh [email protected] in the input box would produce this entry:
see the tips and tricks for details on how to generate the key shown here. you can manually edit this file with anything that supports the ssh configuration file format, so this is just an example.
From now on, the host will appear in the list of hosts when you select remote-ssh: connect to host… from the command palette (f1, ⇧⌘p (windows, linux ctrl+shift+p)) or in the ssh target section of the remote browser.
The Remote Browser allows you to open a new, empty window on the remote host or directly open a folder you previously opened. expand the host and click the open folder icon next to the folder you want to open on the host.
extension management
vs code runs extensions in one of two places: locally on the UI/client side or remotely on the ssh host. while extensions that affect the vs code UI, such as themes and snippets, are installed locally, most extensions will reside on the ssh host. this ensures you have a smooth experience and allows you to install the necessary extensions for a given workspace to a ssh host from your local machine. this way you can pick up exactly where you left off, from a different machine complete with your extensions.
if you install an extension from the extensions view, it will be automatically installed in the correct location. once installed, you can tell where an extension is installed based on category grouping.
there will be a category for your remote ssh host:
and also a local – installed category:
Note: If you are an extension author and find that your extension is not working properly or is installed in the wrong place, please see remote development support for more details.
local extensions that really need to be run remotely will be grayed out and disabled in the local – installed category. select install to install an extension on your remote host.
You can also install all locally installed extensions on the ssh host by going to the extensions view and selecting install local extensions on ssh: {hostname} using the cloud button to the right of local – installed. this will display a dropdown menu where you can select which locally installed extensions to install on your ssh host.
“always installed” extensions
If there are extensions that you would like to always have installed on any ssh host, you can specify which ones using the remote.ssh.defaultextensions property in settings.json. for example, if you want to install the gitlens and resource monitor extensions, specify their extension ids as follows:
advanced: force an extension to run locally/remote
Extensions are typically designed and tested to run either locally or remotely, but not both. however, if an extension supports it, you can force it to run in a particular location in your settings.json file.
for example, the following configuration will force the docker extension to run locally and the debugger to have the chrome extension run remotely instead of its defaults:
a value of “ui” instead of “workspace” will force the extension to run in the local UI/client. this should generally only be used for testing, unless otherwise stated in the extension’s documentation, as it may break extensions. see the remote development support article for more information.
forward a port / create an ssh tunnel
sometimes during development you may need to access a port on a remote machine that is not publicly exposed. there are two ways to do this using an ssh tunnel that “forwards” the desired remote port to your local machine.
temporarily forward a port
once you are connected to a host, if you want to temporarily forward a new port during the session, select forward a port in the command palette ( f1, ⇧ ⌘p (windows, linux ctrl+shift+p)) or click the forward new port icon in the remote browser after selecting it in the activity bar.
you will be prompted to enter the port you would like to forward and you can give it a name.
a notification will tell you the localhost port to use to access the remote port. for example, if you forwarded an http server listening on port 3000, the notification might tell you that port 4123 was assigned on localhost since 3000 was already in use. then you can connect to this remote http server using http://localhost:4123.
This same information is available in the forwarded ports section of the remote browser if you need to access it later.
if you want vs code to remember any ports you have forwarded, check remote: restore forwarded ports in the configuration editor (⌘, (windows, linux ctrl+,)) or set “remote.restoreforwardedports “: true in settings.json.
change the local port in the tunnel
If you want the tunnel’s local port to be different from the remote server’s, you can change it through the ports forwarded panel.
right-click the tunnel you want to modify and select change local port from the context menu.
always forwarding a port
If you have ports that you always want to forward, you can use the localforward directive in the same ssh configuration file that you use to remember hosts and advanced settings.
for example, if you wanted to forward ports 3000 and 27017, you could update the file like this:
open a terminal on a remote host
opening a terminal on the remote host from vs code is simple. once connected, any terminal windows you open in vs code (terminal > new terminal) will automatically run on the remote host instead of locally.
You can also use the command line of code from this same terminal window to perform a number of operations, such as opening a new file or folder on the remote host. type -help code to see all the options available from the command line.
debug on ssh host
once you’re connected to a remote host, you can use vs code’s debugger the same way you would when running the application locally. for example, if you select a launch configuration in launch.json and start debugging (f5), the app will launch on the remote host and attach the debugger to it.
see the debugging documentation for details on configuring vs code debugging functions in .vscode/launch.json.
ssh host specific configuration
vs code’s local user settings are also reused when connected to an ssh host. while this keeps your user experience consistent, you may want to vary some of these settings between your local machine and each host. Fortunately, once you’ve connected to a host, you can also configure host-specific settings by running the command preferences: open remote config from the command palette (f1, ⇧⌘p (windows, linux ctrl+ shift+p)) or by selecting in the remote tab in the configuration editor. these will override any user settings you have set each time you connect to the host. and workspace settings will override user and remote settings.
working with local tools
the remote extension – ssh does not provide direct support for synchronizing source code or using local tools with content on a remote host. however, there are two ways to do this using common tools that will work with most linux hosts. specifically, you can:
- mount the remote filesystem using sshfs.
- synchronize files to/from the remote host to your local machine using rsync.
sshfs is the most convenient option and does not require any file synchronization. however, performance will be significantly slower than working with vs. code, so it’s best used for single file edits and content upload/download. if you need to use an application that massively reads/writes to many files at once (such as a local source control tool), rsync is a better choice.
known limitations
remote – ssh limitations
- It is recommended to use key-based authentication. passwords and other tokens entered for alternate authentication methods are not saved.
- alpine linux and non-glibc based linux ssh hosts are not supported.
- older (community supported) linux distributions require workarounds to install the necessary prerequisites.
- putty is not supported on windows.
- if you clone a git repository using ssh and your ssh key has a passphrase, it is possible that the extract and synchronization functions of the code vs. hang when running remotely. use an ssh key without a passphrase, clone using https, or run git push from the command line to fix the problem.
- local proxy settings are not reused on the remote host, which may prevent extensions from working unless the proper proxy information is set on the remote host (for example, global environment variables http_proxy or https_proxy with the proper proxy information).
- cannot use containers remotes from a remote ssh connection to a window machine.
- See here for a list of active ssh-related issues.
docker extension limitations
If you’re using the docker or kubernetes extension in a remote ssh window, you won’t be able to use the right-click append vs code to container option. this will only work if you are using it from your local machine.
extension limitations
many extensions will work on remote ssh hosts without modification. however, in some cases certain features may require changes. If you run into an extension problem, there is a summary of common problems and solutions that you can mention to the extension author when reporting the problem.
Also, some extensions installed on armv7l (aarch322) / armv8l (aarch64) devices may not work due to native modules or runtimes in the extension that only support x86_64. in these cases, extensions would have to choose to support these platforms by compiling/including binaries for armv7l/armv8l.
common questions
how do I set up an ssh client on…?
see Installing a compatible ssh client for more details.
how do I set up an ssh server in…?
see Installing a compatible ssh server for details on setting up an ssh server for your host.
can i login to my ssh server with additional authentication mechanism like password?
yes, you will be prompted to enter your token or password automatically. however, passwords are not saved, so using key-based authentication is often more convenient.
how do I fix ssh errors about “wrong permissions”?
see ssh file permissions bug fix for details on how to resolve these types of bugs.
what linux packages/libraries should be installed on remote ssh hosts?
Most Linux distributions will not require additional dependency installation steps. for ssh, linux hosts must have bash (/bin/bash), tar and curl or wget installed and those utilities might be missing from certain stripped down distributions. remote development also requires kernel >= 3.10, glibc >=2.17, libstdc++ >= 3.4.18. only glibc-based distributions are currently supported, so by extension alpine linux is not supported.
see the linux prerequisites for more details.
what are the connectivity requirements for the vs code server when running on a remote machine/virtual machine?
vs code server installation requires your local machine to have https connectivity (port 443) outbound to:
- update.code.visualstudio.com
- vscode.blob.core.windows.net
- *.vo.msecnd.net (azure cdn)
by default, remote ssh will try to download to the remote host, but if you enable remote.ssh.allowlocalserverdownload, the extension will fallback to the code server locally and transfer it remotely once a connection is established.
You can manually install extensions without an internet connection using the command extensions: install from vsix…, but if you use the extensions panel to install extensions, your local machine and the vsix server server code will need outgoing https access (port 443) to:
- marketplace.visualstudio.com
- *.vo.msecnd.net (azure cdn)
- *.gallerycdn.vsassets.io (azure cdn)
Finally, some extensions (like c#) download child dependencies from download.microsoft.com or download.visualstudio.microsoft.com. others (such as visual studio live share) may have additional connectivity requirements. see the extension’s documentation for details if you run into problems.
all other communication between the server and the vs code client is done through the secure and authenticated ssh tunnel.
can i use local tools on source code located on remote ssh host?
yes. normally this is done using sshfs or using rsync to get a copy of the files on your local machine. sshfs mounts the remote file system, it’s great for scenarios where you need to edit individual files or browse the source tree and doesn’t require a sync step to use. however, it’s not ideal for using something like a source control tool that manages files in bulk. in this case the rsync approach is better as you get a full copy of the remote source code on your local machine. see tips and tricks for details.
can I use the vs code when I only have access to the sftp/ftp file system on my remote host (no shell access)?
Some cloud platforms only provide remote file system access for developers instead of direct shell access. vs code’s remote development was not designed with this use case in mind as it negates the performance and user experience benefits.
however, this use case can usually be handled by combining extensions like sftp with remote debugging capabilities for node.js, python, c# or others.
As an author of an extension, what should I do?
The vs code extension api abstracts away the local/remote details, so most extensions will work without modification. however, the given extensions can use any node or runtime modules they want, there are situations where adjustments may be needed. We recommend that you test your extension to make sure no updates are required. see remote development support for more information.
questions or comments
- see tips and tricks or the FAQ.
- search on stack overflow.
- add a feature request or report a problem.
- contribute to our documentation or to the vs code itself.
- see our contribution guide for more details.
-
-
