Use Dev Proxy with WSL

At a glance
Goal: Use Dev Proxy with Windows Subsystem for Linux (WSL)
Time: 15 minutes
Prerequisites: Set up Dev Proxy, WSL installed

When developing applications in WSL (Windows Subsystem for Linux), you have two options for using Dev Proxy: running it on your Windows host or inside WSL. Both approaches have their advantages depending on your development workflow.

Option 1: Dev Proxy on Windows host (recommended)

The simplest approach is to install and run Dev Proxy on Windows. With WSL's Auto Proxy and mirrored networking mode, WSL uses the Windows system proxy, so applications running in WSL have their traffic intercepted by Dev Proxy without configuring the proxy in WSL.

Configure WSL networking

Dev Proxy registers itself as the Windows system proxy on a localhost address (127.0.0.1:8000 by default). For applications in WSL to use this proxy, enable the following settings in the [wsl2] section of the WSL configuration file located at %UserProfile%\.wslconfig on Windows:

[wsl2]
networkingMode=mirrored
autoProxy=true

Setting	Description
networkingMode=mirrored	Mirrors the Windows network interfaces into Linux, which allows applications in WSL to connect to servers running on Windows, such as Dev Proxy, using 127.0.0.1. Requires Windows 11 version 22H2 or later. The default value is nat.
autoProxy=true	Makes WSL use the Windows HTTP proxy settings, so that the proxy configured on Windows is automatically set in WSL. Available on Windows 11. Enabled by default.

After you change the .wslconfig file, restart WSL for the changes to take effect:

wsl --shutdown

Note

In the default NAT networking mode, applications in WSL can't connect to Dev Proxy on Windows using 127.0.0.1. If you can't use mirrored networking mode, run Dev Proxy inside WSL instead. For more information, see Option 2: Dev Proxy inside WSL.

For more information, see Accessing network applications with WSL and Advanced settings configuration in WSL.

Set up Dev Proxy on Windows

1. Install Dev Proxy on Windows using winget or manual installation.

2. Start Dev Proxy:

   devproxy
   

3. Trust the certificate when prompted.

Use Dev Proxy from WSL

When Dev Proxy runs as the system proxy on Windows (the default behavior) and you configured WSL networking, applications in WSL automatically route their traffic through it.

Start your application in WSL as you normally would. Dev Proxy intercepts HTTPS requests made by applications that respect the proxy settings.

Important

Restart WSL after starting or stopping Dev Proxy

WSL reads the Windows proxy settings when it starts. If you start Dev Proxy after WSL is already running, or if you stop and restart Dev Proxy, you need to restart WSL for the changes to take effect:

wsl --shutdown

Then start a new WSL session.

Trust the certificate in WSL

For Dev Proxy to intercept HTTPS traffic, applications in WSL need to trust the Dev Proxy certificate. You can either copy the certificate from Windows or export it using the Dev Proxy API.

Option A: Copy the certificate from Windows

1. In WSL, copy the certificate from Windows:

   cp "/mnt/c/Users/<your-username>/AppData/Local/Programs/Dev Proxy/rootCert.pfx" ~/
   

2. Export and install the certificate:

   # Export the certificate
   openssl pkcs12 -in ~/rootCert.pfx -clcerts -nokeys -out dev-proxy-ca.crt -passin pass:""
   # Install the certificate
   sudo cp dev-proxy-ca.crt /usr/local/share/ca-certificates/
   # Update certificates
   sudo update-ca-certificates
   

Option B: Use the Dev Proxy API

The Dev Proxy API requires a bearer token. While Dev Proxy is running on Windows, get the token by running the api token command in a Windows terminal:

devproxy api token

Then, in WSL, download and install the certificate. Replace <token> with the token that you retrieved:

# Download the certificate from Dev Proxy API
curl -H "Authorization: Bearer <token>" -o dev-proxy-ca.crt "http://127.0.0.1:8897/proxy/rootCertificate?format=crt"
# Install the certificate
sudo cp dev-proxy-ca.crt /usr/local/share/ca-certificates/
# Update certificates
sudo update-ca-certificates

Note

Some applications might require extra configuration to trust the system certificate store. For Node.js applications, you might need to set NODE_TLS_REJECT_UNAUTHORIZED=0 for development purposes. Disabling certificate validation isn't recommended for production code.

Option 2: Dev Proxy inside WSL

