Second in the BugTraceAI series — the first post covered what it is and why "agentic" matters. This one is the hands-on part.
Getting BugTraceAI running takes roughly ten minutes: one install command, a short interactive menu and a model API key. No security expertise needed to get it going — finding things is the tool's job.
Screenshots are from an earlier Launcher build — the flow is the same; some labels and version numbers differ slightly in the current release.
What you need
- A Linux machine or VM (or WSL on Windows). The standalone terminal profile needs Python 3.10+; full-platform deployments also use Docker (Docker Engine, Compose and Git).
- An LLM provider API key — e.g. OpenRouter, Anthropic or Z.ai. Analysis runs with your own key.
- Ten minutes and a target you're allowed to test. No target yet? Use BugStore, our intentionally vulnerable practice app.
Step 1 — One command
curl -fsSL https://raw.githubusercontent.com/BugTraceAI/BugTraceAI-Launcher/main/install.sh | bash
The script pulls down the Launcher — the guided installer for the whole ecosystem. Prefer to read before you run? Clone it and start it yourself:
git clone https://github.com/BugTraceAI/BugTraceAI-Launcher.git ~/bugtraceai-launcher
~/bugtraceai-launcher/launcher.sh
On Windows, run this from Git Bash or WSL — PowerShell has no bash.
Step 2 — Pick what to install
The Launcher opens an interactive terminal menu. It checks your environment first (Docker, Compose, Git, curl, RAM and disk — each reported explicitly), then asks which product combination to install:
| Profile | What gets installed | Runtime |
|---|---|---|
terminal |
CLI terminal workspace (TUI) | Local Python or Docker |
web |
WEB dashboard, with either or both scanning engines | Docker |
full |
WEB + both scanning engines + CLI TUI | Docker |
server |
CLI web-scanning API/MCP | Local Python or Docker |
terminal-server |
CLI TUI + web-scanning API/MCP, no WEB | Local Python or Docker |
api |
BugTraceAI-API target engine, REST + MCP | Docker |
For a first look, full shows the complete picture; for the lightest start, choose terminal.
Step 3 — Wizard or AI setup
Next, choose how to run the installation:
- Install with Wizard — manual, step-by-step choices. Supports every module combination.
- Install with AI — the AI Setup & Repair Assistant. Currently supports API-only or the full WEB + CLI + API selection, with OpenRouter or Anthropic.
You'll enter and verify your provider API key during this flow, and the final review shows the selected modules, runtime and ports before anything is written to disk.
Step 4 — Confirm the stack is up
When the install finishes, all services run locally in Docker — check them with:
docker ps
Five containers, all healthy — and nothing leaves your machine.
Step 5 — Open the console and connect your model key
Open the web console — the default is http://localhost:6869, and the installer prints the exact URL for your setup:
Then go to Settings, add your LLM provider key and hit Test API Connection. Green means you're ready to save and scan:
Step 6 — First scan
Point it at your target — or at BugStore, the practice shop we built for exactly this:
Watch the six phases run: Recon → Discovery → Strategy → Exploit → Validate → Report. When it's done, export the report as Markdown or JSON, and open any finding to see its evidence chain — requests, code snippets and traces. That's the part that matters: you verify before you file.
Common questions
- Port already in use? The wizard detects it and offers alternatives — you can also type a custom port (1024–65535). An occupied port is never silently replaced.
- No API key yet? Any supported provider works (OpenRouter, Anthropic, Z.ai, …). Keys are pay-as-you-go, and they stay in your deployment.
- Where do reports and scans live? In your own infrastructure. BugTraceAI is self-hosted: scan data and evidence never leave your machine, and analysis runs with your own provider key.
Honest notes
- All components are in beta — expect rough edges; report anything odd via GitHub Issues.
- Launcher 3.3.26 passed focused installer tests on clean Linux VMs; macOS and ARM runtime validation is not included yet.
- Verify findings before you file them. AI output is a lead, not a verdict — that is exactly why the pipeline validates every finding.
Where to go next
- Docs: the project Wiki — Getting Started, Architecture and component guides
- Community: Discord · GitHub Issues
- Not ready to install? Explore the live demo or grab the demo report
- If this saves you time: a star on GitHub genuinely helps an open-source security project get discovered
BugTraceAI is built for authorized security testing only — only test applications you have explicit written permission to test.
Top comments (0)