Install

Install BreachPilot

Linux is the primary platform. Windows is supported as a secondary platform. Never pipe a script you haven't read — every shortcut below has a review-first alternative.

Linux install

curl -fsSL https://breachpilot.dev/install.sh | bash

For authorized testing only — only test systems you own or have explicit written permission to assess. Safety model →

Linux — review first

review-first flow

curl -fsSL https://breachpilot.dev/install.sh -o install.sh
less install.sh
bash install.sh

Full Kali arsenal: INSTALL_KALI_TOOLS=1 ./install.sh. Lightweight alternative: ./scripts/setup-linux.sh.

Windows — review first

review-first flow

irm https://breachpilot.dev/install.ps1 -OutFile install.ps1
Get-Content install.ps1
.\install.ps1

Or double-click install.bat in Explorer. Afterwards, .\START.bat launches the WebUI.

After install

Verify the install before your first run — each step is safe to run locally.

post-install checks

bp                  # launch the local WebUI (default, opens http://127.0.0.1:8765)
bp --setup-api-keys # store OLLAMA_API_KEY and friends in secr.json
bp --doctor         # environment check — expect all [OK]
bp --self-test      # safe localhost-only smoke test

Essential requirements

Install these first — bp --doctor fails without them.

Essential requirements
Need	Minimum	Notes
Python	3.11+	CI matrix 3.11–3.13; --doctor rejects older. python --version to check.
nmap	on PATH or nmap.path	Linux -O/-sS need root (nmap.sudo with sudo -n) or priv_fallback auto-downgrade.
Model endpoint	Ollama Cloud (default) or local	Cloud needs OLLAMA_API_KEY; embeddings stay local via ollama.embed_host.

Optional — skip if WebUI-only

Needed for sandboxing, the WebUI build, and full tool coverage. Safe to add later.

Optional requirements
Need	Minimum	Notes
Node.js + npm	Node 18+	Only for the first WebUI build (auto-built, opens at 127.0.0.1:8765).
Docker	Engine / Desktop + breachpilot-sandbox image	Sandbox is default-on; without it attacks degrade or block per config.
Disk / rights / Git	~4GB free, admin for installs	Git required for clone. Linux Kali arsenal optional (metasploit, hydra, impacket…).

First lab run

Authorized testing only — run against a local lab target you own, never against hosts you do not own or lack explicit written permission to assess. See the safety model.

first lab run against localhost only

docker run --rm -p 8080:80 vulnerables/web-dvwa   # local victim on http://127.0.0.1:8080
bp --target 127.0.0.1 --mode recon --goal initial_access --yes

Stuck? Troubleshooting →