As a developer, you want the best tools for the job. You love the sleekness and Unix-based environment of your MacBook Air, but you also have a powerhouse Windows 11 Pro desktop. How do you get the best of both worlds? How can you use your Mac to develop inside a full-fledged Linux environment running on your Windows machine?

The answer lies in a powerful combination: Windows Subsystem for Linux (WSL2), SSH, and VS Code’s Remote Development extension.

This guide will walk you through the entire process, from setting up WSL2 on your Windows machine to seamlessly connecting and coding from your MacBook. We’ll cover the manual setup so you understand the mechanics, and then show you how to automate the process to handle common issues like changing IP addresses.

The Big Picture: How Does This Work?

Before we dive in, let’s understand the architecture. Your MacBook can’t directly “see” the Linux instance running inside WSL2, as it lives in its own virtual network on your Windows machine. We need to create a bridge.

  1. WSL2 Ubuntu: Runs a full Linux environment with its own private IP address. We’ll install an SSH server here.
  2. Windows 11 Pro: Acts as the host. We will configure it to forward traffic from one of its network ports to the SSH port on the WSL2 instance.
  3. Your MacBook: Will connect via SSH to your Windows machine’s IP address on the special forwarded port, which Windows will then transparently route to WSL2.

Part 1: Setting Up the Host (Windows 11 Pro)

First, we need to get WSL2 and our Ubuntu environment ready to accept connections.

Step 1: Install WSL2 and Ubuntu

If you haven’t already, installing WSL2 and the default Ubuntu distribution is a one-line command. Open PowerShell as an Administrator and run:

wsl --install -d Ubuntu

This command will enable the necessary Windows features (Virtual Machine Platform, Windows Subsystem for Linux), download the latest Linux kernel, and install the Ubuntu distribution. Restart your computer if prompted.

Step 2: Configure the Ubuntu SSH Server

Once installed, launch your new Ubuntu environment from the Start Menu. Now, let’s set up the SSH server inside it.

  1. Update and Install OpenSSH Server: It’s always good practice to update your package lists before installing new software.

    # Inside the Ubuntu WSL2 terminal
sudo apt update
sudo apt install openssh-server

  2. Start and Enable the SSH Service: We need to start the SSH service and ensure it launches automatically every time WSL2 starts.

    sudo service ssh start
   
# Optional but recommended: enable the service to start on boot
sudo systemctl enable ssh

    You can verify it’s running with sudo service ssh status.

Step 3: Create the Network Bridge (Port Forwarding)

This is the most critical step. We need to tell Windows to forward traffic to our WSL2 instance.

  1. Find the WSL2 IP Address: Your WSL2 instance has a dynamic IP address that can change each time it restarts. Find the current one by running this command inside the Ubuntu terminal:

    # This will print the IP address, e.g., 172.28.17.73
hostname -I

    Take note of this IP address. For our example, we’ll use 172.28.17.73.

  2. Set Up Port Forwarding in PowerShell: Exit the Ubuntu terminal and go back to a PowerShell window running as Administrator. We will forward port 2222 on Windows to port 22 (the default SSH port) on our WSL2 instance.

    Note: Replace 172.28.17.73 with the IP address you found in the previous step.

    # In an Administrator PowerShell
netsh interface portproxy add v4tov4 listenport=2222 listenaddress=0.0.0.0 connectport=22 connectaddress=172.28.17.73

  3. Create a Firewall Rule: Windows Firewall will block the new port by default. Let’s create a rule to allow incoming traffic on port 2222.

    # In the same Administrator PowerShell
New-NetFirewallRule -DisplayName "WSL2 SSH Bridge" -Direction Inbound -LocalPort 2222 -Protocol TCP -Action Allow

Your Windows host is now ready!

Part 2: Connecting From Your MacBook

Now for the fun part. Let’s connect from your MacBook using VS Code.

Step 1: Find Your Windows IP Address

You need the local network IP of your Windows machine. On the Windows PC, open a regular Command Prompt or PowerShell and run:

