Getting Started with PentestAgent

Navigation: Home > Getting Started

This guide will help you set up and run your first penetration test with PentestAgent in under 15 minutes.

System Requirements

Minimum:

8GB RAM
10GB free disk space (for Docker image)
Internet connection (for initial setup and API calls)

Recommended:

16GB+ RAM (for better performance)
SSD storage
Stable internet connection

Platform Support

PentestAgent works on:

macOS (M1/M2/M3 ARM64 and Intel)
Linux (Ubuntu, Debian, Arch, etc.)
Windows (via WSL2 or Docker Desktop)

Prerequisites

For Docker (Recommended):

Docker Desktop installed (download here)
Docker running with at least 4GB memory allocation

For Local Installation:

Python 3.10+ installed
pip package manager
Git

Option 1: Docker Installation (Recommended)

Docker is the easiest and most complete way to run PentestAgent. The Kali Docker image includes all penetration testing tools pre-installed.

Step 1: Pull the Docker Image

docker pull ghcr.io/ldesignlab/pentestagent:kali-arm64

Intel/AMD (amd64): build locally with docker compose --profile kali build (see Docker Setup).

What you get:

✅ All Kali pentesting tools (nmap, metasploit, sqlmap, hydra, gobuster, nikto, etc.)
✅ PentestAgent with all dependencies
✅ RAG knowledge base (54 security documents)
✅ Prebuilt ARM64 image; build locally for amd64

Image size: ~10-11 GB uncompressed

Step 2: Verify Installation

docker images | grep ldesignlab/pentestagent

You should see:

ghcr.io/ldesignlab/pentestagent   kali-arm64   <image-id>   <size>

Success! You're ready to configure authentication.

Authentication Setup

PentestAgent requires an LLM provider. Choose the option that best fits your needs:

Decision Tree: Which Authentication Method?

Need completely free option?
├─ YES → Use Option D (LM Studio - local models)
└─ NO ↓

Have Claude Max/Pro subscription?
├─ YES → Use Option A (OAuth - no API costs)
└─ NO ↓

Need production reliability?
├─ YES → Use Option B (Claude API - paid but reliable)
└─ NO → Use Option C (OpenAI API)

Option A: Claude Max/Pro (OAuth - No API Costs) 🎯

Best for: Development, testing, most pentesting tasks

Cost: Free (included with Claude Max/Pro subscription)

Limitations: Rate limits, no extended thinking

Get OAuth Token

# Install Claude Code CLI
npm install -g @anthropic-ai/claude-code

# Authenticate
claude setup-token

Configure

Create .env file in your project directory:

CLAUDE_CODE_OAUTH_TOKEN=sk-ant-oat01-...
PENTESTAGENT_MODEL=claude-sonnet-4-20250514

Option B: Claude API (Paid) 🏆

Best for: Production pentesting, long engagements

Cost: Pay-per-use (see Anthropic pricing)

Benefits: Higher rate limits, extended thinking support

Get API Key

Go to console.anthropic.com
Sign up or log in
Navigate to API Keys
Create a new key

Configure

Create .env:

ANTHROPIC_API_KEY=sk-ant-...
PENTESTAGENT_MODEL=claude-sonnet-4-20250514

Option C: OpenAI

Best for: Testing OpenAI models

Cost: Pay-per-use (see OpenAI pricing)

Get API Key

Go to platform.openai.com
Sign up or log in
Navigate to API Keys
Create a new key

Configure

Create .env:

OPENAI_API_KEY=sk-...
PENTESTAGENT_MODEL=gpt-5

Option D: LM Studio (Local - Free) 💻

Best for: Complete privacy, no API costs, offline testing

Cost: Free

Requirements: 16GB+ RAM, GPU recommended

Setup LM Studio

Download LM Studio
Install and open LM Studio
Download a model (recommended: bytedance/seed-oss-36b or similar)
Start the local server (Settings → Server → Start)

Configure

Create .env:

LMSTUDIO_ENABLED=true
LMSTUDIO_BASE_URL=http://localhost:1234/v1
LMSTUDIO_MODEL=your-model-name
PENTESTAGENT_EMBEDDINGS=local  # Use local embeddings

For Docker: Use http://host.docker.internal:1234/v1 as the base URL.

See also: Complete LM Studio Setup Guide

First Test Run

Now let's run your first penetration test!

Interactive TUI Mode

docker run -it --rm \
  --privileged \
  --cap-add=NET_ADMIN \
  --cap-add=NET_RAW \
  --network host \
  -v "$(pwd)/loot:/app/loot" \
  -v "$(pwd)/output:/app/output" \
  -e CLAUDE_CODE_OAUTH_TOKEN="$(grep CLAUDE_CODE_OAUTH_TOKEN .env | cut -d= -f2)" \
  -e PENTESTAGENT_MODEL="claude-sonnet-4-20250514" \
  ghcr.io/ldesignlab/pentestagent:kali-arm64

This launches the Terminal UI (TUI) with real-time tool execution visibility.

Simple Scan

Once in the TUI, try this command:

/agent scan localhost for open ports

What happens:

Agent analyzes your request
Selects appropriate tools (nmap)
Executes the scan
Interprets results
Saves findings to loot/notes.json

View Results

Press F1 to switch to notes view and see your findings.

Using Local Installation

