Skip to content
Tutorials Center
My learning

Topics

Lesson 32 of 40 ยท Git and Remote Development

Remote Development with SSH and WSL

Learn how VS Code Remote Development works, connect to a server over SSH, use WSL on Windows, configure the SSH config file, forward ports and stay safe.

Sometimes your code does not live on the computer in front of you. It may sit on a Linux server, inside the Windows Subsystem for Linux (WSL), or in a container. VS Code's Remote Development extensions let you open a folder on that other machine and work as if it were local. The window looks the same, but the files, the terminal, the debugger and the extensions run there.

This lesson explains the model, then walks through Remote - SSH and WSL. We cannot connect to a machine from this site, so the steps are described, and the stand-ins model the SSH configuration and port forwarding logic in JavaScript. Dev containers are covered next.

The architecture: UI here, workspace there

Two halves of one window

Local UI, themes, keyboard
Remote Files, terminal, debugger

A small VS Code Server runs on the remote.

1 / 2

When you connect, VS Code installs a small VS Code Server on the remote machine. Your local window is only the interface. Extensions are split into two kinds: UI extensions (themes, keymaps) stay local, and workspace extensions (language support, debuggers) are installed on the remote, where the code is. The Extensions view shows a section for the remote and offers Install in SSH: host.

No source code is copied to your computer; keystrokes and results travel over the connection.

Remote - SSH

Requirements: an SSH client on your computer (OpenSSH is built into recent Windows, macOS and Linux), SSH access to the host and a supported 64-bit Linux or macOS remote.

  1. Install the Remote - SSH extension (publisher Microsoft; it is also included in the Remote Development pack).
  2. Click the green or blue button in the bottom-left corner, or run Remote-SSH: Connect to Host... from the Command Palette.
  3. Enter user@hostname, or pick a host from your SSH config.
  4. Accept the host key on first connection, after checking it is the one you expect.
  5. Open a folder on the remote with File > Open Folder.

The bottom-left corner now shows SSH: hostname. The terminal you open runs on the server.

The SSH config file

Hosts are described in ~/.ssh/config. A short file makes connecting a single click:

TEXT
Host build-box
  HostName 203.0.113.25
  User ada
  Port 22
  IdentityFile ~/.ssh/id_ed25519
  ServerAliveInterval 30

203.0.113.25 is a documentation address. IdentityFile points to your private key; protect it and never share it. Using keys instead of passwords is both safer and more convenient. Choose Remote-SSH: Open SSH Configuration File... to edit it.

You can also reach hosts through a jump host with ProxyJump bastion in the config. If the connection fails, open the Remote - SSH output channel for the exact error.

WSL

On Windows, WSL runs a real Linux distribution inside Windows. The WSL extension lets VS Code edit files in the Linux file system and run its terminal in that distribution.

  • From a WSL shell, type code . to open the current folder in VS Code connected to WSL.
  • Or use WSL: Connect to WSL and WSL: Open Folder in WSL... from the Command Palette.
  • Keep project files in the Linux home folder (for example ~/projects), not under /mnt/c, because file access across the boundary is much slower.

WSL is a good choice when your target is Linux (servers, containers, Linux-only tools) but your computer runs Windows.

Port forwarding

A web app that listens on localhost:3000 on the remote machine is not reachable from your browser directly. VS Code forwards ports: it opens a local port that tunnels to the remote one. The Ports panel lists forwarded ports; VS Code can detect a server starting and forward automatically. Click the globe icon to open the forwarded address in your browser. By default a forwarded port is private to you; making it public is a deliberate action, so think before you share one.

Working offline and reconnecting

If the connection drops, VS Code shows a reconnecting dialog and usually restores your session. Unsaved edits remain in the local window. Long-running jobs should be started with a tool such as tmux or nohup so they survive a dropped connection.

Security notes

  • Use keys, protect the private key with a passphrase and do not paste it anywhere.
  • Verify the host fingerprint on first connect.
  • Only connect to machines you trust: the remote can influence what runs in your window.
  • Do not forward ports publicly unless needed.

Runnable stand-ins

JS Stand-in: read an SSH config

Press Run (or Ctrl + Enter) to see the console output here.

No output.

JS Stand-in: pick local ports for forwarding

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Where does the terminal run when you are connected with Remote - SSH?

    Files, terminals and debuggers run on the remote; only the UI runs locally.
  2. 2. Which file stores SSH host shortcuts?

    ~/.ssh/config defines Host entries; id_ed25519 is a private key.
  3. 3. Why keep WSL projects in the Linux home folder rather than /mnt/c?

    Crossing the Windows/Linux boundary is slow; native Linux paths perform far better.
  4. 4. What does port forwarding do?

    VS Code tunnels a local port to the remote one so your browser can reach the remote app.

Summary

  • Remote Development keeps the UI local and runs files, terminals and debuggers on the remote machine.
  • Remote - SSH connects to a host using ~/.ssh/config; use keys and verify host fingerprints.
  • WSL gives Windows users a Linux environment; keep code in the Linux file system.
  • Workspace extensions install on the remote; UI extensions stay local.
  • Forwarded ports let you open remote web apps in a local browser.

Next: Dev Containers