VSCode Remote Development: Remote-SSH Setup and Connection Debugging

When remote development is worth it

Three typical scenarios: (1) code must stay on the intranet (compliance forbids syncing locally); (2) heavy work needs remote compute (training, builds, large test suites) with the laptop only editing; (3) dependencies only run on Linux. Remote-SSH deploys a VSCode Server into ~/.vscode-server on the remote host — the UI renders locally while language servers and terminals execute remotely, so opening a huge repo barely touches local RAM.

# Install: search "Remote - SSH" in the extension marketplace (ms-vscode-remote.remote-ssh)

Three steps: host, passwordless, platform

(1) Put the server in ~/.ssh/config (alias + user + key) — Remote-SSH reads this file directly for host selection; (2) verify passwordless access from a terminal first (ssh alias) with keys configured — this single step eliminates 90% of connection problems; (3) run Remote-SSH: Connect to Host from the command palette; the first connect auto-downloads the platform-matching vscode-server.

For bastion hosts one ProxyJump line in the config replaces manual double-hopping.

Host gpu-box
  HostName 10.0.0.8
  User dev
  IdentityFile ~/.ssh/id_ed25519
  ProxyJump bastion.corp.internal   # Bastion host in one line

Five steps when connection fails

(1) Can a bare terminal ssh alias connect? If not, fix the SSH layer first (permissions/keys/network) instead of retrying inside VSCode; (2) is the remote disk full? vscode-server writes hundreds of MB into ~/.vscode-server, and a full disk hangs the connect at "Setting up SSH Host"; (3) corrupted ~/.vscode-server (interrupted upgrade, wrong arch): delete the directory and reconnect to reinstall; (4) remote glibc too old: very old distros cannot run new server builds — pin an older VSCode or upgrade the OS; (5) port forwarding failures: local proxy/VPN conflicts or a firewall blocking the channel.

df -h ~                       # Check if the remote disk is full
rm -rf ~/.vscode-server       # Reset when corrupted (reinstalls on reconnect)

Tuning the experience: extensions, ports and git

Extensions split into local and remote sides: language ones (Python/ESLint) must be "Installed in SSH: xxx" on the remote; themes and icons stay local. When a dev server runs on a remote port, forward it via the Ports panel — browsing localhost:3000 then hits the remote service, the core convenience for debugging.

Git runs on the remote, so push auth uses remote credentials (SSH keys or a credential helper there), independent of your local GitHub login — misplacing this is the number-one cause of "why does push always 403".

# Common command palette entries:
Remote-SSH: Connect to Host
Forward Port...            # Map a remote port to local
Install in SSH: <host>    # Install extensions on the remote

Choosing between this and bare SSH + vim

Remote-SSH suits code-centric daily work: full IDE powers (navigation, refactoring, debugger) plus remote compute. When the server has only a few hundred MB to spare, or you are firefighting two config lines, a bare ssh + vim is lighter. They do not conflict: if vscode-server cramps the disk, deleting it rolls back cleanly with no residue.

du -sh ~/.vscode-server   # Check remote server disk usage
rm -rf ~/.vscode-server   # Full uninstall (re-downloads on next reconnect)

Wrap-up checklist

Alias in config → verify passwordless in a terminal → Connect to Host → install language extensions remotely → forward ports for debugging → configure git credentials on the remote. After these six steps the remote experience is nearly local; when connection issues arise, first check the bare SSH layer, then the vscode-server layer.

ssh <alias> && code .   # Once passwordless works, one command enters remote dev