巧匠Developer Cheatsheet
Dev Tools

VSCode Remote Development: Remote-SSH Setup and Connection Debugging

A weak laptop, code on an intranet server, GPUs in the cluster — Remote-SSH keeps the UI local while code and terminal run remotely, feeling native. This guide covers setup, passwordless auth, common connection failures and experience tuning.

By 巧匠 Team·7 min read·Updated 2026-08-30

When remote development is worth it

Three typical scenarios: ① code must stay on the intranet (compliance forbids syncing locally); ② heavy work needs remote compute (training, builds, large test suites) with the laptop only editing; ③ 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.

# 安装：扩展市场搜索 "Remote - SSH"（ms-vscode-remote.remote-ssh）

Three steps: host, passwordless, platform

① Put the server in ~/.ssh/config (alias + user + key) — Remote-SSH reads this file directly for host selection; ② verify passwordless access from a terminal first (`ssh alias`) with keys configured — this single step eliminates 90% of connection problems; ③ 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   # 跳板机一行搞定

Five steps when connection fails

① Can a bare terminal `ssh alias` connect? If not, fix the SSH layer first (permissions/keys/network) instead of retrying inside VSCode; ② 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"; ③ corrupted ~/.vscode-server (interrupted upgrade, wrong arch): delete the directory and reconnect to reinstall; ④ remote glibc too old: very old distros cannot run new server builds — pin an older VSCode or upgrade the OS; ⑤ port forwarding failures: local proxy/VPN conflicts or a firewall blocking the channel.

df -h ~                       # 远端磁盘是否写满
rm -rf ~/.vscode-server       # 损坏时重置（重连自动重装）

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".

# 命令面板常用：
Remote-SSH: Connect to Host
Forward Port...            # 远端端口映射到本地
Install in SSH: <host>    # 扩展装到远端

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   # 看远端 server 占用
rm -rf ~/.vscode-server   # 完全卸载（下次重连会重新下载）

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 别名 && code .   # 免密就绪后，一条命令进入远程开发

More guides

Git Accident Recovery: Fix Wrong Commits, Wrong Branches and Deleted BranchesThe scariest moment in daily work is "oh no, I messed up a commit or branch". This guide gives copy-ready recovery commands for real accident scenarios, with clear safety boundaries for each.Docker Image Slimming: 5 Steps from 1.2GB to 120MBBigger images mean slower pulls, larger attack surface and higher storage cost. This guide gives 5 immediately applicable slimming steps, each with a reusable Dockerfile snippet and a verification command.Nginx 502 Bad Gateway? Locate It in 5 StepsA 502 means Nginx itself is fine but got an invalid response from the upstream (backend/proxy). This guide gives the shortest path: process → config → timeout → resources → logs.Linux Disk Full: Locate the Real Culprit with df, du and lsofA "No space left on device" error does not mean you should delete files at random. This guide walks through the full path — filesystem water level, directory drill-down, and "deleted but still held" files — plus a safe cleanup order that will not destroy data.Linux CPU at 100%: the Shortest Path from top to the Thread Stack"Restart fixes everything" is the most expensive option when CPU is pegged. This guide gives a reusable path: classify the load, pin the thread, capture what it is executing, then act — with dedicated tools for Java, Python and Go.MySQL Slow Query Tuning: Slow Log, EXPLAIN and Indexing"The database is slow" usually means a handful of slow SQL statements. This guide offers a repeatable flow: use the slow log to circle the most expensive queries, read the plan with EXPLAIN, decide whether an index pays off, and spot the most common index-defeating patterns.Redis Slowdown Playbook: Big Keys, Blocking Commands and EvictionRedis processes commands on a single thread, so one blocking hotspot slows the whole instance. This guide follows the order "memory level → big keys → blocking commands → eviction and persistence", each step with copy-ready commands.Kubernetes CrashLoopBackOff: Diagnose a Restart-Looping Pod in 5 StepsCrashLoopBackOff is not one error but a state: the container dies on start, and Kubernetes retries with backoff. This guide gives the shortest path — exit code → previous logs → probes → resources → dependencies.SSH Passwordless Login: from ssh-keygen to Permission deniedPasswordless SSH boils down to one sentence: put the public key into the remote authorized_keys. What blocks you is usually the three hidden gates — file permissions, the home directory, and SELinux. This guide covers the full setup and a step-by-step debugging path.Python Virtual Environments in Practice: venv, Dependency Pinning and Cross-Platform Gotchas"Works on my machine" usually means mixed environments. This guide builds a clean flow with the stdlib venv: create, activate, pin and reproduce — plus the three frequent pitfalls: Windows activation, version drift and cross-platform dependencies.
← Back to Guides