Deploying Pentest Swarm AI with Docker and Postgres

Pentest Swarm AI ships as a statically-linked Go binary that can run as a bare CLI, a long-lived API server, or a containerized service. For anything beyond a single laptop session — CI/CD pipelines, shared red-team infrastructure, continuous ASM runs — Docker Compose is the recommended deployment path. The stack requires three services: the pentestswarm application, Postgres 16 with the pgvector extension (for the stigmergic blackboard and vector similarity search), and Redis 7 (for rate limiting and session state). An optional Ollama service is included for fully-local LLM inference.

Docker Compose

The production compose file at deploy/docker-compose.yml defines all four services with health checks and restart policies. The pentestswarm service waits for both postgres and redis to pass their health checks before starting.

# deploy/docker-compose.yml
version: "3.9"

services:
  pentestswarm:
    build:
      context: ../..
      dockerfile: deploy/docker/Dockerfile
    ports:
      - "8080:8080"
    environment:
      PENTESTSWARM_DATABASE_HOST: postgres
      PENTESTSWARM_DATABASE_PASSWORD: pentestswarm
      PENTESTSWARM_REDIS_HOST: redis
      PENTESTSWARM_ORCHESTRATOR_PROVIDER: ollama
      PENTESTSWARM_ORCHESTRATOR_ENDPOINT: http://ollama:11434
    depends_on:
      postgres:
        condition: service_healthy
      redis:
        condition: service_healthy
    restart: unless-stopped

  postgres:
    image: pgvector/pgvector:pg16
    environment:
      POSTGRES_USER: pentestswarm
      POSTGRES_PASSWORD: pentestswarm
      POSTGRES_DB: pentestswarm
    ports:
      - "5432:5432"
    volumes:
      - pgdata:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U pentestswarm"]
      interval: 5s
      timeout: 5s
      retries: 5

  redis:
    image: redis:7-alpine
    ports:
      - "6379:6379"
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 5s
      timeout: 5s
      retries: 5

  ollama:
    image: ollama/ollama:latest
    ports:
      - "11434:11434"
    volumes:
      - ollama_models:/root/.ollama
    deploy:
      resources:
        reservations:
          memory: 8G

volumes:
  pgdata:
  ollama_models:

Replace the default POSTGRES_PASSWORD: pentestswarm with a strong secret before exposing port 5432 to any network. In production, inject the password via a secrets manager rather than a plain environment variable in the compose file.

The Dockerfile uses a two-stage build: a golang:1.24-alpine builder stage compiles a statically-linked binary (CGO_ENABLED=0), and a minimal alpine:3.20 runtime stage runs the binary as a non-root swarm user:

# deploy/docker/Dockerfile (runtime stage)
FROM alpine:3.20

RUN apk add --no-cache ca-certificates tzdata curl \
    && addgroup -S swarm && adduser -S -G swarm -h /home/swarm swarm

COPY --from=builder /out/pentestswarm /usr/local/bin/pentestswarm
COPY --chown=swarm:swarm playbooks/ /usr/local/share/pentestswarm/playbooks/

USER swarm
WORKDIR /home/swarm

EXPOSE 8080
ENTRYPOINT ["pentestswarm"]
CMD ["serve"]

Development Setup

The development compose file at deploy/docker-compose.dev.yml runs only the infrastructure services — Postgres, Redis, and Ollama — leaving the pentestswarm binary to run locally with hot-reload. This avoids rebuilding the Docker image on every code change.

# deploy/docker-compose.dev.yml
version: "3.9"

services:
  postgres:
    image: pgvector/pgvector:pg16
    environment:
      POSTGRES_USER: pentestswarm
      POSTGRES_PASSWORD: pentestswarm_dev
      POSTGRES_DB: pentestswarm
    ports:
      - "5432:5432"
    volumes:
      - pgdata:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U pentestswarm"]
      interval: 5s
      timeout: 5s
      retries: 5

  redis:
    image: redis:7-alpine
    ports:
      - "6379:6379"
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 5s
      timeout: 5s
      retries: 5

  ollama:
    image: ollama/ollama:latest
    ports:
      - "11434:11434"
    volumes:
      - ollama_models:/root/.ollama
    deploy:
      resources:
        reservations:
          memory: 8G

volumes:
  pgdata:
  ollama_models:

Start the dev stack, then run the binary directly:

