VS Code Remote-SSH: Develop on Remote Servers Locally

Introduction

Have you ever needed to edit files on a remote Linux server, only to find yourself stuck using vim or nano in a terminal? Or perhaps you've been frustrated by the limitations of editing code over a slow SSH connection with no IntelliSense, no debugging, and no extensions?

VS Code Remote-SSH solves all of this. It lets you open any folder on a remote machine over SSH and work with it as if it were on your local computer — with full IntelliSense, debugging, extensions, and a familiar interface.

In this guide you'll learn:

• How Remote-SSH works under the hood
• Setting up SSH keys for passwordless authentication
• Installing and configuring the Remote-SSH extension
• Connecting to a remote server and opening folders
• Port forwarding for previewing web apps
• Managing multiple remote hosts
• Tips and best practices for productive remote development

How VS Code Remote-SSH Works

When you connect to a remote machine, VS Code installs a small VS Code Server on the remote host. Your local VS Code client communicates with this server over SSH. The server handles:

• File system access
• Language servers (IntelliSense, autocomplete)
• Debugging sessions
• Extension execution

This means language extensions run on the remote machine — where your code actually lives — while the UI runs locally. The result is a snappy, responsive editing experience with full IDE capabilities.

Prerequisites

Before you begin, you need:

• VS Code installed locally (download here)
• A remote server accessible over SSH (Linux/macOS; Windows servers also supported)
• SSH client installed on your local machine
  • macOS/Linux: built-in ssh command
  • Windows: OpenSSH (included in Windows 10+) or Git Bash

Step 1: Set Up SSH Key Authentication

Using SSH keys is more secure and more convenient than password authentication — especially important for frequent remote connections.

Generate an SSH Key Pair

If you don't already have one, generate a key pair on your local machine:

ssh-keygen -t ed25519 -C "your-email@example.com"

Accept the default path (~/.ssh/id_ed25519) or specify a custom one. Add a passphrase for extra security (optional but recommended).

Copy the Public Key to the Remote Server

ssh-copy-id user@your-remote-host

Or manually append the public key:

cat ~/.ssh/id_ed25519.pub | ssh user@your-remote-host "mkdir -p ~/.ssh && cat >> ~/.ssh/authorized_keys"

Test Passwordless Login

ssh user@your-remote-host

You should connect without being prompted for a password.

Step 2: Install the Remote-SSH Extension

1. Open VS Code
2. Go to the Extensions panel (Ctrl+Shift+X / Cmd+Shift+X)
3. Search for "Remote - SSH"
4. Install the extension published by Microsoft

You'll also see Remote - SSH: Editing Configuration Files — install this too for a better config editing experience.

After installation, a new icon appears in the Activity Bar (bottom-left) — the Remote Explorer.

Step 3: Configure SSH Hosts

VS Code reads your SSH connections from the standard ~/.ssh/config file. You can edit it directly or let VS Code manage it.

Open SSH Config

Press Ctrl+Shift+P (or Cmd+Shift+P), type "Remote-SSH: Open SSH Configuration File", and select ~/.ssh/config.

Add a Host Entry

Host my-dev-server
    HostName 192.168.1.100
    User ubuntu
    IdentityFile ~/.ssh/id_ed25519
    Port 22
 
Host work-server
    HostName work.example.com
    User chanh
    IdentityFile ~/.ssh/work_key
    ForwardAgent yes

Key fields explained:

Step 4: Connect to a Remote Host

Method 1: Remote Explorer

1. Click the Remote Explorer icon in the Activity Bar
2. Hover over your host under "SSH Targets"
3. Click the folder icon to open the remote host in a new window
4. Or click the arrow icon to connect in the current window

Method 2: Command Palette

1. Press Ctrl+Shift+P / Cmd+Shift+P
2. Type "Remote-SSH: Connect to Host"
3. Select your configured host from the list
4. VS Code opens a new window connected to the remote

First Connection

On first connection, VS Code will:

1. Download and install VS Code Server on the remote machine
2. Set up the server in ~/.vscode-server/ on the remote
3. Open a new VS Code window — the title bar shows [SSH: hostname] to confirm you're connected

From here, open a folder with File > Open Folder and browse the remote file system.

Step 5: Open a Remote Project

Once connected, navigate to your project:

1. File > Open Folder (or Ctrl+K Ctrl+O)
2. Browse to your project directory on the remote server
3. Click OK

VS Code loads the remote folder. You can now:

