Skip to content
Login Changemaker Archive. Learn more

# Remote Development with VSCode over Tailscale

## Overview

This guide describes how to set up Visual Studio Code for remote development on servers using the Tailscale network. This enables development directly on remote machines as if they were local, with full access to files, terminals, and debugging capabilities.

## What You'll Learn

- How to configure VSCode for remote SSH connections
- How to set up remote development environments
- How to manage multiple remote servers efficiently
- How to troubleshoot common remote development issues
- Best practices for remote development workflows

## Prerequisites

- Ansible + Tailscale setup completed (see previous guide)
- VSCode installed on the local machine (master node)
- Working SSH access to remote servers via Tailscale
- Tailscale running on both local and remote machines

## Verify Prerequisites

Before starting, verify the setup:

    # Check Tailscale connectivity
    tailscale status

    # Test SSH access
    ssh <username>@<tailscale-ip>

    # Check VSCode is installed
    code --version

## Part 1: Install and Configure Remote-SSH Extension

### 1. Install the Remote Development Extensions

Option A: Install Remote Development Pack (Recommended)

1. Open VSCode
2. Press Ctrl+Shift+X (or Cmd+Shift+X on Mac)
3. Search for "Remote Development"
4. Install the Remote Development extension pack by Microsoft

This pack includes:

- Remote - SSH
- Remote - SSH: Editing Configuration Files
- Remote - Containers
- Remote - WSL (Windows only)

Option B: Install Individual Extension

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

### 2. Verify Installation

After installation, the following should be visible:

- Remote Explorer icon in the Activity Bar (left sidebar)
- "Remote-SSH" commands in Command Palette (Ctrl+Shift+P)

## Part 2: Configure SSH Connections

### 1. Access SSH Configuration

Method A: Through VSCode

1. Press Ctrl+Shift+P to open Command Palette
2. Type "Remote-SSH: Open SSH Configuration File..."
3. Select the SSH config file (usually the first option)

Method B: Direct File Editing

    # Edit SSH config file directly
    nano ~/.ssh/config

### 2. Add Server Configurations

Add servers to the SSH config file:

    # Example Node
    Host node1
        HostName <tailscale-ip>
        User <username>
        IdentityFile ~/.ssh/id_rsa
        ForwardAgent yes
        ServerAliveInterval 60
        ServerAliveCountMax 3

    # Additional nodes (add as needed)
    Host node2
        HostName <tailscale-ip>
        User <username>
        IdentityFile ~/.ssh/id_rsa
        ForwardAgent yes
        ServerAliveInterval 60
        ServerAliveCountMax 3

Configuration Options Explained:

- `Host`: Friendly name for the connection
- `HostName`: Tailscale IP address
- `User`: Username on the remote server
- `IdentityFile`: Path to the SSH private key
- `ForwardAgent`: Enables SSH agent forwarding for Git operations
- `ServerAliveInterval`: Keeps connection alive (prevents timeouts)
- `ServerAliveCountMax`: Number of keepalive attempts

### 3. Set Proper SSH Key Permissions

    # Ensure SSH config has correct permissions
    chmod 600 ~/.ssh/config

    # Verify SSH key permissions
    chmod 600 ~/.ssh/id_rsa
    chmod 644 ~/.ssh/id_rsa.pub

## Part 3: Connect to Remote Servers

### 1. Connect via Command Palette

1. Press Ctrl+Shift+P
2. Type "Remote-SSH: Connect to Host..."
3. Select the server (e.g., `node1`)
4. VSCode will open a new window connected to the remote server

### 2. Connect via Remote Explorer

1. Click the Remote Explorer icon in Activity Bar
2. Expand SSH Targets
3. Click the connect icon next to the server name

### 3. Connect via Quick Menu

1. Click the remote indicator in bottom-left corner (looks like ><)
2. Select "Connect to Host..."
3. Choose the server from the list

### 4. First Connection Process

On first connection, VSCode will:

1. Verify the host key (click "Continue" if prompted)
2. Install VSCode Server on the remote machine (automatic)
3. Open a remote window with access to the remote file system

Expected Timeline: - First connection: 1-3 minutes (installs VSCode Server) - Subsequent connections: 10-30 seconds

## Part 4: Remote Development Environment Setup

### 1. Open Remote Workspace

Once connected:

    # In the VSCode terminal (now running on remote server)
    # Navigate to the project directory
    cd /home/<username>/projects

    # Open current directory in VSCode
    code .

    # Or open a specific project
    code /opt/myproject

### 2. Install Extensions on Remote Server

Extensions must be installed separately on the remote server:

Essential Development Extensions:

1. Python (Microsoft) - Python development
2. GitLens (GitKraken) - Enhanced Git capabilities
3. Docker (Microsoft) - Container development
4. Prettier - Code formatting
5. ESLint - JavaScript linting
6. Auto Rename Tag - HTML/XML tag editing

To Install:

1. Go to Extensions (Ctrl+Shift+X)
2. Find the desired extension
3. Click "Install in SSH: node1" (not local install)