docker compose -f deploy/docker-compose.dev.yml up -d
make dev    # hot-reload via air or go run

The key differences from the production compose file:

Aspect	Production	Development
`pentestswarm` service	Containerized	Runs on host
Database password	Set via secrets	`pentestswarm_dev` (plaintext)
Ollama memory reservation	8 GB	8 GB
Restart policy	`unless-stopped`	n/a (no container)

Environment Variables

All configuration values from config.yaml can be overridden via environment variables prefixed with PENTESTSWARM_. The table below covers the variables you must set before the swarm can operate.

Variable	Required	Description
`PENTESTSWARM_ORCHESTRATOR_API_KEY`	Yes (Claude)	Claude API key. Equivalent to `ANTHROPIC_API_KEY`. All agents inherit this key by default — set one key, the entire swarm works.
`PENTESTSWARM_DATABASE_PASSWORD`	Yes	Postgres password. Must match `POSTGRES_PASSWORD` in the compose file.
`PENTESTSWARM_DATABASE_HOST`	No	Postgres hostname (default: `localhost`). Set to `postgres` inside Docker Compose.
`PENTESTSWARM_REDIS_HOST`	No	Redis hostname (default: `localhost`). Set to `redis` inside Docker Compose.
`PENTESTSWARM_ORCHESTRATOR_PROVIDER`	No	LLM provider: `claude` (default), `ollama`, or `lmstudio`.
`PENTESTSWARM_ORCHESTRATOR_ENDPOINT`	No	Required for `ollama` / `lmstudio` (e.g., `http://localhost:11434`).
`HACKERONE_API_TOKEN`	No	HackerOne API key for bug bounty submission. Maps to `bugbounty.hackerone_api_key`.
`HACKERONE_API_USER`	No	HackerOne username. Maps to `bugbounty.hackerone_username`.
`BUGCROWD_API_TOKEN`	No	Bugcrowd API key. Maps to `bugbounty.bugcrowd_api_key`.
`INTIGRITI_API_TOKEN`	No	Intigriti API token (see integrations config).
`ANTHROPIC_API_KEY`	No	Alternative to `PENTESTSWARM_ORCHESTRATOR_API_KEY` when using Claude.

For Claude users: ANTHROPIC_API_KEY and PENTESTSWARM_ORCHESTRATOR_API_KEY are interchangeable. Set either one and leave PENTESTSWARM_ORCHESTRATOR_PROVIDER unset — Claude is the default provider.

Full configuration reference

config.example.yaml documents every option. Copy it to config.yaml and fill in your values:

# config.example.yaml (excerpt)
server:
  host: "0.0.0.0"
  port: 8080

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

orchestrator:
  provider: "claude"
  model: "claude-sonnet-4-6"
  api_key: ""         # REQUIRED for Claude — set via PENTESTSWARM_ORCHESTRATOR_API_KEY
  context_window: 200000
  max_tokens: 8192
  temperature: 0.1

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

Database Migrations

Migrations live in internal/db/migrations/ and are applied in numeric order. Each migration is additive — no migration drops data from a previous one.

Migration	File	What it adds
`000001`	`000001_initial.sql`	Core schema: `campaigns`, `campaign_events`, `attack_surfaces`, `raw_findings`, `classified_findings`, `attack_plans`, `execution_results`, `reports`, `token_usage`. Enables `uuid-ossp`.
`000002`	`000002_pgvector.sql`	Enables the `vector` extension and adds a 1536-dimension `embedding` column to `classified_findings` with an IVFFlat cosine-ops index for semantic similarity search.
`000003`	`000003_cleanup_registry.sql`	Adds the `cleanup_actions` table used by `CleanupRegistry` to track exploitation commands that must be reversed on campaign exit.
`000004`	`000004_blackboard.sql`	Adds the stigmergic swarm blackboard: `swarm_findings`, `swarm_agent_cursors`, `swarm_budgets`. Includes the `swarm_pheromone()` SQL function and `swarm_findings_active` view for pheromone decay queries.
`000005`	`000005_agent_budgets.sql`	Adds `swarm_agent_budgets` for per-agent token caps. Soft threshold (`warn_at_tokens`) emits a WARN event; hard cap (`max_tokens`) blocks further dispatch to that agent.

Run migrations after starting the Postgres container and before starting pentestswarm serve:

pentestswarm migrate up

Or inspect the migration SQL directly:

