HexStrike AI + OpenCode Installer

An interactive Bash installer that sets up HexStrike AI (an MCP server exposing pentest tooling) alongside OpenCode on Ubuntu or Kali Linux, so you can drive security tools from an AI coding agent over MCP.

This came out of repeatedly hitting the same setup/integration issues while wiring HexStrike + OpenCode together across WSL/Kali, then a Kali VPS; so the script scans what you already have, only installs what's missing for the use-cases you actually care about, and patches a known MCP timeout bug before writing a single OpenCode config.

⚠️ Responsible use

This script installs offensive-security tooling (nmap, sqlmap, Metasploit, Hydra, Hashcat, etc.) and wires it up to be driven by an AI agent. Only use this against systems and networks you own or are explicitly authorized to test. You are responsible for complying with local laws and the terms of any environment you run this in (e.g. cloud provider AUPs). This project is provided for legitimate security research, CTFs, and authorized penetration testing only.

What it does

1. Detects/confirms your distro (Ubuntu or Kali).
2. Installs base prerequisites (Python venv, git, tmux, build tools).
3. Scans your system and reports existing pentest-tool coverage by category; nothing is installed yet at this point.
4. Asks which use-case(s) you actually need: network, web, exploit dev, password cracking, OSINT, wireless, forensics, cloud.
5. Computes only the missing tools for those use-cases and installs just those (Kali users can alternatively opt into the full kali-linux-default metapackage).
6. Installs Node via nvm + OpenCode, clones HexStrike, and sets up its Python virtualenv.
7. Patches a known MCP health-check timeout bug (5s → 15s) and writes a single opencode.json MCP config.
8. Validates the install, optionally runs a live health check against the HexStrike server, and prints a run guide.

The script is idempotent/safe to re-run; re-running it later to add more use-cases will only install what's still missing.

Prerequisites

• Ubuntu (22.04+) or Kali Linux, x86_64 or arm64
• A regular user account with sudo access (do not run this via sudo; it calls sudo itself only where needed for package installs)
• An internet connection (the script installs from apt, pip/pipx, Go, gem, and cargo depending on which tools you select)

Usage

git clone https://github.com/<your-username>/hexstrike-opencode-setup.git
cd hexstrike-opencode-setup
chmod +x install-hexstrike-opencode.sh
./install-hexstrike-opencode.sh

Follow the interactive prompts. A full run typically takes anywhere from a few minutes to 20+ minutes depending on how many tools are missing and your connection speed.

Running it again later

Just re-run the script. It re-scans, so it only installs whatever's still missing for whichever use-cases you select this time.

After installation

# 1. Start the HexStrike API server in tmux
tmux new -s hexstrike
cd ~/hexstrike-ai && source hexstrike-env/bin/activate
python3 hexstrike_server.py --debug
# detach with Ctrl+b then d

# 2. Confirm it's healthy
curl -s http://localhost:8888/health | jq .status

# 3. Launch OpenCode (it spawns the MCP bridge itself — don't run
#    hexstrike_mcp.py by hand)
opencode

# 4. Verify the MCP link
opencode mcp list        # expect: hexstrike connected

# 5. Try it
use hexstrike to scan scanme.nmap.org

The OpenCode MCP config lives at ~/.config/opencode/opencode.json if you want to add other model providers.

Keep port 8888 bound to localhost. On a public VPS, firewall it off:

sudo ufw deny 8888

Troubleshooting

• Install log: every run writes detailed output to a per-run log under /tmp/hexstrike-install.*.log; check there first for any tool that failed to install.
• opencode mcp list doesn't show hexstrike connected: make sure the HexStrike server is running first (curl -s http://localhost:8888/health), then relaunch opencode.
• "Connection closed" from OpenCode on startup: this is the MCP health-check timeout the script patches automatically. If you cloned HexStrike separately from this script, re-run the script or manually bump the timeout=5 in hexstrike_mcp.py's health check to timeout=15.
• Go tool installs failing: some security-tool Go modules need the 1.21–1.24 toolchain line. The script installs an official Go toolchain to /usr/local/go if apt's Go is missing or incompatible — check go version after a run.
• nvm/node/opencode not found in a new shell: open a fresh terminal (or source ~/.bashrc / ~/.zshrc) so PATH additions take effect.

Why this exists

Setting this up manually across WSL+Kali and a Kali VPS surfaced the same handful of integration snags each time (missing toolchains, the MCP timeout bug, PEP 668 pip restrictions, PATH issues across Go/cargo/pipx). This script encodes the fixes so the next setup; yours or anyone else's — doesn't have to rediscover them.

Contributing

Issues and PRs welcome — see CONTRIBUTING.md.

License

MIT

Disclaimer

This project is not affiliated with HexStrike AI or OpenCode. Use of any tools installed by this script is entirely your responsibility. See Responsible use above.