VS Code Remote Development on Ubuntu via SSH

This comprehensive guide explains how to set up Visual Studio Code (VS Code) for remote development on an Ubuntu machine using SSH. This setup enables you to develop directly on remote servers while maintaining the comfort of your local VS Code environment.

Overview

Remote development with VS Code over SSH provides several benefits:

• Direct server development: Edit files directly on the remote machine
• Consistent environment: Use your local VS Code setup with remote resources
• Security: Encrypted SSH connection protects your work
• Flexibility: Access powerful remote machines from any local device

Prerequisites

• VS Code installed on your local machine
• Ubuntu machine with network access
• Administrator privileges on both machines

1. Install VS Code and Extensions

1.1 Install VS Code

Download and install VS Code from the official website.

1.2 Install Remote Development Extensions

Install the Remote Development extension pack which includes:

• Remote - SSH
• Remote - Containers
• Remote - WSL

Installation steps:

1. Open VS Code
2. Click the Extensions view icon (Ctrl+Shift+X)
3. Search for "Remote Development"
4. Install the extension pack by Microsoft

1.3 Alternative: Install Individual Extensions

If you only need SSH functionality:

1. Search for "Remote - SSH"
2. Install the extension by Microsoft

2. Configure SSH Server on Ubuntu

2.1 Install OpenSSH Server

# Update package lists
sudo apt update

# Install OpenSSH server
sudo apt install openssh-server

# Verify installation
sudo systemctl status ssh

2.2 Configure SSH Service

# Enable SSH service to start on boot
sudo systemctl enable ssh

# Start SSH service
sudo systemctl start ssh

# Check if SSH is listening on port 22
sudo ss -tlnp | grep :22

2.3 Configure SSH Security (Recommended)

Edit the SSH configuration file:

sudo nano /etc/ssh/sshd_config

Recommended security settings:

# Change default port (optional, for better security)
# Port 2222

# Disable root login
PermitRootLogin no

# Enable public key authentication
PubkeyAuthentication yes

# Disable password authentication (after setting up keys)
# PasswordAuthentication no

# Keep connections alive
ClientAliveInterval 60
ClientAliveCountMax 3

# Limit login attempts
MaxAuthTries 3

Apply configuration changes:

sudo systemctl restart sshd

3. Network Configuration

3.1 Find Ubuntu IP Address

# Method 1: Using ip command (preferred)
ip addr show

# Method 2: Using hostname command
hostname -I

# Method 3: Using ifconfig (if available)
ifconfig

Note the IP address (typically 192.168.x.x for local networks).

3.2 Configure Firewall (If Enabled)

# Check firewall status
sudo ufw status

# Allow SSH through firewall
sudo ufw allow ssh
# or for custom port
sudo ufw allow 2222/tcp

# Enable firewall (if not already enabled)
sudo ufw enable

3.3 Set Static IP (Optional)

For consistent connections, consider setting a static IP:

# Edit netplan configuration
sudo nano /etc/netplan/00-installer-config.yaml

Example static IP configuration:

network:
  ethernets:
    enp0s3:  # Replace with your interface name
      dhcp4: false
      addresses:
        - 192.168.1.100/24
      gateway4: 192.168.1.1
      nameservers:
        addresses: [8.8.8.8, 8.8.4.4]
  version: 2

Apply configuration:

sudo netplan apply

4. SSH Key Setup

4.1 Generate SSH Key Pair (Local Machine)

On Linux/macOS:

# Generate SSH key pair
ssh-keygen -t rsa -b 4096 -C "your_email@example.com"

# Follow prompts:
# - Press Enter for default file location (~/.ssh/id_rsa)
# - Enter passphrase (optional but recommended)
# - Confirm passphrase

On Windows:

# Generate SSH key pair
ssh-keygen -t rsa -b 4096 -C "your_email@example.com"

# Default location: C:\Users\<username>\.ssh\id_rsa

4.2 Copy Public Key to Ubuntu

Method 1: Using ssh-copy-id (Linux/macOS)

ssh-copy-id username@ubuntu_ip_address

Method 2: Manual copy (All platforms)

Display your public key:

# Linux/macOS
cat ~/.ssh/id_rsa.pub

# Windows
type C:\Users\<username>\.ssh\id_rsa.pub

Copy key to Ubuntu:

# Connect to Ubuntu
ssh username@ubuntu_ip_address

# Create .ssh directory (if it doesn't exist)
mkdir -p ~/.ssh

# Create/edit authorized_keys file
nano ~/.ssh/authorized_keys

# Paste your public key into this file
# Save and exit (Ctrl+X, Y, Enter)

# Set proper permissions
chmod 700 ~/.ssh
chmod 600 ~/.ssh/authorized_keys

4.3 Test SSH Connection

# Test connection (should not require password)
ssh username@ubuntu_ip_address

# Exit remote session
exit

SSH Key Security

• Use a passphrase for your private key
• Store your private key securely
• Never share your private key
• Regularly rotate SSH keys

5. Configure VS Code SSH Connection

5.1 Connect via Command Palette

1. Open VS Code
2. Press Ctrl+Shift+P (Cmd+Shift+P on macOS)
3. Type "Remote-SSH: Connect to Host"
4. Enter: username@ubuntu_ip_address
5. Select the platform (Linux)
6. VS Code will install the server components automatically

5.2 Create SSH Config File

For easier connection management, create an SSH config file:

Location:

• Linux/macOS: ~/.ssh/config
• Windows: C:\Users\<username>\.ssh\config

Example configuration:

# Ubuntu Development Server
Host ubuntu-dev
    HostName 192.168.1.100
    User your_username
    Port 22
    IdentityFile ~/.ssh/id_rsa
    ServerAliveInterval 60
    ServerAliveCountMax 3