If you prefer to run Dev Proxy entirely within WSL, install it using the Linux installation method and configure the proxy manually.

Install Dev Proxy in WSL

The setup script requires unzip to extract Dev Proxy. Fresh WSL distributions, like Ubuntu, don't include it by default. Install unzip:

sudo apt update
sudo apt install unzip

Install Dev Proxy using the setup script:

bash -c "$(curl -sL https://aka.ms/devproxy/setup.sh)"

Configure the proxy manually

Since WSL doesn't have a graphical desktop environment, Dev Proxy can't automatically register as the system proxy. Configure your applications to use the proxy manually.

1. Create a Dev Proxy configuration file with asSystemProxy set to false:

   {
     "$schema": "https://raw.githubusercontent.com/dotnet/dev-proxy/main/schemas/v4.0.0/rc.schema.json",
     "asSystemProxy": false,
     "plugins": [
       {
         "name": "RetryAfterPlugin",
         "enabled": true,
         "pluginPath": "~appFolder/plugins/DevProxy.Plugins.dll"
       },
       {
         "name": "GenericRandomErrorPlugin",
         "enabled": true,
         "pluginPath": "~appFolder/plugins/DevProxy.Plugins.dll",
         "configSection": "genericRandomErrorPlugin"
       }
     ],
     "urlsToWatch": [
       "https://jsonplaceholder.typicode.com/*"
     ],
     "genericRandomErrorPlugin": {
       "$schema": "https://raw.githubusercontent.com/dotnet/dev-proxy/main/schemas/v4.0.0/genericrandomerrorplugin.schema.json",
       "errorsFile": "devproxy-errors.json",
       "rate": 50
     },
     "logLevel": "information"
   }
   

2. Start Dev Proxy:

   devproxy
   

3. Trust the certificate:

   # Export Dev Proxy root certificate
   openssl pkcs12 -in ~/.config/dev-proxy/rootCert.pfx -clcerts -nokeys -out dev-proxy-ca.crt -passin pass:""
   # Install the certificate
   sudo cp dev-proxy-ca.crt /usr/local/share/ca-certificates/
   # Update certificates
   sudo update-ca-certificates
   

4. Configure your application to use the proxy. Set the HTTPS_PROXY environment variable:

   export HTTPS_PROXY=http://127.0.0.1:8000
   

   Or specify it when running your application:

   HTTPS_PROXY=http://127.0.0.1:8000 node app.js
   

Tip

For more information on configuring the proxy for Node.js applications, see Use Dev Proxy with Node.js applications.

Comparison of approaches

Feature	Windows host (Option 1)	Inside WSL (Option 2)
Setup complexity	Simple	Moderate
Requirements	Windows 11 22H2 or later, WSL mirrored networking mode	None
Certificate management	One-time copy from Windows	Manual export
Proxy configuration	Automatic (WSL Auto Proxy)	Manual (HTTPS_PROXY)
WSL restart required	Yes, when toggling proxy	No
Works with all WSL apps	Yes	Depends on app proxy support

For most scenarios, running Dev Proxy on Windows (Option 1) is the recommended approach due to its simplicity and automatic proxy configuration.

Troubleshooting

Requests aren't intercepted when using Windows host

If Dev Proxy on Windows isn't intercepting requests from WSL:

1. Verify that networkingMode=mirrored and autoProxy=true are set in the [wsl2] section of your .wslconfig file. For more information, see Configure WSL networking.

2. Restart WSL to refresh proxy settings:

   wsl --shutdown
   

3. Verify Dev Proxy is running and registered as system proxy.

4. Check that the Dev Proxy certificate is trusted in WSL.

unzip: command not found

If the setup script fails with the unzip: command not found error, install unzip and run the setup script again:

sudo apt update
sudo apt install unzip

Certificate errors

If you see certificate errors:

1. Ensure you installed the certificate in WSL following the steps in Trust the certificate in WSL.
2. For Node.js applications, you might need to configure the application to use the proxy agent. See Use Dev Proxy with Node.js applications.

WSL networking issues

WSL 2 uses a virtualized network adapter. If you experience networking issues:

1. Ensure your Windows Firewall allows Dev Proxy.
2. Try using localhost instead of 127.0.0.1 when configuring the proxy address.

Related content

• Use Dev Proxy with Node.js applications
• Use Dev Proxy with .NET applications
• Use Dev Proxy in a Docker container