### 3. Configure Git on Remote Server

    # In VSCode terminal (remote)
    git config --global user.name "<Full Name>"
    git config --global user.email "<email@example.com>"

    # Test Git connectivity
    git clone https://github.com/<username>/<repo>.git

## Part 5: Remote Development Workflows

### 1. File Management

File Explorer:

- Shows remote server's file system
- Create, edit, delete files directly
- Drag and drop between local and remote (limited)

File Transfer:

    # Upload files to remote (from local terminal)
    scp localfile.txt <username>@<tailscale-ip>:/home/<username>/

    # Download files from remote
    scp <username>@<tailscale-ip>:/remote/path/file.txt ./local/path/

### 2. Terminal Usage

Integrated Terminal:

- Press Ctrl+` to open terminal
- Runs directly on remote server
- Multiple terminals supported
- Full shell access (bash, zsh, etc.)

Common Remote Terminal Commands:

    # Check system resources
    htop
    df -h
    free -h

    # Install packages
    sudo apt update
    sudo apt install nodejs npm

    # Start services
    sudo systemctl start nginx
    sudo docker-compose up -d

### 3. Port Forwarding

Automatic Port Forwarding: VSCode automatically detects and forwards common development ports.

Manual Port Forwarding:

1. Open Ports tab in terminal panel
2. Click "Forward a Port"
3. Enter port number (e.g., 3000, 8080, 5000)
4. Access via `http://localhost:port` on the local machine

Example: Web Development

    # Start a web server on remote (port 3000)
    npm start

    # VSCode automatically suggests forwarding port 3000
    # Access at http://localhost:3000 on the local machine

### 4. Debugging Remote Applications

Python Debugging:

    // .vscode/launch.json on remote server
    {
        "version": "0.2.0",
        "configurations": [
            {
                "name": "Python: Current File",
                "type": "python",
                "request": "launch",
                "program": "${file}",
                "console": "integratedTerminal"
            }
        ]
    }

Node.js Debugging:

    // .vscode/launch.json
    {
        "version": "0.2.0",
        "configurations": [
            {
                "name": "Launch Program",
                "type": "node",
                "request": "launch",
                "program": "${workspaceFolder}/app.js"
            }
        ]
    }

## Part 6: Advanced Configuration

### 1. Workspace Settings

Create remote-specific settings:

    // .vscode/settings.json (on remote server)
    {
        "python.defaultInterpreterPath": "/usr/bin/python3",
        "terminal.integrated.shell.linux": "/bin/bash",
        "files.autoSave": "afterDelay",
        "editor.formatOnSave": true,
        "remote.SSH.remotePlatform": {
            "node1": "linux"
        }
    }

### 2. Multi-Server Management

Switch Between Servers:

1. Click remote indicator (bottom-left)
2. Select "Connect to Host..."
3. Choose a different server

Compare Files Across Servers:

1. Open file from server A
2. Connect to server B in new window
3. Open corresponding file
4. Use "Compare with..." command

### 3. Sync Configuration

Settings Sync:

1. Enable Settings Sync in VSCode
2. Settings, extensions, and keybindings sync to remote
3. Consistent experience across all servers

## Part 7: Project-Specific Setups

### 1. Python Development

    # On remote server
    # Create virtual environment
    python3 -m venv venv
    source venv/bin/activate

    # Install packages
    pip install flask django requests

    # VSCode automatically detects Python interpreter

VSCode Python Configuration:

    // .vscode/settings.json
    {
        "python.defaultInterpreterPath": "./venv/bin/python",
        "python.linting.enabled": true,
        "python.linting.pylintEnabled": true
    }

### 2. Node.js Development

    # On remote server
    # Install Node.js
    curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
    sudo apt-get install -y nodejs

    # Create project
    mkdir myapp && cd myapp
    npm init -y
    npm install express

### 3. Docker Development

    # On remote server
    # Install Docker (if not already done via Ansible)
    sudo apt install docker.io docker-compose
    sudo usermod -aG docker $USER

    # Create Dockerfile
    cat > Dockerfile << EOF
    FROM node:18
    WORKDIR /app
    COPY package*.json ./
    RUN npm install
    COPY . .
    EXPOSE 3000
    CMD ["npm", "start"]
    EOF

VSCode Docker Integration:

- Install Docker extension on remote
- Right-click Dockerfile → "Build Image"
- Manage containers from VSCode interface

## Part 8: Troubleshooting Guide

### Common Connection Issues

Problem: "Could not establish connection to remote host"

Solutions:

    # Check Tailscale connectivity
    tailscale status
    ping <tailscale-ip>

    # Test SSH manually
    ssh <username>@<tailscale-ip>

    # Check SSH config syntax
    ssh -T node1

Problem: "Permission denied (publickey)"

Solutions:

    # Check SSH key permissions
    chmod 600 ~/.ssh/id_rsa
    chmod 600 ~/.ssh/config

    # Verify SSH agent
    ssh-add ~/.ssh/id_rsa
    ssh-add -l

    # Test SSH connection verbosely
    ssh -v <username>@<tailscale-ip>