-- 000004_blackboard.sql: pheromone decay function
CREATE OR REPLACE FUNCTION swarm_pheromone(
    base DOUBLE PRECISION,
    half_life_sec INTEGER,
    age_sec DOUBLE PRECISION
) RETURNS DOUBLE PRECISION AS $$
    SELECT base * POWER(0.5, age_sec / GREATEST(half_life_sec, 1))
$$ LANGUAGE SQL IMMUTABLE;

Server Configuration

The API server binds to 0.0.0.0:8080 by default. The port is configurable via server.port in config.yaml or PENTESTSWARM_SERVER_PORT. Health check endpoint:

curl http://localhost:8080/api/v1/health

Returns 200 OK with a JSON body when all dependencies (Postgres, Redis) are reachable. Use this as the readiness probe in Kubernetes or the healthcheck block in Docker Compose. Key API routes:

Method	Path	Description
`GET`	`/api/v1/health`	Liveness / readiness probe
`POST`	`/api/v1/campaigns`	Create a new campaign
`GET`	`/api/v1/campaigns/:id`	Get campaign status
`GET`	`/api/v1/campaigns/:id/findings`	List classified findings
`GET`	`/api/v1/campaigns/:id/report`	Download report (JSON / Markdown / SARIF)

Observability

The deploy/metrics/ directory contains a metrics aggregator (aggregator.go) that polls download counts from npm, Docker Hub, GitHub Releases, and PyPI, and serves them as a JSON API on port 3001:

# Endpoints served by deploy/metrics/aggregator.go
GET /api/metrics          # Full metrics blob (cached 1 hour)
GET /api/badge/total      # Shields.io-compatible total downloads badge
GET /api/badge/weekly     # Shields.io-compatible weekly downloads badge

For operational metrics (agent activity, pheromone heatmaps, token spend), a Grafana dashboard definition is available at deploy/metrics/grafana-swarm-dashboard.json. Import it into any Grafana 10+ instance pointing at your Postgres datasource. Campaign events are written to the campaign_events table (append-only) on every agent action, providing a queryable audit trail without additional infrastructure.

Production Checklist

Set all required environment variables

At minimum, export PENTESTSWARM_ORCHESTRATOR_API_KEY (or ANTHROPIC_API_KEY) and PENTESTSWARM_DATABASE_PASSWORD. For bug bounty workflows, add HACKERONE_API_TOKEN and HACKERONE_API_USER.

export PENTESTSWARM_ORCHESTRATOR_API_KEY=sk-ant-your-key-here
export PENTESTSWARM_DATABASE_PASSWORD=your-strong-password

Start Docker Compose

Start all services detached. The pentestswarm container will wait for Postgres and Redis health checks to pass before accepting connections.

docker compose -f deploy/docker-compose.yml up -d

Verify the health endpoint

Wait approximately 15 seconds for migrations to run, then confirm the API server is ready:

curl http://localhost:8080/api/v1/health
# Expected: {"status":"ok","postgres":"up","redis":"up"}

Run the doctor command

The built-in doctor performs an 8-point system health check covering tool availability, API key validity, database connectivity, and scope configuration:

pentestswarm doctor

All checks must pass before running a campaign against a real target.

Do not disable scope enforcement in production. The scope.enforce_strict flag is hardcoded to true and cannot be overridden via environment variables or config file. Any deployment that modifies source to disable scope enforcement is operating outside the tool’s safety design.

Hardening

Four-layer defense against MINJA and MemoryGraft memory-injection attacks

Legal Notice

Authorization requirements, AGPL-3.0 license, and responsible disclosure

Get Started

Core Concepts

CLI Reference

Guides

Security & Operations

Deploying Pentest Swarm AI with Docker and Postgres

Docker Compose

Development Setup

Environment Variables

Full configuration reference

Database Migrations

Server Configuration

Observability

Production Checklist

Hardening

Legal Notice

Build docs developers (and LLMs) love

Get Started

Core Concepts

CLI Reference

Guides

Security & Operations

Documentation Index

​Docker Compose

​Development Setup

​Environment Variables

​Full configuration reference

​Database Migrations

​Server Configuration

​Observability

​Production Checklist

Hardening

Legal Notice

Build docs developers (and LLMs) love

Docker Compose

Development Setup

Environment Variables

Full configuration reference

Database Migrations

Server Configuration

Observability

Production Checklist