• Browse and edit files in the Explorer panel
• Open an integrated terminal (Ctrl+`) — this runs on the remote machine
• Use IntelliSense powered by the remote language server
• Run and debug code on the remote host

The Integrated Terminal

The terminal inside a Remote-SSH window is a real shell session on the remote server. Any command you run executes remotely:

# This runs on the remote machine
ls /home/ubuntu/projects
python3 --version
docker ps

Step 6: Install Extensions on the Remote

Some extensions need to run on the remote server (e.g., language extensions, linters). Others run locally (themes, keybindings).

To install an extension on the remote:

1. Open the Extensions panel while connected
2. Search for the extension
3. Click "Install in SSH: hostname"

Extensions marked with a remote indicator run server-side. VS Code automatically suggests migrating local extensions to the remote when you connect.

Recommended Remote Extensions

Step 7: Port Forwarding

When you run a web app on a remote server (e.g., localhost:3000), you can't access it from your local browser directly. VS Code's port forwarding tunnels the remote port to your local machine automatically.

Automatic Port Forwarding

VS Code detects when a process binds to a port (e.g., npm run dev) and offers to forward it automatically. Click the notification toast to open it in your local browser.

Manual Port Forwarding

1. Open the Ports panel (in the bottom panel area)
2. Click "Forward a Port"
3. Enter the remote port number (e.g., 3000)
4. VS Code assigns a local port (often the same number)
5. Open http://localhost:3000 in your local browser

Persistent Port Forwarding

Add frequently-forwarded ports to your workspace settings:

{
  "remote.SSH.defaultForwardedPorts": [
    { "localPort": 3000, "remotePort": 3000 },
    { "localPort": 5432, "remotePort": 5432 }
  ]
}

Managing Multiple Remote Environments

Organizing Hosts with Labels

Use descriptive Host aliases in your SSH config to keep things organized:

# Development servers
Host dev-api
    HostName 10.0.1.10
    User ubuntu
    IdentityFile ~/.ssh/dev_key
 
Host dev-db
    HostName 10.0.1.11
    User postgres
    IdentityFile ~/.ssh/dev_key
 
# Production (read-only access)
Host prod-web
    HostName prod.example.com
    User deploy
    IdentityFile ~/.ssh/prod_key

Workspace Files for Remote Projects

Save a .code-workspace file to quickly reopen remote folders:

{
  "folders": [
    {
      "uri": "vscode-remote://ssh-remote+my-dev-server/home/ubuntu/api",
      "name": "API Service"
    },
    {
      "uri": "vscode-remote://ssh-remote+my-dev-server/home/ubuntu/frontend",
      "name": "Frontend"
    }
  ]
}

Common Workflows

Workflow 1: Python Development on a GPU Server

# SSH config
Host gpu-server
    HostName gpu.mylab.com
    User researcher
    IdentityFile ~/.ssh/lab_key

1. Connect via Remote-SSH
2. Open your Python project folder
3. Install Python and Jupyter extensions on remote
4. Select the remote Python interpreter / virtual environment
5. Run and debug ML scripts directly on the GPU server
6. Forward Jupyter port (8888) to view notebooks locally

Workflow 2: Docker Development on a VPS

1. Connect to your VPS via Remote-SSH
2. Install the Docker extension on remote
3. Manage containers, images, and volumes from VS Code's Docker panel
4. Open terminals inside containers directly from VS Code
5. Forward application ports for local browser testing

Workflow 3: Git Operations on Remote

When your SSH agent is forwarded (ForwardAgent yes), git operations on the remote use your local SSH keys — no need to copy keys to the server.

# On remote, inside VS Code terminal
git clone git@github.com:yourname/yourrepo.git
git push origin main  # Uses your local SSH key via agent forwarding

Tips & Best Practices

Performance Optimization

Use a faster SSH cipher for high-latency connections:

Host fast-server
    HostName server.example.com
    User ubuntu
    Ciphers aes128-gcm@openssh.com
    Compression yes

Use connection multiplexing to reuse SSH connections:

Host *
    ControlMaster auto
    ControlPath ~/.ssh/sockets/%r@%h-%p
    ControlPersist 600

Create the sockets directory:

mkdir -p ~/.ssh/sockets

Workspace Settings vs User Settings

Settings in .vscode/settings.json inside the remote project override user settings. Use this to configure remote-specific settings:

{
  "python.defaultInterpreterPath": "/home/ubuntu/.venv/bin/python",
  "editor.formatOnSave": true,
  "terminal.integrated.defaultProfile.linux": "bash"
}

Keep VS Code Server Updated

VS Code Server updates automatically when you update VS Code locally. To manually reinstall the server (e.g., after a failed update):

1. Ctrl+Shift+P → "Remote-SSH: Kill VS Code Server on Host"
2. Reconnect — VS Code will reinstall the server

Using Jump Hosts (Bastion Servers)

If your server is behind a bastion/jump host:

Host bastion
    HostName bastion.example.com
    User ubuntu
    IdentityFile ~/.ssh/id_ed25519
 
Host internal-server
    HostName 10.0.0.50
    User ubuntu
    IdentityFile ~/.ssh/id_ed25519
    ProxyJump bastion

VS Code handles the multi-hop SSH connection transparently.

Troubleshooting Common Issues

"Could not establish connection to server"

Causes and fixes:

1. Wrong hostname/IP — verify with ssh user@host in terminal
2. Firewall blocking port 22 — check remote firewall rules
3. SSH service not running — run sudo systemctl status ssh on remote
4. Wrong key — ensure IdentityFile points to the correct private key

"VS Code Server failed to start"

# On remote, remove old server installation and reconnect
rm -rf ~/.vscode-server/

Then reconnect — VS Code will reinstall the server.

Extension Not Available on Remote

Some extensions don't support remote execution. Check the extension's marketplace page for the "Remote Development" badge. For unsupported extensions, consider alternatives or run them locally.

Slow Connection / High Latency

• Enable SSH compression (Compression yes in config)
• Use a faster cipher (Ciphers aes128-gcm@openssh.com)
• Consider using VS Code Tunnels for HTTPS-based tunneling (no open SSH port required)

VS Code Remote-SSH vs Alternatives

Remote-SSH is the best starting point for most developers — it's free, powerful, and works with any server you can SSH into.

Summary

VS Code Remote-SSH transforms how you work with remote servers:

✅ Full IntelliSense, debugging, and extensions on remote machines
✅ Integrated terminal that runs directly on the remote server
✅ Automatic port forwarding for local browser access
✅ Works with any SSH-accessible Linux, macOS, or Windows server
✅ Zero configuration on the remote beyond SSH access

Once you try remote development with VS Code, you'll never go back to editing over plain SSH again. The productivity gains — IntelliSense, multi-file refactoring, integrated debugging — are immediate and significant.

Next steps to explore:

• Dev Containers — containerized development environments
• Remote Tunnels — connect without an open SSH port
• GitHub Codespaces — cloud-hosted development environments