# Multiple servers example
Host production-server
    HostName 10.0.0.50
    User deploy
    Port 2222
    IdentityFile ~/.ssh/production_key

Host staging-server
    HostName staging.example.com
    User developer
    ProxyJump bastion-host

Using SSH config:

1. Open Command Palette (Ctrl+Shift+P)
2. Type "Remote-SSH: Connect to Host"
3. Select "ubuntu-dev" from the list

5.3 Advanced SSH Configuration

For improved performance and reliability:

Host *
    # Keep connections alive
    ServerAliveInterval 60
    ServerAliveCountMax 3
    
    # Enable connection sharing
    ControlMaster auto
    ControlPath ~/.ssh/control-%r@%h:%p
    ControlPersist 600
    
    # Enable compression
    Compression yes
    
    # Speed up connections
    TCPKeepAlive yes

6. VS Code Remote Development

6.1 First Connection

1. Connect to your remote host
2. VS Code will automatically install the VS Code Server
3. Wait for the installation to complete
4. You'll see "SSH: hostname" in the bottom-left corner

6.2 Working with Remote Files

# Open a folder
Ctrl+K Ctrl+O

# Open terminal on remote machine
Ctrl+` (backtick)

# File explorer shows remote files
# All extensions run on the remote machine

6.3 Install Extensions on Remote

Extensions need to be installed separately for remote development:

1. Go to Extensions view (Ctrl+Shift+X)
2. You'll see separate sections:
   • Local - Installed: Extensions on your local machine
   • SSH: hostname - Installed: Extensions on remote machine
3. Install needed extensions in the remote section

Recommended remote extensions:

• Language support for your stack (Python, Node.js, etc.)
• GitLens
• Bracket Pair Colorizer
• File icons

6.4 Port Forwarding

Forward ports from remote machine to local:

1. Open Command Palette (Ctrl+Shift+P)
2. Type "Remote-SSH: Forward Port from Active Host"
3. Enter remote port number
4. Access via localhost:port on your local machine

Example: Forward web server on port 8000:

• Remote server runs on port 8000
• Forward to local port 8000
• Access via http://localhost:8000

7. Troubleshooting

7.1 Connection Issues

"Connection Refused" Error

# Check SSH service status
sudo systemctl status ssh

# Restart SSH service
sudo systemctl restart ssh

# Check if port is open
sudo ss -tlnp | grep :22

# Check firewall
sudo ufw status

"Permission Denied" Error

# Check SSH key permissions
ls -la ~/.ssh/

# Fix permissions
chmod 700 ~/.ssh
chmod 600 ~/.ssh/authorized_keys
chmod 600 ~/.ssh/id_rsa
chmod 644 ~/.ssh/id_rsa.pub

"Host Key Verification Failed"

# Remove old host key
ssh-keygen -R ubuntu_ip_address

# Connect again to add new host key
ssh username@ubuntu_ip_address

7.2 Performance Issues

Slow Connection

# Enable compression in SSH config
Host your-host
    Compression yes
    TCPKeepAlive yes
    ServerAliveInterval 60

High CPU Usage

• Disable unnecessary extensions on remote
• Use lightweight themes
• Limit file watchers for large projects

7.3 VS Code Server Issues

Reset VS Code Server

# On remote machine, remove VS Code Server
rm -rf ~/.vscode-server

# Reconnect from VS Code to reinstall

Update VS Code Server

VS Code Server updates automatically, but you can force update:

1. Disconnect from remote
2. Update VS Code locally
3. Reconnect to remote

7.4 Debug Connection Issues

# Verbose SSH connection
ssh -v username@ubuntu_ip_address

# Check SSH logs on Ubuntu
sudo tail -f /var/log/auth.log

# Test SSH config
ssh -F ~/.ssh/config -T ubuntu-dev

8. Best Practices

8.1 Security Best Practices

1. Use SSH keys instead of passwords
2. Change default SSH port
3. Disable root login
4. Use fail2ban for intrusion prevention
5. Keep systems updated

# Install fail2ban
sudo apt install fail2ban

# Basic fail2ban configuration
sudo nano /etc/fail2ban/jail.local

Example fail2ban configuration:

[sshd]
enabled = true
port = ssh
filter = sshd
logpath = /var/log/auth.log
maxretry = 3
bantime = 3600

8.2 Development Workflow

1. Use version control: Always use Git for your projects
2. Backup regularly: Set up automated backups
3. Environment consistency: Use containers or virtual environments
4. Documentation: Document your setup and configurations

8.3 Performance Optimization

# Optimize SSH connection
Host *
    ControlMaster auto
    ControlPath ~/.ssh/control-%r@%h:%p
    ControlPersist 600
    Compression yes

9. Advanced Features

9.1 Multi-hop SSH Connections

# Connect through a bastion host
Host production-server
    HostName 10.0.0.100
    User developer
    ProxyJump bastion-host

Host bastion-host
    HostName bastion.example.com
    User admin

9.2 SSH Agent Forwarding

# Enable agent forwarding
Host ubuntu-dev
    HostName 192.168.1.100
    User developer
    ForwardAgent yes

9.3 X11 Forwarding for GUI Apps

# Enable X11 forwarding
Host ubuntu-dev
    HostName 192.168.1.100
    User developer
    ForwardX11 yes
    ForwardX11Trusted yes

Resources

• VS Code Remote Development
• SSH Configuration Guide
• OpenSSH Manual
• VS Code Remote SSH Tips

Pro Tips

• Use SSH config files for managing multiple connections
• Set up SSH agent for password-less key access
• Use VS Code settings sync to maintain consistent configuration
• Consider using tmux or screen for persistent sessions

Security Reminder

Always follow security best practices when setting up remote access. Use strong authentication, keep systems updated, and monitor access logs regularly.