Blog
5 min read

VS Code Remote SSH: Develop on a Remote Server as if It Were Local

The Remote - SSH extension lets VS Code edit files, run terminals and debug on a remote Linux server. How it works, setup step by step, SSH config and keys, extensions and port forwarding, and fixes for the common connection problems.

Your laptop is slow, your app needs Linux, or your project already lives on a server — and you'd still like your normal editor. VS Code's Remote - SSH extension does exactly that: the VS Code window runs on your machine, while files, terminals, extensions and debugging run on the remote server. It feels local, but nothing runs locally.

How it works

When you connect, VS Code:

  1. opens an SSH connection to the server,
  2. installs a small VS Code Server there (in your home directory),
  3. runs your language extensions, terminal and debugger on the server,
  4. streams the interface back to your local window.

Your code never has to be copied to your laptop. Builds use the server's CPU and memory. Dependencies install once, on the server.

Requirements

  • Locally: VS Code (or a compatible fork like Cursor) and an SSH client — built into macOS, Linux and Windows 10/11.
  • Remotely: a Linux server (x86_64 or ARM64) you can SSH into. Recent VS Code versions require a reasonably modern Linux distribution (glibc 2.28 or later — Ubuntu 20.04+, Debian 10+, and similar). macOS and Windows hosts are also supported for SSH.

Setup, step by step

1. Make sure plain SSH works first

ssh you@your-server.example.com

If that doesn't work in a terminal, it won't work in VS Code. Use key-based login rather than passwords — it's more secure and stops VS Code prompting repeatedly. (SSH keys explained.)

2. Add the server to your SSH config

Save typing (and help VS Code) with an entry in ~/.ssh/config:

Host myserver
  HostName your-server.example.com
  User you
  IdentityFile ~/.ssh/id_ed25519

Now ssh myserver works, and VS Code lists myserver automatically. (The SSH config file explained.)

3. Install the extension

In VS Code, open Extensions (Ctrl/Cmd+Shift+X) and install Remote - SSH by Microsoft.

4. Connect

Press F1 (or Ctrl/Cmd+Shift+P) → Remote-SSH: Connect to Host… → choose myserver. A new window opens; the bottom-left corner shows SSH: myserver. Use File → Open Folder to open your project on the server.

Working remotely

  • Terminal (Ctrl+`) opens a shell on the server.
  • Extensions install into either the local or the remote side. Language servers, linters and debuggers need to be installed on the remote; themes and keymaps stay local. VS Code shows an "Install in SSH: myserver" button.
  • Port forwarding: start your app on the server on port 3000, and VS Code offers to forward it — open http://localhost:3000 in your local browser and you're seeing the remote app. You can also add ports manually in the Ports panel. (SSH port forwarding explained.)
  • Git runs on the server, using the server's git configuration and credentials.
  • AI tools: run Claude Code in the remote terminal, or use the Claude Code extension installed on the remote side, so the agent works where the code and running app are. (Claude Code in VS Code.)

Common problems and fixes

"Could not establish connection" / timeouts

  • Test ssh myserver in a normal terminal and fix that first.
  • Check the server's firewall allows SSH (port 22, or your custom port in the config).
  • Read the Output panel → Remote - SSH log; it shows the exact failure.

Keeps asking for a password

Set up key-based authentication and add the key to your SSH agent. On Windows, enable the OpenSSH Authentication Agent service.

Stuck at "Installing VS Code Server" or "Setting up SSH Host"

  • The server may be out of disk space (df -h).
  • The server may block downloads; VS Code can download the server locally and copy it over — look for the "local server download" setting.
  • A previous install may be broken: run Remote-SSH: Kill VS Code Server on Host… and reconnect.

"The remote host may not meet VS Code Server's prerequisites"

The server's Linux is too old for current VS Code. Upgrade the distribution, or connect with a supported host.

Slow or laggy

Latency to the server matters — pick a server region near you. (What is latency?.) Exclude large folders like node_modules from file watching (files.watcherExclude) to reduce load.

"Wrong platform" detected

Set the remote's platform explicitly with the remote.SSH.remotePlatform setting (e.g. "myserver": "linux").

Why develop this way?

  • Same environment as production: Linux, case-sensitive files, the real database. Fewer works-locally-not-in-production surprises.
  • Power on demand: builds and agents use the server's resources, not your laptop's battery.
  • Pick up anywhere: your project and running processes stay on the server; any machine with VS Code can connect. Combined with tmux, long-running tasks survive disconnects.
  • Cheaper hardware: a modest laptop is enough. (Cloud development environments vs local setup.)

The summary

  • Remote - SSH runs VS Code's back end on a Linux server and the interface locally.
  • Get plain SSH working with keys and an SSH config entry, then connect with "Remote-SSH: Connect to Host".
  • Install language extensions on the remote side; forward ports to see your app locally.
  • Most problems are SSH problems, disk space, or an outdated server OS.

EasySpawn servers are reachable over SSH as well as from the web and your phone — point VS Code Remote SSH at your server and edit right beside your running app, database and Claude Code. See how it works or join the waitlist.

Related: How to Run Claude Code on a Remote Server · Self-Hosted Cloud IDEs · What Is a Dev Container? · VS Code for Beginners

Keep reading