Remote SSH allows you to use Visual Studio Code as a full-featured remote development environment by connecting to any machine with an SSH server. This setup lets you edit code, debug applications, and manage terminal sessions on a remote Linux or Windows host while enjoying the familiar local interface. The process installs a lightweight VS Code Server component directly onto the target machine, enabling seamless integration without requiring local installation of all development tools.
Prerequisites for Remote Connection
Before establishing a connection, ensure that your remote machine meets the basic requirements. The target system must be running an SSH server and be accessible from your local network. For Linux systems, this typically means having OpenSSH installed and running. Windows 10 and 11 can act as hosts if the OpenSSH Server feature is enabled in Settings. macOS also supports SSH connections out of the box.
Your local computer needs Visual Studio Code installed along with the official "Remote - SSH" extension. This extension, published by Microsoft, handles the communication between your local editor and the remote server. It manages the secure tunneling and file synchronization automatically. You do not need to install Node.js or any other runtime on the remote machine manually; the extension bundle includes everything needed for the server component.
Installing the Remote - SSH Extension
Open Visual Studio Code on your local machine. Navigate to the Extensions view by clicking the square icon in the sidebar or using the keyboard shortcut
Ctrl+Shift+X. Search for "Remote - SSH" in the marketplace. Click the install button next to the extension published by Microsoft. Once installed, the command palette will gain access to new remote commands.
After installation, click the green icon in the bottom-left corner of the window status bar. Select "Connect to Host" from the menu. You can choose to add a new SSH target or connect to one already configured. If you are connecting for the first time, select "Add New SSH Host." Enter the connection string in the format
ssh username@hostname. Replace
username with your account name on the remote machine and
hostname with the IP address or domain name.
Configuring SSH Connections
When you enter the SSH string, VS Code saves it to your local SSH configuration file. This file is located at
~/.ssh/config on Linux and macOS, or
%USERPROFILE%\.ssh\config on Windows. You can edit this file directly to add aliases, port numbers, or identity files. For example, you might define an alias like
myserver to represent
ssh [email protected] -p 2222.
To connect, simply type the alias or the full connection string into the command palette again. VS Code will prompt you for your password or use your SSH keys for authentication. If you have multiple keys, ensure your SSH agent has them loaded. The first connection may take a moment as it establishes the secure channel and prepares the environment.
Understanding the VS Code Server
A common misconception is that the remote machine requires a specific version of Node.js or other heavy dependencies. This is incorrect. When you first connect, VS Code automatically downloads and installs a small server component into a hidden directory on the remote host, typically
~/.vscode-server. This server is bundled with its own runtime environment, ensuring compatibility regardless of the remote OS's installed software.
The server communicates over the SSH tunnel you established. It handles file watching, language services, and debugging ports. Because it runs on the remote machine, all CPU-intensive tasks like indexation and linting happen there, leaving your local machine free for other work. This architecture ensures that the performance depends on the remote server's capabilities, not your local hardware.
If you encounter issues with the server installation, you can clean up the remote installation by deleting the
~/.vscode-server directory and reconnecting. This forces VS Code to reinstall a fresh copy of the server. Always ensure that your firewall allows SSH traffic on the default port 22 or your custom port.
For more advanced file management, such as moving or renaming files within the remote workspace, you can use standard Git operations integrated into the source control panel. See
Move/Rename File in VS Code with Git for details on handling version control alongside remote edits.
Troubleshooting Common Issues
If the connection fails, check your SSH credentials and network connectivity. Ensure that the remote SSH service is active. On Linux, run
systemctl status sshd to verify. If the connection succeeds but the editor feels slow, check the remote server's resource usage. High CPU or memory usage can delay the server startup.
Another issue is permission errors when accessing certain directories. Ensure your user has read and write access to the project folder. If you are using SSH keys, verify that the private key permissions are correct (usually
600). You can also configure VS Code to use a specific key by adding
IdentityFile ~/.ssh/mykey to your SSH config.
Sometimes, the remote server may become unresponsive. Restarting the VS Code Server process usually resolves this. You can do this by opening the command palette and selecting "Remote-SSH: Kill VS Code Server on Host." Then reconnect. This clears any stuck processes without needing to reboot the entire machine.
Frequently Asked Questions
Do I need to install Node.js on the remote server?
No, the Remote - SSH extension bundles its own runtime environment. The VS Code Server installed on the remote host includes all necessary dependencies, so you do not need to manually install Node.js or other runtimes on the target machine.
How can I switch between different remote projects?
You can save multiple SSH configurations in your local SSH config file. Use the "Connect to Host" command in the status bar to select from your saved targets. Each connection opens a separate window, allowing you to work on multiple remote machines simultaneously.
Why is my remote connection slow?
Latency often depends on network speed and the remote server's performance. Ensure you are using a stable connection. If the editor feels sluggish, check the remote server's CPU and memory usage via the terminal. Closing unnecessary extensions locally can also improve responsiveness.
Can I use this method on Windows remote hosts?
Yes, provided you have enabled the OpenSSH Server feature in Windows settings. The VS Code Server component works seamlessly on Windows, allowing you to edit code, debug, and use terminals just as you would on Linux.
What happens if the remote server crashes?
VS Code detects disconnections and attempts to reconnect automatically. If the server fails to restart, you can manually kill the process on the remote host and reconnect. This triggers a fresh installation of the server component, restoring normal functionality.