Codespace SSH Port Forwarder

Auto-detect listening ports in GitHub Codespaces and create SSH tunnels to access them at localhost on your Windows machine.

The Problem

When you SSH into a codespace with gh cs ssh and start a server (e.g., npm start on port 3000), you can't access localhost:3000 from your Windows machine - unlike VS Code which auto-forwards ports.

The Solution

This script:

1. Monitors your codespace for listening ports
2. Automatically creates SSH tunnels (ssh -L) for each detected port
3. Lets you access services at localhost:<port> on Windows

Usage

Quick Start

# Run directly
.\cswatch-standalone.ps1

# Or with specific codespace
.\cswatch-standalone.ps1 -Codespace "my-codespace-name"

# Press 'q' to quit and close all tunnels cleanly

Cleanup Orphaned Tunnels

If you close the terminal without pressing 'q', SSH tunnels may be left running:

# List and kill orphaned SSH tunnel processes
.\csstop-standalone.ps1

Workflow

Terminal 1: Run the watcher

.\cswatch-standalone.ps1
# Select codespace from picker
# Watches for new ports...

Terminal 2: SSH and start your server

gh cs ssh -c my-codespace
npm start  # Server starts on port 3000

Terminal 1: Shows detection

[Detected port 3000] -> localhost:3000

Browser: Open http://localhost:3000 - it works!

Installation

Option 1: Run directly

Just download the scripts and run them from any directory:

.\cswatch-standalone.ps1
.\csstop-standalone.ps1

Option 2: Add aliases to PowerShell profile

# Add to your $PROFILE
Set-Alias cswatch "C:\path\to\cswatch-standalone.ps1"
Set-Alias csstop "C:\path\to\csstop-standalone.ps1"

Parameters

Parameter	Default	Description
-Codespace	(picker)	Name of codespace to watch
-IgnorePorts	22,53,1089,2222	Ports to ignore
-IncludeHighPorts	false	Include ports > 49151
-IncludeLowPorts	false	Include ports < 1024
-PollInterval	2	Seconds between checks

How It Works

1. Generate SSH Config: Uses gh cs ssh --config to get SSH configuration
2. Fix Windows Paths: Converts backslashes to forward slashes, quotes paths with spaces
3. Poll for Ports: Runs ss -tlnH in codespace to detect listening ports
4. Create Tunnels: Uses ssh -F config -L port:localhost:port -N host for each port

Requirements

• PowerShell 5.1+ or PowerShell Core
• GitHub CLI (gh) authenticated
• OpenSSH client (included in Windows 10+)

Troubleshooting

Tunnel says "ready" but can't connect

Check if the port is actually bound:

netstat -ano | Select-String "YOUR_PORT.*LISTENING"

If not listed, the tunnel failed. Try:

1. Kill stale SSH processes: Get-Process ssh | Stop-Process -Force
2. Restart the watcher

Path errors with spaces

The script should handle this, but if you see errors about "C:Program", the ProxyCommand path isn't quoted properly. Check ~/.ssh/codespaces_portfwd_config.

License

MIT