Install

Install BreachPilot in minutes

Linux is the primary platform, macOS and Windows are supported. The review-first flow below is recommended. The one-liner picker is an optional shortcut for scripts you have already read.

Linux · primarymacOS · supportedWindows · secondary

Linux install

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

Quick install above is optional. Recommended: Review installer before running →

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

Trust, then run

Review-first install per OS

Never pipe a script you haven't read. Download it, read it, then run the local copy.

Linux

Primary platform. Full Kali arsenal optional.

linux review-first

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

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

macOS

Same installer as Linux. Xcode CLT + Homebrew recommended.

macos review-first

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

nmap via brew install nmap. Docker Desktop enables the default-on sandbox.

Windows

Secondary platform. Run in an elevated PowerShell.

windows review-first

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.

Post-install

Verify before your first run

Four commands, in order. Each step is safe to run locally. Stop at the first one that fails and check the requirements below.

1.Launch
Launch
```
bp
```
Starts the local WebUI and opens http://127.0.0.1:8765. Nothing leaves your machine.
2.Keys
Keys
```
bp --setup-api-keys
```
Stores OLLAMA_API_KEY and friends in secr.json. Keys stay in env / local files, never in config.
3.Doctor
Doctor
```
bp --doctor
```
Environment check for Python, nmap, and the model endpoint. Expect all [OK] before your first run.
4.Self-test
Self-test
```
bp --self-test
```
Localhost-only smoke test. No external traffic, safe to run anywhere.

Prerequisites

What you need first

Essential

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

Essential requirements
Need	Minimum	Notes
Python	3.11+	CI matrix 3.11 to 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

Prove it on localhost

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