Configuring Pentest Swarm AI: Keys, Models, and Tools

Pentest Swarm AI uses a layered configuration system: a YAML file supplies structured defaults, and environment variables override any value at runtime without touching the file. The config file is looked up in order from ./config.yaml, ~/.pentestswarm/config.yaml, and /etc/pentestswarm/config.yaml. You can also point directly to a file with --config <path> on any command. Running pentestswarm init writes a minimal starter config to ~/.pentestswarm/config.yaml and stores your API key in the OS keychain — that is the recommended starting point.

Full annotated config.yaml

Copy config.example.yaml from the repository root to config.yaml and fill in your values. Every field shown below can be overridden by an environment variable prefixed with PENTESTSWARM_ (dots replaced with underscores — e.g. PENTESTSWARM_ORCHESTRATOR_API_KEY).

# pentestswarm configuration
# Copy this to config.yaml and fill in your values.
# All values can be overridden via environment variables prefixed with PENTESTSWARM_
# Example: PENTESTSWARM_ORCHESTRATOR_API_KEY=sk-ant-...

# --- Server ---
server:
  host: "0.0.0.0"          # API server bind address
  port: 8080               # API server port

# --- Database ---
database:
  host: "localhost"
  port: 5432
  user: "pentestswarm"
  password: ""             # REQUIRED — set via PENTESTSWARM_DATABASE_PASSWORD
  name: "pentestswarm"
  sslmode: "disable"       # disable, require, verify-ca, verify-full

# --- Redis ---
redis:
  host: "localhost"
  port: 6379
  password: ""
  db: 0

# --- Orchestrator (main AI) ---
orchestrator:
  provider: "claude"       # claude, ollama, lmstudio
  model: "claude-sonnet-4-6" # Model to use for orchestration
  api_key: ""              # REQUIRED for Claude — set via PENTESTSWARM_ORCHESTRATOR_API_KEY
  endpoint: ""             # Required for ollama/lmstudio (e.g. http://localhost:11434)
  context_window: 200000   # Max context window size in tokens
  max_tokens: 8192         # Max output tokens per completion
  temperature: 0.1         # Lower = more deterministic

# --- Specialist Agent Models ---
# By default, ALL agents inherit the orchestrator's provider and API key.
# This means with just a Claude API key above, everything works — no Ollama needed.
#
# To use local fine-tuned models instead (v2.0), uncomment and configure:
agents:
  recon:
    provider: ""               # empty = inherit from orchestrator (Claude)
    model: ""                  # empty = use orchestrator's model
    # To use fine-tuned local model instead:
    # provider: "ollama"
    # model: "ArmurAI/recon-agent-qwen2.5-7b"
    # endpoint: "http://localhost:11434"
  classifier:
    provider: ""
    model: ""
  exploit:
    provider: ""
    model: ""
  report:
    provider: ""
    model: ""

# --- Security Tool Settings ---
tools:
  default_timeout: 300     # Default tool timeout in seconds
  subfinder:
    recursive: false       # Recursive subdomain enumeration
    timeout: 300
    rate_limit: 10         # Requests per second
  httpx:
    follow_redirects: true
    timeout: 30            # Per-request timeout in seconds
    threads: 50
  nuclei:
    template_path: ""      # Custom template directory (leave empty for default)
    severity:              # Minimum severity levels to scan
      - critical
      - high
      - medium
    rate_limit: 150        # Requests per second
    timeout: 300
  naabu:
    ports: "top-1000"      # Port specification: "top-100", "top-1000", "80,443,8080"
    rate: 1000             # Packets per second
    timeout: 300
  katana:
    depth: 3               # Crawl depth
    js_crawl: true         # Enable JavaScript-aware crawling
    timeout: 300

# --- Scope Enforcement ---
scope:
  enforce_strict: true     # ALWAYS true — cannot be disabled. Safety constraint.

# --- Continuous ASM ---
asm:
  enabled: false           # Enable continuous attack surface monitoring
  default_schedule: "24h"  # How often to re-scan watched scopes
  max_auto_campaigns: 3    # Max auto-triggered campaigns per 24h per scope
  notification_slack: ""   # Slack webhook URL for ASM alerts
  notification_email: ""   # Email address for ASM alerts

# --- Bug Bounty ---
bugbounty:
  hackerone_api_key: ""    # HackerOne API key
  hackerone_username: ""   # HackerOne username
  bugcrowd_api_key: ""     # Bugcrowd API key

# --- Shared Intelligence Network ---
intelligence:
  enabled: false           # Must be explicitly enabled (opt-in)
  share_patterns: false    # Contribute anonymized patterns to community
  consume_patterns: false  # Use community patterns to improve scans
  api_endpoint: "https://api.pentestswarm.ai"

# --- Integrations ---
integrations:
  jira:
    url: ""                # Jira instance URL (e.g. https://company.atlassian.net)
    api_token: ""
    project: ""            # Default project key
    issue_type: "Bug"      # Default issue type
  slack:
    bot_token: ""          # Slack bot token (xoxb-...)
    signing_secret: ""
    channel: ""            # Default channel for notifications

