VS Code: Remote Development

VS Code's Remote Development extensions let you write code locally while the execution environment is on a remote server, inside Docker, or in WSL. The UI runs locally; the language server, debugger, and terminal run remotely.

Remote SSH

# Install: Extensions → "Remote - SSH" (ms-vscode-remote.remote-ssh)

# Connect to a remote host
# Ctrl+Shift+P → "Remote-SSH: Connect to Host..."
# Enter: user@hostname or use a config alias

# SSH config for named hosts (~/.ssh/config)
Host my-dev-server
  HostName 192.168.1.100
  User ubuntu
  IdentityFile ~/.ssh/id_ed25519
  ForwardAgent yes

Host aws-prod
  HostName ec2-54-123-456-789.compute-1.amazonaws.com
  User ec2-user
  IdentityFile ~/.ssh/aws-keypair.pem
  ServerAliveInterval 60

# After connecting:
# - VS Code status bar shows "SSH: hostname" (bottom-left)
# - Open Folder: opens folders on the remote machine
# - Terminal: runs on remote machine
# - Extensions: installed separately per remote host
# - Debug: runs on remote

# Port forwarding: forward remote port to local
# Ctrl+Shift+P → "Forward a Port"
# Or: Remote Explorer panel → Forwarded Ports → + icon
# Example: forward remote :3000 to local :3000 (access at localhost:3000)

# View forwarded ports
# Bottom panel → PORTS tab (appears when connected remotely)

# Reconnect to last remote
# Ctrl+Shift+P → "Remote-SSH: Connect to Host..." → pick recent

# Open remote file directly from URL
code --remote ssh-remote+my-dev-server /home/ubuntu/myproject

Dev Containers

Dev Containers define the development environment as code in `.devcontainer/devcontainer.json`. The entire team gets the exact same tools, runtimes, and dependencies - no more "works on my machine".

// .devcontainer/devcontainer.json
{
  "name": "Node.js + PostgreSQL",

  // Use a prebuilt image
  "image": "mcr.microsoft.com/devcontainers/javascript-node:20-bookworm",

  // Or build from Dockerfile
  // "build": {
  //   "dockerfile": "Dockerfile",
  //   "context": ".."
  // },

  // Docker Compose for multi-container setups
  // "dockerComposeFile": "docker-compose.yml",
  // "service": "app",
  // "workspaceFolder": "/workspace",

  // Services (adds containers alongside the dev container)
  "features": {
    "ghcr.io/devcontainers/features/git:1": {},
    "ghcr.io/devcontainers/features/github-cli:1": {},
    "ghcr.io/devcontainers/features/docker-in-docker:2": {}
  },

  // Forward ports (accessible on host)
  "forwardPorts": [3000, 5432],
  "portsAttributes": {
    "3000": { "label": "App", "onAutoForward": "openBrowser" },
    "5432": { "label": "PostgreSQL", "onAutoForward": "silent" }
  },

  // Run after container starts
  "postCreateCommand": "npm install && npm run db:migrate",

  // VS Code settings inside container
  "customizations": {
    "vscode": {
      "settings": {
        "terminal.integrated.defaultProfile.linux": "bash",
        "editor.formatOnSave": true
      },
      "extensions": [
        "dbaeumer.vscode-eslint",
        "esbenp.prettier-vscode",
        "ms-azuretools.vscode-docker"
      ]
    }
  },

  // Run as non-root user
  "remoteUser": "node"
}

WSL (Windows Subsystem for Linux)

# Install: Extensions → "WSL" (ms-vscode-remote.remote-wsl)
# Requires WSL 2 installed on Windows

# Install WSL 2
wsl --install              # Installs WSL2 + Ubuntu
wsl --install -d Ubuntu-22.04
wsl --set-default-version 2

# Connect VS Code to WSL
# Option 1: from WSL terminal
wsl
code .                     # Opens VS Code connected to WSL filesystem

# Option 2: from VS Code
# Ctrl+Shift+P → "WSL: Connect to WSL"
# Ctrl+Shift+P → "WSL: Connect to WSL using Distro..." → pick Ubuntu

# Status bar shows "WSL: Ubuntu" when connected
# Terminal runs Linux shell
# All tools (node, python, git) use Linux versions
# File system: /home/user/ (Linux) or /mnt/c/Users/... (Windows FS)

# Open WSL folder from Windows context menu
# Right-click folder in Windows Explorer → "Open with VS Code in WSL"

# Performance tip: keep project files on Linux filesystem (/home/user/)
# NOT on /mnt/c/ - Linux → Windows filesystem access is slow

# Port forwarding is automatic in WSL2
# App running on :3000 in WSL accessible at localhost:3000 on Windows

GitHub Codespaces

# GitHub Codespaces: cloud-hosted dev containers on GitHub
# Uses devcontainer.json from your repo
# Access via: github.com/owner/repo → Code → Codespaces → New codespace

# Open Codespace in VS Code desktop (instead of browser)
# Install: Extensions → "GitHub Codespaces"
# Ctrl+Shift+P → "Codespaces: Connect to Codespace..."

# GitHub CLI for Codespaces
gh codespace list
gh codespace create --repo owner/repo --branch main
gh codespace code               # Open current repo codespace in VS Code
gh codespace ssh                # SSH into codespace terminal
gh codespace stop
gh codespace delete

# Codespace environment variables
# Set in: github.com → Settings → Codespaces → Secrets
# Available as env vars in all your codespaces

# Prebuilds: pre-build codespace image for faster startup
# github.com/owner/repo → Settings → Codespaces → Prebuilds
# Triggers on push to branch, caches the post-create state

# Forward ports from Codespace
# Bottom panel → PORTS tab → Forward Port
# Set port visibility: Private (auth required) or Public
# Public URL: https://username-reponame-xxxx-PORT.preview.app.github.dev