# Activate virtual environment (if not already)
source venv/bin/activate  # Linux/macOS
.\venv\Scripts\Activate.ps1  # Launch TUI
pentestagent

# Or launch with target
pentestagent -t 192.168.1.1

Then run the same /agent scan localhost for open ports command.

Where Results Are Saved

After running a test, check these locations:

1. Notes Database: loot/notes.json

Structured findings
Categories: credential, vulnerability, finding, artifact
Searchable and filterable

2. Logs: loot/logs/<timestamp>/

Debug logs
Tool execution traces
Error messages

3. Reports: loot/reports/ (if report generation enabled)

Markdown reports
Auto-generated summaries

Viewing Notes in TUI

Keyboard shortcuts:

F1 - Toggle notes panel
F2 - Toggle tool execution sidebar
F3 - Toggle help
Ctrl+C - Exit

Notes View Features:

Filter by category
Sort by severity
Export to markdown
Search by keywords

Viewing Notes via CLI

# View all notes
pentestagent notes

# Filter by category
pentestagent notes --category vulnerability

# Export to markdown
pentestagent notes --export report.md

Example Notes Output

{
  "timestamp": "2026-01-01T12:00:00",
  "category": "vulnerability",
  "description": "Open SSH port detected on 192.168.1.100",
  "details": {
    "port": 22,
    "service": "ssh",
    "version": "OpenSSH 7.4",
    "severity": "info"
  }
}

Next Steps

Congratulations! You've successfully run your first PentestAgent scan. Here's what to explore next:

1. Try Different Modes

Assist Mode (Interactive chat):

/assist how do I test for SQL injection?

Agent Mode (Autonomous execution):

/agent enumerate web directories on example.com

Crew Mode (Multi-agent orchestration):

/crew perform complete web app pentest on example.com

Learn more: Modes Guide

2. Run Playbooks

Playbooks provide structured, multi-phase pentesting workflows:

Available playbooks:

thp3_recon - Complete reconnaissance
thp3_web - Web application testing
thp3_network - Network penetration testing

Usage:

pentestagent run -t example.com --playbook thp3_web

Learn more: Playbooks Guide

3. Explore Advanced Features

Extended Thinking (deeper reasoning):

# Add to .env
PENTESTAGENT_EXTENDED_THINKING=true

Web Search (live CVE lookups):

# Add to .env
TAVILY_API_KEY=tvly-xxx...

MCP Integration (30+ tool servers):

# See pentestagent/mcp/docker_defaults.json

4. Customize Your Setup

Docker Setup Guide - Advanced Docker configuration
Environment Variables - Complete env var reference
Performance Tuning - Token optimization

5. Join the Community

GitHub Issues: Report bugs or request features
Discussions: Ask questions
Contributing: Developer Guide

Docker: "Cannot connect to Docker daemon"

Solution:

# Or on Linux:
sudo systemctl start docker

Authentication: "No API key configured"

Solution: Double-check your .env file exists and contains the correct variables for your chosen auth method.

Local: "pentestagent: command not found"

Solution:

# Make sure virtual environment is activated
source venv/bin/activate  # Linux/macOS
.\venv\Scripts\Activate.ps1  # Windows

Docker: "Permission denied" on loot directory

Solution:

# Create loot directory with correct permissions
mkdir -p loot output
chmod 777 loot output  # Or use your user's permissions

Quick Reference

Common Commands:

# Launch TUI
pentestagent

# Run with target
pentestagent -t <target>

# Run playbook
pentestagent run -t <target> --playbook <name>

# View notes
pentestagent notes

# Get help
pentestagent --help

TUI Commands:

/agent <task>      - Run autonomous agent
/crew <task>       - Run multi-agent crew
/assist <question> - Ask for help
/target <ip/url>   - Set target
/tools             - List available tools
/notes             - View findings
/clear             - Clear screen
/exit              - Exit TUI

See also: Quick Reference Guide

Need Help?

Troubleshooting: Common issues and solutions
Documentation: Full documentation index
Support: GitHub Issues

🎉 You're ready to start pentesting with AI!

Return to README | Continue to Quick Reference

FilesExpand file tree

GETTING_STARTED.md

Latest commit

History

GETTING_STARTED.md

File metadata and controls

Getting Started with PentestAgent

System Requirements

Platform Support

Prerequisites

Option 1: Docker Installation (Recommended)

Step 1: Pull the Docker Image

Step 2: Verify Installation

Authentication Setup

Decision Tree: Which Authentication Method?

Option A: Claude Max/Pro (OAuth - No API Costs) 🎯

Get OAuth Token

Configure

Option B: Claude API (Paid) 🏆

Get API Key

Configure

Option C: OpenAI

Get API Key

Configure

Option D: LM Studio (Local - Free) 💻

Setup LM Studio

Configure

First Test Run

Interactive TUI Mode

Simple Scan

View Results

Using Local Installation

Where Results Are Saved

Viewing Notes in TUI

Viewing Notes via CLI

Example Notes Output

Next Steps

1. Try Different Modes

2. Run Playbooks

3. Explore Advanced Features

4. Customize Your Setup

5. Join the Community

Docker: "Cannot connect to Docker daemon"

Authentication: "No API key configured"

Local: "pentestagent: command not found"

Docker: "Permission denied" on loot directory

Quick Reference

Need Help?