How to Connect to a Remote Server with SSH in VS Code

You connect VS Code to a remote server by installing the Remote - SSH extension, then running one command from the Command Palette. Once connected, you can open folders, edit files, run terminals, and debug applications on the remote machine as if it were your local computer.

What you need before starting

You need three things:

• A local SSH client. macOS and Linux include OpenSSH by default. On Windows 10/11, OpenSSH is included as an optional feature. Verify it by running the ssh command in a terminal.
• A remote server with an SSH server running. The remote machine must have an SSH server installed and accessible. Linux servers typically have OpenSSH preinstalled. For Windows Server, install the official OpenSSH Server. On macOS, enable Remote Login in System Settings, under General > Sharing.
• VS Code with the Remote - SSH extension, published by Microsoft with extension ID ms-vscode-remote.remote-ssh.

The remote host must meet the current Remote - SSH system requirements. Alpine Linux and other non-glibc Linux SSH hosts are not supported.

Step 1: Test your SSH connection outside VS Code

Before using VS Code, confirm that SSH works from your terminal:

bash

ssh user@your-server-address

Replace the username and server address with your actual values. On a first connection, compare the displayed host fingerprint with a value supplied by the server administrator through a trusted channel before typing yes.

If the connection fails, check that the SSH server is running on the remote machine and that your firewall allows port 22. Do not proceed until a plain ssh command succeeds.

Step 2: Connect from VS Code

Open the Command Palette with F1, Ctrl+Shift+P on Windows or Linux, or Cmd+Shift+P on macOS. Run:

Remote-SSH: Connect to Host...

Type the same user@hostname you used in step 1 and press Enter.

If VS Code cannot detect the remote operating system, it asks you to select it manually (Linux, Windows, or macOS). Pick the correct platform. VS Code remembers this choice.

A progress notification appears while VS Code installs the VS Code Server on the remote machine. This happens only on the first connection. Future connections are much faster.

When the Status Bar in the bottom-left corner shows SSH: hostname, you are connected.

Step 3: Open a folder on the remote server

Once connected, go to File > Open Folder (or File > Open... on macOS). The file dialog shows the remote server's filesystem, not your local one.

Navigate to the project folder you want to work on and select it. VS Code reloads the window with that folder open on the remote server.

From here, you can:

• Open and edit files with full syntax highlighting and IntelliSense
• Open a terminal (Terminal > New Terminal) that runs on the remote server
• Install extensions that run on the remote host
• Use the debugger with a launch.json configured for the remote environment

Step 4: Save the host for quick reconnection

Typing the full address every time is tedious. Save it to your SSH config file.

Open the Command Palette and run Remote-SSH: Add New SSH Host.... Enter the full SSH command you normally use, such as:

bash

ssh -i ~/.ssh/id_rsa user@myserver.example.com

Choose the SSH configuration file when prompted. VS Code adds the host entry there. The host then appears when you run Remote-SSH: Connect to Host... and in the SSH Targets section of the Remote Explorer.

What runs where

When connected over SSH, your VS Code window splits into two parts:

Extensions you install while connected are placed in the correct location automatically. The Extensions view shows separate categories for Local - Installed and the remote host.

Disconnecting

When you are done, choose File > Close Remote Connection or close the VS Code window. Your files remain on the server, and you can reconnect later.

Troubleshooting

Connection hangs or times out. Verify that the remote server is reachable from your terminal with a plain ssh command. Check that the server's firewall allows port 22.

"Permission denied" or SSH key errors. Confirm that VS Code is using the intended user, host, and private key. If the plain ssh command reports bad key permissions, follow the platform-specific permission guidance in the official Remote - SSH troubleshooting documentation.

Extension does not work on the remote host. Some extensions have native dependencies that only support x86_64. ARM-based servers (like Raspberry Pi) may not run all extensions. Look for an Install in SSH button next to disabled extensions in the Extensions view.

Server does not have the required packages. The remote Linux host needs bash, tar, and either curl or wget. Most distributions include these by default. If missing, install them with your package manager.

Next, learn how to use VS Code with WSL 2 on Windows, create a Dev Container, or forward ports in local and remote development.