Skip to main content

Quick Start

One command to install. One command to run. No API key, no cloud, and no bill to get started — a bundled lab plus a local model will find a real vuln for free.

1 · Install (pick one)​

# npm (Node ≥ 16) — the quickest path
npm install -g @armurai/pentestswarm

# any macOS / Linux — install script
curl -fsSL https://raw.githubusercontent.com/Armur-Ai/Pentest-Swarm-AI/main/scripts/install.sh | sh

# Homebrew
brew install Armur-Ai/tap/pentestswarm

# Go toolchain
go install github.com/Armur-Ai/Pentest-Swarm-AI/cmd/pentestswarm@latest

# Docker
docker run --rm ghcr.io/armur-ai/pentestswarm:latest --help

Verify the binary is on your PATH:

pentestswarm --version

If the command isn't found right after an npm -g install, see Troubleshooting.

2 · Run it​

pentestswarm run

That's it. run opens the interactive TUI launcher — no flags to memorize. Step through it in the terminal:

  1. Pick your AI provider and paste a key right in the UI — Together AI (first-class multi-model: Llama / Qwen / DeepSeek routed by task), Claude, OpenAI, Gemini, OrcaRouter, or fully local Ollama / LM Studio (no key at all). See Providers.
  2. Point it at a target — a URL you're authorized to test, or a bundled vulnerable lab that spins up, gets attacked, and tears down after.
  3. Pick a scan mode — manual, bugbounty, ctf, or asm. See Scan Modes.
  4. Set a spend cap — the Spend cap field is a hard per-run USD ceiling (minimum $2 on paid providers, ←/→ to adjust; "no cost — local model" for Ollama / LM Studio). See Cost & Safety.
  5. Choose your live view — a web dashboard on localhost:7777 and/or a full-screen terminal TUI with live charts, a swarm-topology diagram, and a graded findings stream. Both, by default. See Live Views.
  6. Launch and watch the swarm work at machine speed.

A readiness check runs right inside the launcher (Go, Docker, tools, provider). It never blocks — anything missing shows up as a note you can fix or ignore.

Bundled labs​

Don't have an authorized target handy? Pick a bundled, intentionally-vulnerable lab. Each spins up in Docker, gets attacked, and tears down automatically — safe and legal, zero setup:

Lab--lab-targetWhat it is
crAPIcrapiCompletely Ridiculous API — OWASP API Top 10
Juice ShopjuiceshopOWASP's modern web-app playground
VAmPIvampiVulnerable REST API
DVGAdvgaDamn Vulnerable GraphQL Application

Running a lab requires Docker. That's the only thing Docker is needed for — see Troubleshooting.

Prefer flags? (scripting / CI)​

run just wraps scan, so everything is scriptable too:

# watch it find a real vuln in ~2 min — bundled lab, local model, no key
pentestswarm scan --lab --lab-target crapi --provider ollama --swarm --tui

# a real target, cloud model for max quality
export PENTESTSWARM_ORCHESTRATOR_API_KEY=your-key-here
pentestswarm scan <authorized-target> --scope <target> --swarm --follow

See the full CLI reference for every command and flag.

Next steps​

  • Scan Modes — steer the swarm for bug bounty, CTF, or ASM.
  • Cost & Safety — spend caps, killswitch, safe mode, and scope: everything you need to leave a run unattended.
  • Live Views / Dashboard — the localhost:7777 dashboard and the terminal TUI.
  • Configuration — pin providers, models, and per-agent overrides in config.yaml.
Docs from the terminal

Run pentestswarm docs any time to open this documentation site in your browser.