SSH Key Authentication for VSCode Remote Development

Eliminate the need to repeatedly enter passwords when using VSCode's Remote-SSH extension by setting up secure SSH key authentication.

Why Password-Based SSH is Inefficient

Using password authentication for SSH connections in VSCode requires manual input each time you connect to a remote host. This interrupts workflow and reduces productivity. More importantly, SSH keys provide a more secure authentication method than passwords.

Security Notice

Storing SSH passwords in plaintext (as some insecure workarounds suggest) creates significant security vulnerabilities. SSH key authentication is the recommended approach.

SSH Key Authentication: The Standard Solution

SSH key authentication uses a pair of cryptographic keys instead of passwords:

• Private key: Stored on your local machine (never shared)
• Public key: Added to the remote server's authorized keys

Step 1: Generate SSH Key Pair

Open your terminal and run:

ssh-keygen -t ed25519 -b 4096

For broader compatibility, you can use RSA:

ssh-keygen -t rsa -b 4096

During generation:

• Accept the default location (~/.ssh/id_ed25519 or ~/.ssh/id_rsa)
• Set a strong passphrase for additional security

TIP

Using a passphrase encrypts your private key, requiring it to be entered only once per session when using an SSH agent.

Step 2: Configure SSH Client

Edit or create your SSH config file at ~/.ssh/config:

Host my-remote-server
  HostName server.example.com
  User your-username
  Port 22
  IdentityFile ~/.ssh/id_ed25519
  PreferredAuthentications publickey

Replace my-remote-server with a nickname for your connection, and update the other values accordingly.

Step 3: Copy Public Key to Remote Server

Use ssh-copy-id for easy key deployment:

ssh-copy-id -i ~/.ssh/id_ed25519.pub your-username@server.example.com

You'll be prompted for your password one final time.

Alternatively, manually copy the public key:

# Display your public key
cat ~/.ssh/id_ed25519.pub

# On remote server, add to authorized_keys
echo "public-key-content" >> ~/.ssh/authorized_keys

Step 4: Set Proper Permissions

On the remote server, ensure correct permissions:

chmod 700 ~/.ssh
chmod 600 ~/.ssh/authorized_keys

Step 5: Test Connection

Verify your setup works without a password:

ssh your-username@server.example.com

Setting Up SSH Agent for Passphrase Caching

If you used a passphrase with your key, set up SSH agent to cache it:

Windows

Enable SSH Agent service:

# Set service to start automatically
Set-Service -Name ssh-agent -StartupType Automatic

# Start the service
Start-Service ssh-agent

# Add your key
ssh-add ~/.ssh/id_ed25519

macOS

Add to your ~/.zshrc or ~/.bashrc:

# Start ssh-agent and add key
eval "$(ssh-agent -s)"
ssh-add --apple-use-keychain ~/.ssh/id_ed25519

Linux

Add to your shell configuration:

eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_ed25519

VSCode-Specific Configuration

Once SSH keys are configured, VSCode's Remote-SSH extension will automatically use them:

1. Open VSCode Command Palette (Ctrl+Shift+P / Cmd+Shift+P)
2. Select "Remote-SSH: Connect to Host"
3. Choose your configured host nickname

VSCode SSH Settings

You can customize SSH behavior in VSCode settings:

• remote.SSH.path: Custom SSH executable path
• remote.SSH.configFile: Custom SSH config file location

Troubleshooting Common Issues

Permission Errors

Ensure proper file permissions:

# Local machine
chmod 700 ~/.ssh
chmod 600 ~/.ssh/id_ed25519
chmod 644 ~/.ssh/id_ed25519.pub
chmod 644 ~/.ssh/config
chmod 644 ~/.ssh/known_hosts

# Remote server
chmod 700 ~/.ssh
chmod 600 ~/.ssh/authorized_keys

Connection Refused

Check if SSH is running on the remote server:

# On remote server
sudo systemctl status sshd

Authentication Still Failing

Enable verbose logging to diagnose issues:

ssh -v your-username@server.example.com

Alternative Methods (With Caveats)

While not recommended as primary solutions, these alternatives exist:

SSH Config with ControlMaster

Add to your SSH config for persistent connections:

Host *
  ControlMaster auto
  ControlPath ~/.ssh/sockets/%r@%h-%p
  ControlPersist 600

Third-Party Tools

• Windows: SSH Config Editor apps
• Multi-platform: Tailscale SSH (automates key management)

Insecure Methods

Avoid solutions that store passwords in plaintext (like sshpass scripts), as they create significant security risks.

Best Practices for SSH Security

1. Use ED25519 keys when possible (more secure than RSA)
2. Always use passphrases with private keys
3. Regularly rotate keys (every 6-12 months)
4. Use different keys for different services
5. Disable password authentication on servers when possible

Conclusion

SSH key authentication provides a secure, convenient way to connect to remote hosts from VSCode without repeatedly entering passwords. While the initial setup requires several steps, the long-term productivity gains and enhanced security make it well worth the effort.

For most developers, the standard SSH key approach with passphrase caching via SSH agent offers the best balance of security and convenience for VSCode remote development.