WSL2 Port Forwarding

WSL Port Forwarding is a specialized feature in HomeDock OS Desktop for Windows that solves a fundamental networking limitation: Docker applications running inside WSL2 are only accessible on localhost and cannot be reached from other devices on your network.

This feature creates network rules that expose your HomeDock OS applications to other devices on your local network, enabling you to access them from phones, tablets, other computers, and any device connected to the same Wi-Fi or Ethernet network.

Why It’s Needed

The WSL2 Limitation

When HomeDock OS runs on Windows, the applications operates inside a WSL2 bridge (Windows Subsystem for Linux). While this provides excellent performance and compatibility, it creates a networking isolation:

• Internal Access: Applications are accessible via http://localhost:PORT on your Windows computer
• Network Isolation: Other devices on your network cannot reach these applications directly
• WSL2 Virtual Network: Applications run in a separate network namespace that’s not bridged to your physical network

The Solution

WSL2 Port Forwarding creates Windows network rules that:

1. Listen on your Windows computer’s network interface (accessible to other devices)
2. Forward traffic to the corresponding port inside WSL2
3. Enable network-wide access to your HomeDock OS applications

How to Use

Accessing WSL2 Port Forwarding

1. Open HomeDock OS Desktop on run as self-hosted
2. Right-click the system tray icon (near your clock)
3. Select “WSL2 Port Forwarding” from the context menu
4. The WSL2 Port Forwarding window will open

Note: This option only appears when HomeDock OS is already running as a self-hosted instance and on Windows devices

Using the Interface

Available Ports Section

• Auto-Detection: Automatically discovers HomeDock OS installed applications with exposed ports
• Real-time: Updates as you start/stop applications in HomeDock OS
• One-Click: Click “Expose” to make a port available network-wide (or internet wide if you open the ports too on your router)

Example Usage

1. Start an application in HomeDock OS (e.g., The Atlas on port 42424)
2. Open Port Forwarding from the system tray
3. Click “Expose” next to port 42424
4. Access from any device: http://YOUR-COMPUTER-IP:42424
5. That’s all, we wanted it to be that that easy :)

Technical Details

Network Rules Created

For each exposed port, the system creates:

• Port Proxy Rule: netsh interface portproxy add v4tov4 listenport=PORT listenaddress=0.0.0.0 connectport=PORT connectaddress=WSL_IP
• Firewall Rule: netsh advfirewall firewall add rule name="HomeDock OS Port PORT" dir=in action=allow protocol=TCP localport=PORT

Security Considerations

• Local Network Only: Rules bind to 0.0.0.0, making ports accessible on your local network
• No Internet Exposure: Your router/firewall still protects you from external access
• Selective Exposure: Only ports you explicitly enable are exposed
• Easy Reversal: Rules can be removed instantly

Finding Your Computer’s IP

To access exposed applications from other devices, you will need to access your local HomeDock OS instance via browser on any other device or access directly with your local IP address:

Method 1: Command Line

ipconfig | findstr IPv4

Method 2: Settings

1. Windows Settings → Network & Internet
2. Properties → IPv4 address

Method 3: Control Panel

1. Network and Sharing Center
2. Click your connection → Details

Troubleshooting

Port Forwarding Not Working

Check Administrator Privileges

• Ensure you provided admin credentials when prompted
• Try closing and reopening the Port Forwarding window

Verify Network Rules

netsh interface portproxy show v4tov4
netsh advfirewall firewall show rule name="HomeDock OS Port [PORT]"

Restart Network Services

net stop winnat
net start winnat

Applications Not Showing

Refresh the Port List

• Click the “Refresh” button in the Port Forwarding window
• Ensure your applications are actually running in HomeDock OS

Connection Issues from Other Devices

Check Windows Firewall

• Ensure Windows Firewall isn’t blocking connections
• Verify the specific port rules were created

Network Configuration

• Confirm all devices are on the same network/subnet
• Test with a simple ping to your Windows computer

Common Use Cases

Development Team Access

• Web Applications: Share development previews with team members
• API Testing: Allow mobile apps to connect to local API servers
• Database Access: Enable database GUI tools from other computers

Home Network Integration

• Media Servers: Stream content to smart TVs and devices
• Home Automation: Access control panels from tablets and phones
• File Sharing: Make file servers available network-wide

Testing and Demos

• Cross-Device Testing: Test responsive design on real mobile devices
• Client Presentations: Show applications without complex deployment
• Multi-User Testing: Enable simultaneous access for testing scenarios

Best Practices

When using WSL2 Port Forwarding, security should be your primary consideration. Always expose only the ports you actually need to minimize your attack surface, and make it a habit to remove forwarding rules when applications are no longer required. The WSL2 Port Forwarding interface makes it easy to monitor which rules are currently active, so check this regularly to ensure you’re not inadvertently exposing services you’ve forgotten about.

Limitations

WSL2 Port Forwarding is inherently tied to Windows and WSL2, so this functionality isn’t available on other operating systems where HomeDock OS might run. The feature only exposes applications to your local network, it doesn’t provide internet access or external connectivity beyond your router. You’ll need administrator privileges for the initial setup and whenever you create new forwarding rules, though existing rules will persist without requiring elevated access. Currently, the system only supports IPv4 networking, which covers most home and office network scenarios but may not work in IPv6-only environments.

Related Features

This WSL2 Port Forwarding capability on Windows works alongside several other HomeDock OS features. Within HomeDock OS itself, you can configure which ports your applications use through the main settings interface, giving you control over the source of what gets exposed. Windows Firewall may require additional configuration in some network scenarios, particularly in corporate environments with strict security policies. Advanced users who are comfortable with WSL2 can also modify the underlying network configuration directly, though the WSL2 Port Forwarding interface should handle most common use cases without requiring manual intervention.