ipconfig

Look for the “IPv4 Address” under your active Wi-Fi or Ethernet adapter. It will likely look something like 192.168.0.113.

Step 2: Connect with VS Code Remote-SSH

On your MacBook, make sure you have the Remote Development extension pack installed in VS Code.

  1. Open VS Code and press Cmd+Shift+P to open the Command Palette.
  2. Type Remote-SSH: Add New SSH Host... and press Enter.

  3. Enter the connection command using your WSL Ubuntu username, your Windows IP, and the forwarded port (2222).

    # Format: ssh <wsl-username>@<windows-ip> -p 2222
# Example:
ssh jboldsenryan@192.168.0.113 -p 2222
  4. Choose the first option to update your SSH config file (~/.ssh/config).
  5. Now, connect! Press Cmd+Shift+P again and select Remote-SSH: Connect to Host....
  6. Choose the host you just added (e.g., 192.168.0.113).
  7. The first time you connect, you’ll be asked to confirm the server’s fingerprint (type yes) and then enter the password for your Ubuntu user. VS Code will then install its server components in WSL2.

That’s it! Your VS Code window is now running remotely inside WSL2. The integrated terminal is a full Ubuntu shell, and any files you open are on the Linux filesystem.

Your Daily Workflow & Troubleshooting

The initial setup is done once. Here’s what your daily use looks like.

Daily Workflow:

  1. On Windows: Make sure your WSL2 instance is running. You can start it with wsl -d Ubuntu.
  2. On MacBook: Open VS Code, go to the Remote Explorer tab, and click the connect icon next to your saved host.

Troubleshooting Common Issues

1. Connection Refused? This usually means the SSH server isn’t running in WSL2 or WSL2 itself is shut down.

  • On Windows: Check WSL status with wsl --list --verbose.
  • In WSL2: Start the SSH server with sudo service ssh start.

2. The WSL IP Address Changed! This is the most common problem. After a reboot of your Windows PC, WSL2 will likely get a new IP address, breaking your port forwarding rule.

  • Solution:
    1. Get the new WSL2 IP with hostname -I.
    2. On Windows (in an Admin PowerShell), remove the old rule and add the new one: 
      # Get the new IP first! Let's say it's now 172.28.20.55
netsh interface portproxy delete v4tov4 listenport=2222 listenaddress=0.0.0.0
netsh interface portproxy add v4tov4 listenport=2222 listenaddress=0.0.0.0 connectport=22 connectaddress=172.28.20.55

Level Up: Automate the IP Problem

Manually updating the IP is tedious. I’ve created a set of PowerShell scripts to automate this entire process. The main script, setup-wsl2-ssh.ps1, can automatically detect the WSL2 IP and update the port forwarding rule for you.

If you have these scripts, you can fix a changed IP by simply running this on Windows:

# Run PowerShell as Administrator
.\setup-wsl2-ssh.ps1

This single command finds the current IP, sets the port forward, and configures the firewall, making maintenance a breeze!

📥 Download the Automation Scripts

I’ve created practical scripts to automate this entire process. You can download them directly:

Essential Scripts

Quick Start with Scripts

  1. Download and run the main setup script: 
    # In PowerShell as Administrator (Windows)
.\setup-wsl2-ssh.ps1
  2. When WSL2 IP changes (after restarts): 
    # Quick IP update (Windows)
.\update-wsl2-ip.ps1
  3. Connect from Mac/Linux: 
    # Make executable and run (Mac/Linux)
chmod +x connect-wsl2.sh
./connect-wsl2.sh

The scripts handle error checking, provide colored output, and can recover from most common issues automatically.

Conclusion

You now have a professional-grade, cross-platform development environment. You can leverage the raw power of your Windows machine to run Linux containers, build heavy projects, and run backend services, all while enjoying the fluid user experience of your MacBook Air. By understanding the manual steps and leveraging automation for maintenance, you’ve created a workflow that is both powerful and sustainable.

Happy coding! 🚀