VS Code Remote SSH: Stop Developing on Your Laptop

Set up VS Code Remote SSH to develop directly on a remote server — SSH config, extension placement, port forwarding, and key permission fixes covered.

If you're running compute-heavy workloads on a local machine that struggles with multiple Docker containers and a language server, you're working harder than you need to. VS Code Remote SSH lets you keep the familiar editor experience while offloading all actual computation to a remote server — a cluster node, a cloud VM, or even a beefy desktop in another room.

This tutorial walks through the full setup, the config file layout that actually scales, and the gotchas I hit when first moving my dev environment off-laptop.

---

The Problem: Your Laptop Is a Bottleneck

Running a Python data pipeline, a local Postgres instance, and a TypeScript language server simultaneously will bring most laptops to their knees. The usual workaround — SSH into a server, edit files in vim or nano, transfer files with scp — is slow and breaks your flow constantly.

The other common pattern is keeping a local copy of the code and rsync-ing changes up to the server. That works until it doesn't: you forget to sync, you edit the wrong copy, and you spend 20 minutes debugging a "bug" that doesn't exist on the server.

What I wanted was a single source of truth on the server, with a real editor on top.

---

Section 1: Installation and SSH Config

Install the Remote Development extension pack from Microsoft — it bundles Remote SSH, Remote Containers, and WSL in one install. You want the full pack, not just the SSH extension alone, because the container support becomes useful later.

# From the VS Code command palette
ext install ms-vscode-remote.vscode-remote-extensionpack

Once installed, the real setup happens in your SSH config file, not in VS Code's UI.

# Edit or create the SSH config
nano ~/.ssh/config

Here's the structure that works well when you have multiple servers:

Host dev-cluster
  HostName 192.168.1.100
  User seunghyeon
  IdentityFile ~/.ssh/id_ed25519
  ServerAliveInterval 60
  ServerAliveCountMax 3

Host gpu-box
  HostName gpu.mylab.internal
  User seunghyeon
  IdentityFile ~/.ssh/id_ed25519
  ForwardAgent yes

A few things here that matter:

• ServerAliveInterval 60 + ServerAliveCountMax 3 keeps the connection alive through NAT timeouts. Without these, your session drops silently after a few minutes of inactivity.
• ForwardAgent yes lets the remote machine use your local SSH keys — useful if the server needs to pull from private GitHub repos.

After saving the config, open the Command Palette (Cmd+Shift+P on Mac, Ctrl+Shift+P on Linux/Windows) and run Remote-SSH: Connect to Host. Your configured hosts appear in the dropdown.

---

Section 2: What Runs Where

This is the core insight that makes everything click. When you connect via Remote SSH, VS Code splits itself in two:

• Local side: the window chrome, keybindings, themes, and Git decoration
• Remote side: the language server, linter, debugger, terminal, and file system

The practical consequence: extensions that touch files or run processes must be installed on the remote side. If you install ESLint or Pylance locally, they won't do anything useful in a remote session. VS Code will usually prompt you to install them on the remote, but you can also do it explicitly:

# Inside the remote-connected VS Code terminal
# Verify which Python the language server will use
which python3
python3 --version

For Python projects specifically, always confirm the interpreter path via the Command Palette → Python: Select Interpreter. The remote server may have multiple Python versions and the default often isn't the one in your virtual environment.

---

Section 3: Variations and Gotchas

Port Forwarding

Running a web server on the remote? VS Code handles port forwarding automatically in many cases, but you can also configure it explicitly.

Host dev-cluster
  HostName 192.168.1.100
  User seunghyeon
  IdentityFile ~/.ssh/id_ed25519
  LocalForward 8080 localhost:8080
  LocalForward 5432 localhost:5432

This maps localhost:8080 and localhost:5432 on your laptop to the same ports on the remote server. Your browser and local DB client work without any changes.

Extension Behavior Across Environments

Extension Type	Where to Install	Why
Themes / Icons	Local	Only affects rendering
Language servers (Pylance, tsserver)	Remote	Must access remote files
Linters (ESLint, Ruff)	Remote	Must read remote project files
Git decorations	Either	VS Code syncs state
Docker extension	Remote	Needs Docker socket access

SSH Key Permissions

This trips up almost everyone on Linux servers. If your connection fails with Permission denied (publickey), check the key file permissions first:

# On the remote server
chmod 700 ~/.ssh
chmod 600 ~/.ssh/authorized_keys

# On your local machine
chmod 600 ~/.ssh/id_ed25519
chmod 644 ~/.ssh/id_ed25519.pub

If permissions are correct and you still get denied, verify the public key is actually in ~/.ssh/authorized_keys on the server:

# On remote
cat ~/.ssh/authorized_keys
# Should contain your id_ed25519.pub content

Slow First Connection

The first time you connect to a new server, VS Code installs a small server binary on the remote. This can take 30–60 seconds depending on the server's internet speed. Subsequent connections are near-instant.

If the server has no internet access (air-gapped environments), you need to manually copy the VS Code server binary. The official docs cover this, but it's a niche case.

macOS vs. Linux Differences

On macOS, the SSH agent is managed by the system keychain. Run this once to persist the key across reboots:

# macOS only
ssh-add --apple-use-keychain ~/.ssh/id_ed25519

On Linux, you typically need to start the agent manually or via your .bashrc:

# Linux — add to ~/.bashrc or ~/.zshrc
eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_ed25519

On Windows using WSL2, point your SSH config at the key inside the WSL filesystem (/home/user/.ssh/) rather than the Windows path — mixing paths causes subtle authentication failures.

---

Closing

The one-line takeaway: your laptop is a display and a keyboard; the server is where your code lives and runs. Remote SSH makes that split invisible.

Next logical step from hereis Remote Containers (Dev Containers) — same concept, but instead of SSH-ing into a bare server, you attach VS Code to a Docker container running a fully reproducible environment. If you're already using Docker Compose for local dev, it's a small jump. 🚀

---

🐦 Faster updates on X: @baegseungh7061
📚 More in this series: AI Insights
💌 Subscribe: Follow on X or grab the RSS