keepcalculator

06 Numbers and Powers

VS Code Remote Development via SSH: How It Works

Card No. 06·83737 · Updated · Standard formula, shown below

VS Code Remote-SSH lets you edit and debug code on a remote server exactly as if it were on your local machine, with your full IDE running locally while files, processes, and terminals execute remotely. You install the Remote-SSH extension, add a host to your SSH config, and connect — no code is copied to your laptop. This article explains what happens behind the scenes, how to set it up, common pitfalls, and how to choose between the available remote development options.

What Actually Happens When You Connect

When you click “Connect to Host” and pick a server, VS Code performs these steps:

  • It opens an SSH connection to the remote machine using your configured credentials (key or password).
  • It downloads a small server component (the VS Code Server) into ~/.vscode-server on the remote host — this runs your extensions, language servers, and terminal.
  • Your local VS Code window becomes a client that renders the UI and streams keystrokes, file contents, and output over the SSH connection.
  • All file operations, searches, Git commands, and build tasks run on the remote machine, so you never transfer large repositories to your local disk.

This architecture means your local machine only needs enough power to run the editor UI. The remote side needs the actual toolchain (compilers, interpreters, linters) and enough RAM/CPU for your workload.

Prerequisites and Setup

Before you start, ensure you have:

  • VS Code installed locally (version 1.45+ for Remote-SSH).
  • The Remote-SSH extension (by Microsoft) installed from the marketplace.
  • An SSH client on your local machine (OpenSSH on Linux/macOS, or the built-in OpenSSH client on Windows 10/11).
  • A remote server with SSH enabled, and an account with permission to log in.
  • Network access to the server (port 22, or a custom port).

Once the extension is installed, open the Remote Explorer (the monitor icon in the sidebar), click “+” to add a new host, and enter user@hostname. VS Code will add it to your ~/.ssh/config file. You can also edit that file manually to set a custom port, identity file, or jump host.

For key-based authentication (recommended over passwords), generate a key pair locally with ssh-keygen -t ed25519, then copy the public key to the server with ssh-copy-id user@hostname (or manually append it to ~/.ssh/authorized_keys).

Choosing Between Remote-SSH, WSL, and Containers

VS Code offers three remote development extensions, and they solve different problems:

  • Remote-SSH — best for a dedicated Linux server, a VM in the cloud, or a machine on your LAN. You get the full Linux environment without virtualization overhead.
  • WSL (Windows Subsystem for Linux) — best if you’re on Windows and want a Linux environment without a separate machine. It runs a lightweight VM under the hood.
  • Dev Containers — best for reproducible development environments defined in a Dockerfile or devcontainer.json. You can spin up a container with specific tools and dependencies, and VS Code attaches to it.

If you already have a server, Remote-SSH is the simplest. If you need isolated environments per project, Dev Containers is more powerful. WSL is a middle ground for Windows users who want Linux without leaving their machine.

Common Problems and How to Fix Them

Here are the most frequent issues users hit, with concrete fixes:

  • “Can’t connect to host” — Check the SSH connection first with ssh user@host from a terminal. If that fails, the problem is network, credentials, or the SSH server config. If it works, check the VS Code Remote-SSH log (Output panel → “Remote-SSH”).
  • VS Code Server fails to download — The server component is fetched from Microsoft’s servers. If your remote host has no internet access, you can download the server tarball manually and place it in ~/.vscode-server/bin/. Alternatively, use a proxy or set remote.SSH.allowLocalServerDownload.
  • Extensions not installed on remote — Extensions run on the remote side. Install them from the Extensions view, and click “Install in SSH: hostname” if prompted. Some extensions (like themes) can run locally.
  • Slow connection or high latency — Use a reliable network, enable SSH compression (Compression yes in your SSH config), and avoid using a VPN if it adds overhead. Also, disable unnecessary extensions that poll the filesystem.
  • Port forwarding for web apps — If your app runs on a port (e.g., 3000), VS Code can forward it automatically when you open a terminal. Use the “Ports” panel to add a forward, or run ssh -L 3000:localhost:3000 user@host manually.

Performance and Security Considerations

Remote-SSH is generally fast because only UI events and file diffs travel over the wire. However, large file transfers (like opening a 100 MB log) can feel sluggish. For better performance, keep your working directory on the remote filesystem, not on a network mount.

Security-wise, always use key-based authentication and disable password login on the server if possible. Never expose SSH to the public internet without a firewall or fail2ban. Also, be aware that the VS Code Server runs with your user’s privileges on the remote machine — treat it like any other service you install.

If you’re connecting through a jump host (bastion), you can configure a ProxyJump in your SSH config:

Host internal-server
  HostName 10.0.0.5
  User myuser
  ProxyJump myuser@bastion.example.com

Alternatives to VS Code Remote-SSH

If VS Code isn’t your editor, other tools offer similar remote workflows:

  • JetBrains IDEs (e.g., PyCharm, IntelliJ) have a “Remote Development” feature that runs the IDE backend on the server and a thin client locally.
  • Emacs with Tramp mode lets you edit remote files via SSH directly, though it lacks the full IDE integration.
  • Vim/Neovim over SSH — just SSH into the server and edit there. Simple, but you lose the local GUI.
  • VS Code Web (code-server) — you run VS Code in the browser on the server, and access it via a URL. This is different from Remote-SSH because the entire editor runs on the server, not just the backend.

Each has trade-offs in setup complexity, feature parity, and resource usage. Remote-SSH is the most seamless if you’re already a VS Code user.

Frequently Asked Questions

Can I use Remote-SSH with a Windows server?

Yes, but it’s less common. The remote machine must have an SSH server (OpenSSH for Windows) and VS Code Server supports Windows, but some extensions may not work. Most users target Linux servers.

Does Remote-SSH work without internet access on the server?

Yes, if you pre-install the VS Code Server manually. The server component is a single directory that you can download on a machine with internet and copy over. VS Code will detect it and use it.

Why do my extensions not appear on the remote host?

Extensions are installed per-remote. When you connect to a host, the Extensions view shows a “Install in SSH” button for local extensions that aren’t yet installed remotely. Click it to install. Some extensions (like debuggers) must run on the remote side to work.

How do I keep my local and remote files in sync?

You don’t need to — Remote-SSH works directly with remote files. If you want a local copy for offline work, use Git to clone the repository locally and push/pull, or use an SFTP extension that syncs on save.

Is Remote-SSH free?

Yes, the Remote-SSH extension is free and included in VS Code. The only cost is the server you connect to (if it’s a cloud VM). There’s also a paid option called “Remote Tunnels” that lets you connect to a machine behind a NAT without a public IP, but the classic SSH method is free.

Can I use Remote-SSH with a GUI application on the server?

No, Remote-SSH is for terminal and editor workflows. If you need a full desktop GUI, use X11 forwarding (ssh -X) or a remote desktop solution like VNC or RDP.

Related

Method: the standard formula for this calculation, rounded as each result states. See how the calculators work or report an error.

More cards in this drawer

The whole Numbers and Powers drawer →