# --- Logging ---
logging:
  level: "info"            # debug, info, warn, error
  format: "console"        # console (human-readable) or json (structured)

Config sections

Orchestrator — provider, model, API key

The orchestrator block configures the primary LLM used to coordinate the swarm. All agents inherit this provider and API key unless explicitly overridden in the agents block.

Field	Default	Description
`provider`	`claude`	LLM backend: `claude`, `ollama`, or `lmstudio`
`model`	`claude-sonnet-4-6`	Model name passed to the provider
`api_key`	`""`	Claude API key — prefer the `PENTESTSWARM_ORCHESTRATOR_API_KEY` env var
`endpoint`	`""`	Required for `ollama` / `lmstudio` (e.g. `http://localhost:11434`)
`context_window`	`200000`	Max context window in tokens
`max_tokens`	`8192`	Max tokens per LLM completion
`temperature`	`0.1`	Sampling temperature; lower values are more deterministic

Claude example:

orchestrator:
  provider: claude
  model: claude-sonnet-4-6
  api_key: ""          # set via PENTESTSWARM_ORCHESTRATOR_API_KEY instead
  temperature: 0.1

Ollama (local) example:

orchestrator:
  provider: ollama
  model: llama3.3
  endpoint: http://localhost:11434
  temperature: 0.1

LM Studio (local) example:

orchestrator:
  provider: lmstudio
  model: meta-llama-3.1-8b-instruct
  endpoint: http://localhost:1234
  temperature: 0.1

Agents — per-agent model overrides

The agents block lets you assign a different model to each specialist agent. An empty provider or model field means the agent inherits from the orchestrator — which means a single Claude key is sufficient to run the whole swarm by default.Agents available: recon, classifier, exploit, report.Example: exploit agent on a heavier model, classifier on a cheaper one:

agents:
  exploit:
    model: claude-opus-4-7      # reasoning-heavy agent on the smart model
  classifier:
    model: claude-haiku-4-5-20251001   # cheap model for volume classification

Example: hybrid cloud + local setup:

agents:
  recon:
    provider: ollama
    model: ArmurAI/recon-agent-qwen2.5-7b
    endpoint: http://localhost:11434
  classifier:
    provider: ollama
    model: ArmurAI/classifier-agent-qwen2.5-3b
    endpoint: http://localhost:11434
  exploit:
    provider: claude
    model: claude-opus-4-7
    # api_key inherits from orchestrator
  report:
    # inherits everything from orchestrator

Each agent block accepts provider, model, api_key, and endpoint. Any field left empty falls back to the orchestrator value.

Tools — subfinder, httpx, nuclei, naabu, katana

The tools block tunes the behaviour of each security tool the swarm calls out to. default_timeout applies to any tool that does not have its own timeout key.subfinder — passive subdomain discovery:

Field	Default	Description
`recursive`	`false`	Enumerate subdomains of discovered subdomains
`timeout`	`300`	Total run timeout in seconds
`rate_limit`	`10`	Requests per second

httpx — HTTP probing:

Field	Default	Description
`follow_redirects`	`true`	Follow HTTP redirects
`timeout`	`30`	Per-request timeout in seconds
`threads`	`50`	Concurrent threads

nuclei — template-based vulnerability scanning:

Field	Default	Description
`template_path`	`""`	Path to custom template directory; empty uses nuclei’s default templates
`severity`	`[critical, high, medium]`	Minimum severity filter
`rate_limit`	`150`	Requests per second
`timeout`	`300`	Total run timeout in seconds

naabu — port scanning:

Field	Default	Description
`ports`	`top-1000`	Port set: `top-100`, `top-1000`, or a list like `80,443,8080`
`rate`	`1000`	Packets per second
`timeout`	`300`	Total run timeout in seconds

katana — web crawling:

Field	Default	Description
`depth`	`3`	Maximum crawl depth
`js_crawl`	`true`	Parse and crawl JavaScript-rendered content
`timeout`	`300`	Total run timeout in seconds

Scope enforcement

Scope enforcement prevents the swarm from acting on targets outside the --scope you specify at scan time.

scope:
  enforce_strict: true

scope.enforce_strict is always true and cannot be disabled. The value is hard-coded in internal/config/config.go regardless of what the config file or environment contains. Scope enforcement is a fundamental safety constraint: it is applied at the tool layer and again at the executor layer as defence in depth. The --scope flag is not bypassable.

ASM — continuous attack surface monitoring

The asm block enables scheduled re-scanning of watched scopes, building a continuous picture of an organization’s external attack surface.

Field	Default	Description
`enabled`	`false`	Enable continuous ASM mode
`default_schedule`	`24h`	Re-scan interval (Go duration string: `6h`, `24h`, `72h`)
`max_auto_campaigns`	`3`	Maximum auto-triggered campaigns per scope per 24-hour window
`notification_slack`	`""`	Slack webhook URL for new-finding alerts
`notification_email`	`""`	Email address for new-finding alerts

asm:
  enabled: true
  default_schedule: "24h"
  max_auto_campaigns: 3
  notification_slack: "https://hooks.slack.com/services/T.../B.../..."