Problem: "Host key verification failed"

Solutions:

    # Remove old host key
    ssh-keygen -R <tailscale-ip>

    # Or disable host key checking (less secure)
    # Add to SSH config:
    # StrictHostKeyChecking no

### VSCode-Specific Issues

Problem: Extensions not working on remote

Solutions:

1. Install extensions specifically for the remote server
2. Check extension compatibility with remote development
3. Reload VSCode window: Ctrl+Shift+P → "Developer: Reload Window"

Problem: Slow performance

Solutions: - Use `.vscode/settings.json` to exclude large directories:

    {
        "files.watcherExclude": {
            "**/node_modules/**": true,
            "**/.git/objects/**": true,
            "**/dist/**": true
        }
    }

Problem: Terminal not starting

Solutions:

    # Check shell path in remote settings
    "terminal.integrated.shell.linux": "/bin/bash"

    # Or let VSCode auto-detect
    "terminal.integrated.defaultProfile.linux": "bash"

### Network and Performance Issues

Problem: Connection timeouts

Solutions: Add to SSH config:

    ServerAliveInterval 60
    ServerAliveCountMax 3
    TCPKeepAlive yes

Problem: File transfer slow

Solutions: - Use `.vscodeignore` to exclude unnecessary files - Compress large files before transfer - Use `rsync` for large file operations:

    rsync -avz --progress localdir/ <username>@<tailscale-ip>:remotedir/

## Part 9: Best Practices

### Security Best Practices

1. Use SSH keys, never passwords
2. Keep SSH agent secure
3. Regular security updates on remote servers
4. Use VSCode's secure connection verification

### Performance Optimization

1. Exclude unnecessary files:

       // .vscode/settings.json
       {
           "files.watcherExclude": {
               "**/node_modules/**": true,
               "**/.git/**": true,
               "**/dist/**": true,
               "**/build/**": true
           },
           "search.exclude": {
               "**/node_modules": true,
               "**/bower_components": true,
               "**/*.code-search": true
           }
       }

2. Use remote workspace for large projects

3. Close unnecessary windows and extensions
4. Use efficient development workflows

### Development Workflow

1. Use version control effectively:

       # Always work in Git repositories
       git status
       git add .
       git commit -m "feature: add new functionality"
       git push origin main

2. Environment separation:

       # Development
       ssh node1
       cd /home/<username>/dev-projects

       # Production
       ssh node2
       cd /opt/production-apps

3. Backup important work:

       # Regular backups via Git
       git push origin main

       # Or manual backup
       scp -r <username>@<tailscale-ip>:/important/project ./backup/

## Part 10: Team Collaboration

### Shared Development Servers

SSH Config for Team:

    # Shared development server
    Host team-dev
        HostName <tailscale-ip>
        User <team-user>
        IdentityFile ~/.ssh/team_dev_key
        ForwardAgent yes

    # Personal development
    Host my-dev
        HostName <tailscale-ip>
        User <username>
        IdentityFile ~/.ssh/id_rsa

### Project Structure

    /opt/projects/
    ├── project-a/
    │   ├── dev/          # Development branch
    │   ├── staging/      # Staging environment
    │   └── docs/         # Documentation
    ├── project-b/
    └── shared-tools/     # Common utilities

### Access Management

    # Create shared project directory
    sudo mkdir -p /opt/projects
    sudo chown -R :developers /opt/projects
    sudo chmod -R g+w /opt/projects

    # Add users to developers group
    sudo usermod -a -G developers <username>

## Quick Reference

### Essential VSCode Remote Commands

    # Command Palette shortcuts
    Ctrl+Shift+P → "Remote-SSH: Connect to Host..."
    Ctrl+Shift+P → "Remote-SSH: Open SSH Configuration File..."
    Ctrl+Shift+P → "Remote-SSH: Kill VS Code Server on Host..."

    # Terminal
    Ctrl+` → Open integrated terminal
    Ctrl+Shift+` → Create new terminal

    # File operations
    Ctrl+O → Open file
    Ctrl+S → Save file
    Ctrl+Shift+E → Focus file explorer

### SSH Connection Quick Test

    # Test connectivity
    ssh -T node1

    # Connect with verbose output
    ssh -v <username>@<tailscale-ip>

    # Check SSH config
    ssh -F ~/.ssh/config node1

### Port Forwarding Commands

    # Manual port forwarding
    ssh -L 3000:localhost:3000 <username>@<tailscale-ip>

    # Background tunnel
    ssh -f -N -L 8080:localhost:80 <username>@<tailscale-ip>

## Conclusion

This remote development setup provides:

- Full development environment on remote servers
- Seamless file access and editing capabilities
- Integrated debugging and terminal access
- Port forwarding for web development
- Extension ecosystem available remotely
- Secure connections through Tailscale network

The combination of VSCode Remote Development with Tailscale networking creates a powerful, flexible development environment that works from anywhere while maintaining security and performance.

Whether developing Python applications, Node.js services, or managing Docker containers, this setup provides a professional remote development experience that rivals local development while leveraging the power and resources of remote servers.