docs: Add WSL setup guide and automation script for Claude Code

[jeffaf]

Summary

This PR adds comprehensive documentation for setting up HexStrike MCP in WSL2 environments connecting to a HexStrike server running on Windows host (including VM port-forwarding scenarios).

New Files

WSL_SETUP.md - Step-by-step setup guide including:

• Architecture diagram showing WSL → Windows host → VM connectivity
• Prerequisites and quick setup instructions
• Manual setup with Windows firewall and port proxy commands
• Troubleshooting section for common issues (connection refused, module errors, etc.)
• Mirrored networking mode alternative for WSL 2.0+

wsl-setup.sh - Automated setup script that:

• Installs required Python dependencies
• Auto-detects Windows host IP from WSL
• Tests server connectivity
• Configures Claude Code MCP settings automatically
• Provides clear Windows configuration commands when needed

Problem Being Solved

Currently there's no documentation for:

1. Setting up HexStrike in WSL2 environments
2. Configuring Claude Code CLI (only Claude Desktop is documented)
3. Handling the WSL networking quirks (localhost doesn't route to Windows host)

This is a common setup scenario - running Claude Code in WSL while the HexStrike server runs in a Kali VM with ports forwarded through Windows.

Testing Done

• Tested on WSL2 (Ubuntu) connecting to HexStrike server in Kali Linux VM
• Port forwarding through Windows host using netsh portproxy
• Verified both manual setup and automated script
• Confirmed MCP tools accessible in Claude Code after setup

Related Issues

• Relates to Tools Installation Scripts #12 (documentation request)
• Relates to How to install missing tools #120 (setup issues)

---

🤖 Generated with Claude Code

[destroyerofworldsllm]

This is a Rube Goldberg configuration that is not ideal, and will not work as you have described it. I suspect Claude itself is the author of this mess, but why did the humans in the loop set it to this particularly task in the first place?

You can run the server and mcp component AND claude on a single wsl instance that would run lighter than this setup. Or even better, run the server and mcp on a single instance of Kali WSL with all the tools and requirements ready to go, and then use claude for windows, if you have to use Claude in the first place. Either will work with the localhost forwarding, which is enabled in WSL2 by default.

The second problem you have not addressed is trying to invoke tools that require root from a normal users account. As there is no interactivity, it will fail as it cannot pass the sudo password. The way around this is to visudo the user in the instance that contains the tools, and set it to all:all, unless you want to create individual passwordless sudo exceptions for 60+ tools.

A better and cheaper way is run server and mcp on the kali wsl instance from the store, and then use Void and Roo to connect to it. This lets you use openrouter (free) or Z.AI 4.6 (3$ a month) on almost any system, without paying for claude. Im not even sure if claude will run 150 tool defs in one mcp load, to be honest.

[jeffaf]

This is a Rube Goldberg configuration that is not ideal, and will not work as you have described it. I suspect Claude itself is the author of this mess, but why did the humans in the loop set it to this particularly task in the first place?

It works fine for me.

You can run the server and mcp component AND claude on a single wsl instance that would run lighter than this setup. Or even better, run the server and mcp on a single instance of Kali WSL with all the tools and requirements ready to go, and then use claude for windows, if you have to use Claude in the first place. Either will work with the localhost forwarding, which is enabled in WSL2 by default.

Yep, but this is for if you need to connect to a VM outside of WSL. Personally, I need Claude Code for Linux because I use PAI (https://github.com/danielmiessler/Personal_AI_Infrastructure) but its not a requirement for this setup.

The second problem you have not addressed is trying to invoke tools that require root from a normal users account. As there is no interactivity, it will fail as it cannot pass the sudo password. The way around this is to visudo the user in the instance that contains the tools, and set it to all:all, unless you want to create individual passwordless sudo exceptions for 60+ tools.

?? I'm not using tools that require sudo and I don't think hexstrike is either but I don't know for sure.

A better and cheaper way is run server and mcp on the kali wsl instance from the store, and then use Void and Roo to connect to it. This lets you use openrouter (free) or Z.AI 4.6 (3$ a month) on almost any system, without paying for claude. Im not even sure if claude will run 150 tool defs in one mcp load, to be honest.

Sounds cool, I like roo too. I don't know if Claude will load 150 tools either but I think it would. Instead here we just load hexstrike.

And yes the docs were generated by Claude Code and it says as much at the bottom.