Your local machine shouldn’t be the bottleneck for your development workflow.
VSCode Remote SSH lets you run your entire development environment on a remote server while keeping Visual Studio Code’s familiar interface on your computer. The language servers, debuggers, and extensions all execute on the remote host – not locally.
According to the 2025 Stack Overflow Developer Survey, 75.9% of developers use VS Code as their primary editor. Most of them don’t use Remote SSH. They’re missing out.
This guide covers everything from initial SSH connection setup and SSH key authentication to port forwarding, extension management, and bastion host configuration – so you can build a remote development environment that actually works.
What is VSCode With Remote SSH
VSCode Remote SSH is a Visual Studio Code extension that runs the editor’s entire backend on a remote machine over an SSH connection, while the local UI stays on your computer. You get full IntelliSense, debugging, and file access – all executing on the remote host.
Most people assume it works like a traditional SSH terminal with a nice UI on top. It doesn’t.
The extension is part of Microsoft’s Remote Development Extension Pack, sitting alongside the Dev Containers and WSL extensions. It’s the SSH-specific piece of that trio.
| What runs locally | What runs on the remote |
|---|---|
| VS Code UI (windows, panels, themes) | VS Code Server process |
| Keybindings and user preferences | Language servers and linters |
| UI extensions (e.g., themes) | Workspace extensions and debuggers |
| SSH client | Your codebase and file system |
The codebase lives entirely on the remote machine. The SSH tunnel handles all communication between the two VSCode processes.
Supported remote environments include Linux servers, Raspberry Pi, cloud VMs on AWS, Azure, or GCP, and Windows Server (with some limitations). According to the 2025 Stack Overflow Developer Survey, 75.9% of developers use VS Code as their primary editor – making Remote SSH one of the most practically relevant extensions in the ecosystem.
How VSCode Remote SSH Works
When you connect to a remote host for the first time, VS Code automatically downloads and installs a lightweight VSCode Server binary on that machine. You don’t trigger this manually. It just happens.
After that first install, the architecture looks like this:
- The local VS Code acts as a thin client, handling display and input only
- The VSCode Server on the remote handles all language processing, extension execution, and file I/O
- An SSH tunnel connects both sides and carries all communication
- Port forwarding runs through this same tunnel
One thing worth knowing: the VSCode Server keeps running on the remote even after you close your connection. It doesn’t automatically shut down.
Resource note: the server spawns a Node.js runtime and runs your installed workspace extensions. On a Raspberry Pi or a t2.micro EC2 instance, this can spike CPU to 200% or more (as documented in 4sysops, January 2024). Microsoft recommends at least 2 GB RAM and a 2-core CPU on the remote host for stable use.
GitHub Codespaces uses a closely related architecture – the remote execution model is essentially the same idea, scaled to managed cloud infrastructure.
Requirements and Compatibility
Local machine requirements:
- VS Code 1.75 or later
- Remote – SSH extension installed from the marketplace
- An OpenSSH-compatible SSH client (PuTTY is not supported)
Remote host requirements:
- OpenSSH server running and accessible
- Linux (most distros), macOS, or Windows Server 2019+
- glibc 2.17 or later (rules out some older distros – more on this in the troubleshooting section)
- Minimum 1 GB RAM; 2 GB+ strongly recommended
Windows as a remote host works but has real limitations. Certain extensions with x86 native binaries won’t run on ARM-based hosts either. Worth checking extension docs before committing to a setup.
Network-side: the remote SSH connection defaults to port 22. Any firewall between your local machine and the remote needs to allow outbound TCP on that port. SSH key-based authentication is the recommended approach – password auth works but adds friction and latency on every connection.
Setting Up Remote SSH in VSCode
The setup takes about five minutes if your SSH keys are already in place. If they’re not, add another few minutes for that step.
Configuring the SSH Config File
Before connecting through VS Code, add your remote host to ~/.ssh/config. This is what a basic entry looks like:
Host my-server HostName 192.168.1.100 User ubuntu IdentityFile ~/.ssh/ided25519
You can define as many hosts as you need in the same file. VS Code reads this file directly – whatever works in a regular SSH session will work here.
Useful additions to each host block:
- ServerAliveInterval 60 – prevents dropped connections on idle sessions
- ServerAliveCountMax 3 – defines how many missed keepalives before disconnect
- ControlMaster auto with ControlPersist 600 – speeds up repeated connections by reusing the initial SSH socket
Connecting for the First Time
Open the Command Palette (Ctrl+Shift+P or Cmd+Shift+P), type Remote-SSH: Connect to Host, and pick your configured host from the list.
VS Code opens a new window and installs the VSCode Server on the remote during this first connection. You’ll see a progress notification in the bottom-left. Once done, open any remote folder via File > Open Folder and you’re working directly on the remote machine.
The status bar at the bottom-left will show the remote host name, confirming you’re in a remote session.
SSH Key Setup for Passwordless Authentication
Password-based SSH auth works, but you’ll type it every single time VS Code reconnects – and it reconnects more often than you’d expect. Key-based auth is worth the five-minute setup.
Step 1 – Generate a key pair:
ssh-keygen -t ed25519 -C "your-email@example.com"
Ed25519 is the current recommended algorithm. RSA works too (use 4096-bit if you go that route), but Ed25519 keys are shorter and faster. Save the key to the default location unless you have a reason not to.
Step 2 – Copy the public key to the remote:
ssh-copy-id -i ~/.ssh/ided25519.pub user@remote-host
If ssh-copy-id isn’t available (common on Windows), manually append the contents of ided25519.pub to ~/.ssh/authorizedkeys on the remote.
Permissions matter here. This is probably the most common reason key auth silently fails:
- ~/.ssh
on the remote: chmod 700
- ~/.ssh/authorizedkeys
: chmod 600
If permissions are wrong, the SSH server ignores your key and falls back to password auth without telling you why. Took me longer than I’d like to admit to figure that out the first time.
Step 3 – Reference the key in your SSH config:
Host my-server HostName 192.168.1.100 User ubuntu IdentityFile ~/.ssh/ided25519
Managing multiple keys for multiple hosts is straightforward – just use different IdentityFile paths per host block in your config.
Managing Extensions Over Remote SSH
This is where a lot of developers get confused the first time. Extensions don’t all behave the same way in a remote session.
The split: VS Code divides extensions into two categories depending on where they need to run.
| Extension type | Where it runs | Examples |
|---|---|---|
| UI extensions | Local machine | Themes, keymaps, icon packs |
| Workspace extensions | Remote host (VS Code Server) | Pylance, ESLint, Prettier, debuggers |
When you open a remote session, your local UI extensions carry over automatically. But language servers, linters, and any extension that needs to touch your files must be installed on the remote side.
Installing a workspace extension on the remote: open the Extensions panel while connected, find the extension, and click “Install in SSH: your-host.” VS Code handles the rest.
To pre-install extensions automatically on every new remote connection, add them to your settings.json:
"remote.SSH.defaultExtensions": [ "ms-python.python", "dbaeumer.vscode-eslint" ]
If an extension isn’t behaving as expected (running locally when it should run remotely, or vice versa), use remote.extensionKind in settings.json to force its placement. This is a niche fix but occasionally necessary when extension authors haven’t set the kind correctly in their manifest.
One thing to watch: the ~/.vscode-server folder on the remote grows over time as extensions accumulate. If disk space is tight on the remote host, that folder is the first place to check.
Port Forwarding in Remote SSH
Port forwarding is one of the most useful things Remote SSH does quietly in the background. When a process on the remote machine starts listening on a port, VS Code detects it and offers to forward it to your local machine automatically.
You access the Ports panel from the bottom status bar. It’s easy to miss at first.
Two ways to forward ports during a session:
- Let VS Code detect and prompt you automatically when a port opens
- Add a port manually via the Ports panel using the “Add Port” button
For ports you always need forwarded, skip the Ports panel entirely. Use LocalForward directly in your ~/.ssh/config host block:
Host dev-server LocalForward 127.0.0.1:3000 127.0.0.1:3000 LocalForward 127.0.0.1:5432 127.0.0.1:5432
This handles forwarding before VS Code even opens, and it persists across reconnects.
Forwarded ports are private by default – accessible only on localhost. You can change a port’s visibility to “public” in the Ports panel if others on your network need access, but that’s rarely needed for a standard remote development SSH workflow.
One known issue: forwarded ports sometimes stop working correctly after a reconnect caused by a network interruption (tracked in the VS Code GitHub repo, issue #10568, December 2024). The workaround is removing and re-adding the port in the panel. Not ideal, but it takes five seconds.
Editing the Remote SSH Config and Settings
Most developers set up a host entry and never touch settings.json again. That works fine until you hit a slow connection, a platform detection delay, or a dropped session on high latency.
These settings are worth knowing about:
| Setting | What it does | When to use it |
|---|---|---|
| remote.SSH.remotePlatform | Skips OS detection on connect | Any Linux remote host |
| remote.SSH.connectTimeout | Extends connection timeout | High-latency or slow networks |
| remote.SSH.showLoginTerminal | Shows terminal during auth | Debugging MFA or password issues |
| remote.restoreForwardedPorts | Remembers forwarded ports | Any repeated port forwarding setup |
On the SSH config side, two entries prevent the most common session drop complaints:
ServerAliveInterval 60 ServerAliveCountMax 3
Remote settings vs. user settings: when you’re connected to a host, run “Preferences: Open Remote Settings” from the Command Palette to set host-specific overrides. These take precedence over your local user settings for that connection only.
Remote settings live on the remote machine inside ~/.vscode-server/data/Machine/settings.json. Workspace settings (.vscode/settings.json in your project) override both. That order matters when things behave differently than expected.
Troubleshooting Common Remote SSH Issues
Most Remote SSH failures fall into three buckets. Knowing which bucket you’re in cuts debugging time considerably.
Connection Failures
“Could not establish connection” is the most generic error message VS Code gives. It covers a lot of ground.
Check these in order:
- Test the raw SSH connection from your terminal first: ssh -v yourhost
- Confirm the SSH server is running on the remote: sudo systemctl status ssh
- Check that port 22 (or your custom port) isn’t blocked by a firewall
- Verify key permissions: chmod 700 ~/.ssh
andchmod 600 ~/.ssh/authorizedkeyson the remote
If the terminal SSH works but VS Code doesn’t, the problem is almost always inside VS Code’s SSH settings -not the connection itself. Enable remote.SSH.showLoginTerminal in settings to see what’s happening during auth.
VSCode Server Installation Problems
The VSCode Server install fails silently more often than you’d expect. It shows a progress spinner and then times out.
Common causes:
- Remote machine has no internet access (can’t download the server binary)
- glibc version below 2.17 on older Linux distros – VS Code drops a “remote host may not meet prerequisites” message
- Disk space exhausted on the remote (the ~/.vscode-server folder can grow past 300MB with extensions)
The fastest fix for a corrupted or stuck install: delete the server folder on the remote and reconnect.
rm -rf ~/.vscode-server
VS Code reinstalls it cleanly on the next connection. Alternatively, run “Remote-SSH: Uninstall VS Code Server from Host” from the Command Palette while connected.
Performance Issues on the Remote
High CPU on the remote after connecting is the most common complaint from developers running VS Code on low-spec machines. The 4sysops blog documented cases where vscode-server processes spike to 200% CPU with only a handful of extensions active (January 2024).
Microsoft’s minimum recommendation is 2 GB RAM and a 2-core CPU. On a t2.micro or Raspberry Pi, that threshold gets crossed fast.
Practical fixes:
- Disable extensions you don’t need on the remote – each one runs a separate process
- Use ps aux | grep vscode-server on the remote to identify which processes are heavy
- Kill lingering server processes when not actively connected
Using Remote SSH with Jump Hosts and Bastion Servers
Most corporate networks and cloud VPCs put servers behind a bastion host. The remote machine isn’t reachable directly – you have to hop through an intermediary first.
VS Code handles this without any special configuration inside the extension itself. The SSH config file does all the work.
Basic single-hop setup:
Host bastion HostName bastion.example.com User ubuntu IdentityFile ~/.ssh/ided25519
Host private-server HostName 10.0.1.50 User ubuntu IdentityFile ~/.ssh/id_ed25519 ProxyJump bastion
Connect to private-server in VS Code normally. The extension reads the SSH config and routes through the bastion automatically.
Multi-hop chains use comma-separated hosts in ProxyJump:
ProxyJump bastion1,bastion2
ProxyJump was introduced in OpenSSH 7.3 and creates a single end-to-end encrypted SSH session across all hops. It replaced the older ProxyCommand approach for most setups. For older SSH versions (pre-7.3), ProxyCommand still works:
ProxyCommand ssh -W %h:%p bastion
Agent forwarding note: if you need your local SSH key to be recognized on the final destination (not just the bastion), add ForwardAgent yes to the bastion host block in your SSH config. Use this carefully – agent forwarding gives the bastion access to your key agent while connected.
One known friction point: if the bastion SSH connection uses a non-standard port, the ProxyJump syntax needs an explicit port:
ProxyJump ubuntu@bastion.example.com:2222
VS Code’s Remote SSH extension reads these configurations exactly as the SSH client does, so anything that works in your terminal will work through the extension. Testing the full hop chain in a regular terminal first always saves time before debugging inside VS Code. This is especially relevant for teams using DevOps workflows with private infrastructure in isolated VPCs, where bastion setups are standard.
FAQ on VSCode Remote SSH
What is VSCode Remote SSH?
It’s a Visual Studio Code extension that connects your local editor to a remote machine over an SSH tunnel. The VSCode Server runs on the remote host, handling all language processing, debugging, and file access while your UI stays local.
Does VSCode Remote SSH work with cloud VMs?
Yes. It works with any SSH-accessible machine – AWS EC2, Google Cloud Compute Engine, Azure Virtual Machines, or a private Linux server. As long as OpenSSH is running and port 22 is reachable, the remote SSH connection works.
Why is VSCode Remote SSH using so much CPU on my server?
The VSCode Server spawns a Node.js runtime and runs all your workspace extensions on the remote host. Too many extensions running simultaneously causes high CPU. Disable unused remote extensions and ensure your server has at least 2 GB RAM.
How do I set up passwordless SSH authentication?
Generate an Ed25519 key pair with ssh-keygen -t ed25519, copy the public key to the remote using ssh-copy-id, then reference the private key via IdentityFile in your ~/.ssh/config file.
Can I use VSCode Remote SSH through a bastion host?
Yes. Add ProxyJump bastion-host to your remote host’s entry in ~/.ssh/config. VS Code reads the SSH config directly, so the jump host setup works without any extra configuration inside the extension itself.
How does port forwarding work in Remote SSH?
VS Code detects when a port opens on the remote machine and offers to forward it automatically. You can also add ports manually via the Ports panel. Use LocalForward in your SSH config for ports you always need available.
Which extensions run locally vs. on the remote?
UI extensions like themes run locally. Workspace extensions – linters, language servers, debuggers – install and run on the remote host. You can force placement using remote.extensionKind in settings.json if an extension lands in the wrong location.
What do I do when VSCode Server fails to install on the remote?
Usually it’s a missing internet connection on the remote, insufficient disk space, or an incompatible glibc version. Delete ~/.vscode-server on the remote and reconnect. VS Code reinstalls the server cleanly from scratch.
Can I use VSCode Remote SSH with a Raspberry Pi?
You can, but carefully. The VSCode Server is resource-heavy. A Raspberry Pi with less than 2 GB RAM will struggle under normal extension load. Limit active remote extensions and monitor CPU usage to keep the connection stable.
How is VSCode Remote SSH different from GitHub Codespaces?
GitHub Codespaces is a managed cloud service – Microsoft handles the infrastructure. Remote SSH connects to any machine you control. Remote SSH gives you more flexibility; Codespaces gives you less setup friction and easier team sharing.
Conclusion
This conclusion is for an article presenting VSCode Remote SSH as a practical solution for developers who work across Linux servers, cloud VMs, and private infrastructure behind bastion hosts.
Once the SSH config file is set up correctly and key-based authentication is in place, the remote development workflow becomes nearly identical to working locally.
Port forwarding, remote debugging, and workspace extension management all run through the same SSH tunnel – no extra tools required.
The VSCode Server does demand real resources on the remote host, so low-spec machines need careful extension management.
Get that right, and Remote SSH is one of the most reliable ways to keep your development environment consistent across every machine you touch.
Many of his resources are available on various design marketplaces and for free on Codepen.
Over the years, he's worked with a range of clients and contributed to design publications like Design Your Way, Designmodo, WebDesignerDepot, WPDean, Speckyboy, and Slider Revolution among others.
- How to Make a Repository Public in GitHub - July 14, 2026
- Production Incident Communication Without Separate Monitoring and Status-Page Systems - July 13, 2026
- How to Set Up Subscriptions on Google Play (Developer Guide) - July 12, 2026