Bug bounty platform credentials

Supply platform API credentials to enable automatic program-scope fetching and submission helpers.

bugbounty:
  hackerone_api_key: ""      # HackerOne API key
  hackerone_username: ""     # HackerOne username
  bugcrowd_api_key: ""       # Bugcrowd API key

Prefer environment variables for credentials — see the environment variables table below:

export PENTESTSWARM_BUGBOUNTY_HACKERONE_API_KEY=...
export PENTESTSWARM_BUGBOUNTY_HACKERONE_USERNAME=...
export PENTESTSWARM_BUGBOUNTY_BUGCROWD_API_KEY=...

Integrations — Jira and Slack

Configure Jira to auto-file issues for confirmed findings, and Slack for campaign notifications.

integrations:
  jira:
    url: "https://company.atlassian.net"
    api_token: ""          # Jira API token
    project: "SEC"         # Project key
    issue_type: "Bug"      # Issue type name
  slack:
    bot_token: "xoxb-..."  # Bot token
    signing_secret: ""
    channel: "#pentest-alerts"

Both integrations are optional. If url / bot_token is empty the integration is silently disabled.

Logging

logging:
  level: "info"      # debug | info | warn | error
  format: "console"  # console (human-readable) | json (structured)

Set format: json when aggregating logs in a SIEM or log platform. Set level: debug to see every LLM prompt and tool invocation.

Environment variables

Environment variables take precedence over the config file. All YAML keys map to PENTESTSWARM_<UPPER_SNAKE> (dots become underscores).

Environment variable	Equivalent YAML key	Description
`PENTESTSWARM_ORCHESTRATOR_API_KEY`	`orchestrator.api_key`	Claude (or compatible) API key — primary lookup
`ANTHROPIC_API_KEY`	`orchestrator.api_key`	Short-form alias; checked if the primary variable is unset
`PENTESTSWARM_DATABASE_PASSWORD`	`database.password`	Postgres password — never put this in a committed file
`PENTESTSWARM_ORCHESTRATOR_PROVIDER`	`orchestrator.provider`	Override the LLM provider at runtime
`PENTESTSWARM_ORCHESTRATOR_MODEL`	`orchestrator.model`	Override the model name at runtime
`PENTESTSWARM_ORCHESTRATOR_ENDPOINT`	`orchestrator.endpoint`	Override the provider endpoint (Ollama / LM Studio)
`PENTESTSWARM_BUGBOUNTY_HACKERONE_API_KEY`	`bugbounty.hackerone_api_key`	HackerOne API key
`PENTESTSWARM_BUGBOUNTY_HACKERONE_USERNAME`	`bugbounty.hackerone_username`	HackerOne username
`PENTESTSWARM_BUGBOUNTY_BUGCROWD_API_KEY`	`bugbounty.bugcrowd_api_key`	Bugcrowd API key
`PENTESTSWARM_LOGGING_LEVEL`	`logging.level`	Set log verbosity without editing the file

LLM provider comparison

All agents inherit from a single provider config. Set one key and the entire swarm uses it. You can mix providers per-agent via the agents block.

Provider	Setup	Privacy	Best for
Claude (default)	`export PENTESTSWARM_ORCHESTRATOR_API_KEY=sk-ant-...`	Cloud	Best quality, zero local setup, prompt caching on recon + classifier by default
Ollama	Install Ollama, `ollama pull <model>`, set `endpoint: http://localhost:11434`	100% local	Full data privacy, air-gapped environments, no token costs
LM Studio	Load a model in the LM Studio GUI, enable the local server, set `endpoint: http://localhost:1234`	100% local	GUI-based model management, easy model switching

Claude’s prompt caching is enabled by default for the recon and classifier agents. On large scans with repeated system prompts this meaningfully reduces both cost and latency.

Per-agent model override example

The following config runs the compute-intensive exploit agent on Claude Opus while keeping the high-volume classifier agent on a faster, cheaper model, and inheriting Claude Sonnet for everything else from the orchestrator:

orchestrator:
  provider: claude
  model: claude-sonnet-4-6
  # api_key set via PENTESTSWARM_ORCHESTRATOR_API_KEY

agents:
  exploit:
    model: claude-opus-4-7        # reasoning-heavy; use the smartest model
  classifier:
    model: claude-haiku-4-5-20251001  # high-volume; use the fastest model
  # recon and report inherit claude-sonnet-4-6 from the orchestrator

Get Started

Core Concepts

CLI Reference

Guides

Security & Operations

Configuring Pentest Swarm AI: Keys, Models, and Tools

Full annotated config.yaml

Config sections

Environment variables

LLM provider comparison

Per-agent model override example

Build docs developers (and LLMs) love

Get Started

Core Concepts

CLI Reference

Guides

Security & Operations

Documentation Index

​Full annotated config.yaml

​Config sections

​Environment variables

​LLM provider comparison

​Per-agent model override example

Build docs developers (and LLMs) love

Full annotated config.yaml

Config sections

Environment variables

LLM provider comparison

Per-agent model override example