vxcontrol/pentagi
Fully autonomous AI Agents system capable of performing complex penetration testing tasks
PentAGI
Penetration testing Artificial General Intelligence
Join the Community! Connect with security researchers, AI enthusiasts, and fellow ethical hackers. Get support, share insights, and stay updated with the latest PentAGI developments.
discord.gg/2xrMh7qX6m⠀t.me/+Ka9i6CNwe71hMWQytrendshift.io/repositories/15161
Table of Contents
• Overview
• Features
• How to Use PentAGI After Login
• Ollama
• OpenAI
• DeepSeek
• GLM
• Kimi
• Qwen
• Monitoring and Observability
• Embedding Configuration and Testing
• Function Testing with ftester
• Building
• Credits
• License
Overview
PentAGI is an innovative tool for automated security testing that leverages cutting-edge artificial intelligence technologies. The project is designed for information security professionals, researchers, and enthusiasts who need a powerful and flexible solution for conducting penetration tests.
You can watch the video PentAGI overview: youtu.be/R70x5Ddzs1o
Features
• Secure & Isolated. All operations are performed in a sandboxed Docker environment with complete isolation.
• Fully Autonomous. AI-powered agent that automatically determines and executes penetration testing steps with optional execution monitoring and intelligent task planning for enhanced reliability.
• Professional Pentesting Tools. Built-in suite of 20+ professional security tools including nmap, metasploit, sqlmap, and more.
• Smart Memory System. Long-term storage of research results and successful approaches for future use.
• Knowledge Graph Integration. Graphiti-powered knowledge graph using Neo4j for semantic relationship tracking and advanced context understanding.
• Web Intelligence. Built-in browser via scraper for gathering latest information from web sources.
• External Search Systems. Integration with advanced search APIs including Tavily, Traversaal, Perplexity, DuckDuckGo, Google Custom Search, Sploitus Search and Searxng for comprehensive information gathering.
• Team of Specialists. Delegation system with specialized AI agents for research, development, and infrastructure tasks, enhanced with optional execution monitoring and intelligent task planning for optimal performance with smaller models.
• Comprehensive Monitoring. Detailed logging and integration with Grafana/Prometheus for real-time system observation.
• Detailed Reporting. Generation of thorough vulnerability reports with exploitation guides.
• Smart Container Management. Automatic Docker image selection based on specific task requirements.
• Modern Interface. Clean and intuitive web UI for system management and monitoring.
• Comprehensive APIs. Full-featured REST and GraphQL APIs with Bearer token authentication for automation and integration.
• Persistent Storage. All commands and outputs are stored in PostgreSQL with pgvector extension.
• Scalable Architecture. Microservices-based design supporting horizontal scaling.
• Self-Hosted Solution. Complete control over your deployment and data.
• Flexible Authentication. Support for 10+ LLM providers (OpenAI, Anthropic, Google AI/Gemini, AWS Bedrock, Ollama, DeepSeek, GLM, Kimi, Qwen, Custom) plus aggregators (OpenRouter, DeepInfra). For production local deployments, see our vLLM + Qwen3.5-27B-FP8 guide.
• API Token Authentication. Secure Bearer token system for programmatic access to REST and GraphQL APIs.
• Quick Deployment. Easy setup through Docker Compose with comprehensive environment configuration.
Current Capability Boundaries
• PentAGI today is an autonomous and assistant-guided penetration testing platform, not a CALDERA-style Breach and Attack Simulation (BAS) or adversary emulation product with predefined campaigns or attack plans.
• BAS-like agent-authored attack scripts should be treated as conceptual or future work, not as a feature that is implemented today.
• The current flow report UI supports web view, copy to clipboard, Markdown download, and PDF download. JSON flow-report export is not documented as a supported output format today.
• Provider flexibility is available today through built-in providers and custom/OpenAI-compatible endpoints. See Custom LLM Provider Configuration and the vLLM + Qwen3.5-27B-FP8 guide.
Architecture
System Context
Container Architecture (click to expand)
Entity Relationship (click to expand)
Agent Interaction (click to expand)
Memory System (click to expand)
Chain Summarization (click to expand)
The chain summarization system manages conversation context growth by selectively summarizing older messages. This is critical for preventing token limits from being exceeded while maintaining conversation coherence.
The algorithm operates on a structured representation of conversation chains (ChainAST) that preserves message types including tool calls and their responses. All summarization operations maintain critical conversation flow while reducing context size.
Global Summarizer Configuration Options
Assistant Summarizer Configuration Options
Assistant instances can use customized summarization settings to fine-tune context management behavior:
The assistant summarizer configuration provides more memory for context retention compared to the global settings, preserving more recent conversation history while still ensuring efficient token usage.
Summarizer Environment Configuration
Advanced Agent Supervision (click to expand)
PentAGI includes sophisticated multi-layered agent supervision mechanisms to ensure efficient task execution, prevent infinite loops, and provide intelligent recovery from stuck states:
Execution Monitoring (Beta)
• Automatic Mentor Intervention: Adviser agent (mentor) is automatically invoked when execution patterns indicate potential issues
• Pattern Detection: Monitors identical tool calls (threshold: 5, configurable) and total tool calls (threshold: 10, configurable)
• Progress Analysis: Evaluates whether agent advances toward subtask objective, detects loops and inefficiencies
• Alternative Strategies: Recommends different approaches when current strategy fails
• Information Retrieval Guidance: Suggests searching for established solutions instead of reinventing
• Enhanced Response Format: Tool responses include both and sections
• Configurable: Enable via EXECUTION_MONITOR_ENABLED (default: false), customize thresholds with EXECUTION_MONITOR_SAME_TOOL_LIMIT and EXECUTION_MONITOR_TOTAL_TOOL_LIMIT
Best for: Smaller models (< 32B parameters), complex attack scenarios requiring continuous guidance, preventing agents from getting stuck on single approach
Performance Impact: 2-3x increase in execution time and token usage, but delivers 2x improvement in result quality based on testing with Qwen3.5-27B-FP8
Intelligent Task Planning (Beta)
• Automated Decomposition: Planner (adviser in planning mode) generates 3-7 specific, actionable steps before specialist agents begin work
• Context-Aware Plans: Analyzes full execution context via enricher agent to create informed plans
• Structured Assignment: Original request wrapped in structure with execution plan and instructions
• Scope Management: Prevents scope creep by keeping agents focused on current subtask only
• Enriched Instructions: Plans highlight critical actions, potential pitfalls, and verification points
• Configurable: Enable via AGENT_PLANNING_STEP_ENABLED (default: false)
Best for: Models < 32B parameters, complex penetration testing workflows, improving success rates on sophisticated tasks
Enhanced Adviser Configuration: Works exceptionally well when adviser agent uses stronger model or enhanced settings. Example: using same base model with maximum reasoning mode for adviser (see vllm-qwen3.5-27b-fp8.provider.yml) enables comprehensive task analysis and strategic planning from identical model architecture.
Performance Impact: Adds planning overhead but significantly improves completion rates and reduces redundant work
Tool Call Limits (Always Active)
• Hard Limits: Prevent runaway executions regardless of supervision mode status
• Differentiated by Agent Type:
• General agents (Assistant, Primary Agent, Pentester, Coder, Installer): MAX_GENERAL_AGENT_TOOL_CALLS (default: 100)
• Limited agents (Searcher, Enricher, Memorist, Generator, Reporter, Adviser, Reflector, Planner): MAX_LIMITED_AGENT_TOOL_CALLS (default: 20)
• Graceful Termination: Reflector guides agents to proper completion when approaching limits
• Resource Protection: Ensures system stability and prevents resource exhaustion
Reflector Integration (Always Active)
• Automatic Correction: Invoked when LLM fails to generate tool calls after 3 attempts
• Strategic Guidance: Analyzes failures and guides agents toward proper tool usage or barrier tools (done, ask)
• Recovery Mechanism: Provides contextual guidance based on specific failure patterns
• Limit Enforcement: Coordinates graceful termination when tool call limits are reached
Recommendations for Open Source Models
Must-Have for Models < 32B Parameters: Testing with Qwen3.5-27B-FP8 demonstrates that enabling both Execution Monitoring and Task Planning is essential for smaller open source models:
• Quality Improvement: 2x better results compared to baseline execution without supervision
• Loop Prevention: Significantly reduces infinite loops and redundant work
• Attack Diversity: Encourages exploration of multiple attack vectors instead of fixating on single approach
• Air-Gapped Deployments: Enables production-grade autonomous pentesting in closed network environments with local LLM inference
Trade-offs:
• Token consumption: 2-3x increase due to mentor/planner invocations
• Execution time: 2-3x longer due to analysis and planning steps
• Result quality: 2x improvement in completeness, accuracy, and attack coverage
• Model requirements: Works best when adviser uses enhanced configuration (higher reasoning parameters, stronger model variant, or different model)
Configuration Strategy: For optimal performance with smaller models, configure adviser agent with enhanced settings:
• Use same model with maximum reasoning mode (example: vllm-qwen3.5-27b-fp8.provider.yml)
• Or use stronger model for adviser while keeping base model for other agents
• Adjust monitoring thresholds based on task complexity and model capabilities
The architecture of PentAGI is designed to be modular, scalable, and secure. Here are the key components:
1. Core Services
• Frontend UI: React-based web interface with TypeScript for type safety
• Backend API: Go-based REST and GraphQL APIs with Bearer token authentication for programmatic access
• Vector Store: PostgreSQL with pgvector for semantic search and memory storage
• Task Queue: Async task processing system for reliable operation
• AI Agent: Multi-agent system with specialized roles for efficient testing
2. Knowledge Graph
• Graphiti: Knowledge graph API for semantic relationship tracking and contextual understanding
• Neo4j: Graph database for storing and querying relationships between entities, actions, and outcomes
• Automatic capturing of agent responses and tool executions for building comprehensive knowledge base
3. Monitoring Stack
• OpenTelemetry: Unified observability data collection and correlation
• Grafana: Real-time visualization and alerting dashboards
• VictoriaMetrics: High-performance time-series metrics storage
• Jaeger: End-to-end distributed tracing for debugging
• Loki: Scalable log aggregation and analysis
4. Analytics Platform
• Langfuse: Advanced LLM observability and performance analytics
• ClickHouse: Column-oriented analytics data warehouse
• Redis: High-speed caching and rate limiting
• MinIO: S3-compatible object storage for artifacts
5. Security Tools
• Web Scraper: Isolated browser environment for safe web interaction
• Pentesting Tools: Comprehensive suite of 20+ professional security tools
• Sandboxed Execution: All operations run in isolated containers
6. Memory Systems
• Long-term Memory: Persistent storage of knowledge and experiences
• Working Memory: Active context and goals for current operations
• Episodic Memory: Historical actions and success patterns
• Knowledge Base: Structured domain expertise and tool capabilities
• Context Management: Intelligently manages growing LLM context windows using chain summarization
The system uses Docker containers for isolation and easy deployment, with separate networks for core services, monitoring, and analytics to ensure proper security boundaries. Each component is designed to scale horizontally and can be configured for high availability in production environments.
Quick Start
System Requirements
• Docker and Docker Compose (or Podman - see Podman configuration)
• Minimum 2 vCPU
• Minimum 4GB RAM
• 20GB free disk space
• Internet access for downloading images and updates
Using Installer (Recommended)
PentAGI provides an interactive installer with a terminal-based UI for streamlined configuration and deployment. The installer guides you through system checks, LLM provider setup, search engine configuration, and security hardening.
Supported Platforms:
• Linux: amd64 download | arm64 download
• Windows: amd64 download
• macOS: amd64 (Intel) download | arm64 (M-series) download
Quick Installation (Linux amd64):
Prerequisites & Permissions:
The installer requires appropriate privileges to interact with the Docker API for proper operation. By default, it uses the Docker socket (/var/run/docker.sock) which requires either:
• Option 1 (Recommended for production): Run the installer as root:
• Option 2 (Development environments): Grant your user access to the Docker socket by adding them to the docker group: ⚠️ Security Note: Adding a user to the docker group grants root-equivalent privileges. Only do this for trusted users in controlled environments. For production deployments, consider using rootless Docker mode or running the installer with sudo.
The installer will:
1. System Checks: Verify Docker, network connectivity, and system requirements
2. Environment Setup: Create and configure .env file with optimal defaults
3. Provider Configuration: Set up LLM providers (OpenAI, Anthropic, Gemini, Bedrock, Ollama, Custom)
4. Search Engines: Configure DuckDuckGo, Google, Tavily, Traversaal, Perplexity, Sploitus, Searxng
5. Security Hardening: Generate secure credentials and configure SSL certificates
6. Deployment: Start PentAGI with docker-compose
Current Web Settings Coverage
The PentAGI web console already manages several settings areas after the server is up and running:
• Settings -> Providers: Create, edit, delete, and test user-defined provider profiles for supported provider types. These profiles control per-agent model selection, runtime parameters, reasoning options, and pricing metadata.
• Settings -> Prompts: Manage system, human, and tool prompt templates.
• Settings -> PentAGI API: Create and manage PentAGI Bearer tokens for REST and GraphQL access.
• Other UI-managed preferences: Favorite flows are stored as user preferences, and theme selection is handled from the main sidebar/profile controls rather than the Settings pages.
Still Server-Managed
The following configuration areas still need to be set on the server through environment variables, compose files, or mounted config files:
• LLM credentials and connection details: API keys, endpoints, auth modes, and provider-specific connection settings for OpenAI, Anthropic, Bedrock, Ollama, custom providers, and similar backends; config-path settings apply only where supported, such as OLLAMA_SERVER_CONFIG_PATH and LLM_SERVER_CONFIG_PATH.
• Search provider credentials and options: Settings such as DUCKDUCKGO_, GOOGLE_, TAVILY_API_KEY, TRAVERSAAL_API_KEY, PERPLEXITY_, SEARXNG_, and SPLOITUS_ENABLED.
• Third-party integrations: Langfuse, Graphiti, and similar external services remain server-side configuration.
• MCP server management: MCP settings pages are not currently exposed as a live web-console feature.
For Production & Enhanced Security:
For production deployments or security-sensitive environments, we strongly recommend using a distributed two-node architecture where worker operations are isolated on a separate server. This prevents untrusted code execution and network access issues on your main system.
See detailed guide: Worker Node Setup
The two-node setup provides:
• Isolated Execution: Worker containers run on dedicated hardware
• Network Isolation: Separate network boundaries for penetration testing
• Security Boundaries: Docker-in-Docker with TLS authentication
• OOB Attack Support: Dedicated port ranges for out-of-band techniques
Manual Installation
1. Create a working directory or clone the repository:
1. Copy .env.example to .env or download it:
1. Touch examples files (example.custom.provider.yml, example.ollama.provider.yml) or download it:
1. Fill in the required API keys in .env file.
1. Change all security related environment variables in .env file to improve security.
Security related environment variables
Main Security Settings
• COOKIE_SIGNING_SALT - Salt for cookie signing, change to random value
• PUBLIC_URL - Public URL of your server (eg. pentagi.example.com)
• SERVER_SSL_CRT and SERVER_SSL_KEY - Custom paths to your existing SSL certificate and key for HTTPS (these paths should be used in the docker-compose.yml file to mount as volumes)
Scraper Access
• SCRAPER_PUBLIC_URL - Public URL for scraper if you want to use different scraper server for public URLs
• SCRAPER_PRIVATE_URL - Private URL for scraper (local scraper server in docker-compose.yml file to access it to local URLs)
Access Credentials
• PENTAGI_POSTGRES_USER and PENTAGI_POSTGRES_PASSWORD - PostgreSQL credentials
• NEO4J_USER and NEO4J_PASSWORD - Neo4j credentials (for Graphiti knowledge graph)
1. Remove all inline comments from .env file if you want to use it in VSCode or other IDEs as a envFile option:
1. Run the PentAGI stack:
Visit localhost:8443 to access PentAGI Web UI (default is admin@pentagi.com / admin)
Web UI Accounts
PentAGI does not expose public self-service sign-up from the login page. A fresh installation creates the default local administrator account:
• Email: admin@pentagi.com
• Password: admin
On first login, change the default password before using the instance for real work. If the administrator password is lost later, use the installer maintenance menu to reset the default admin@pentagi.com account password.
For multi-user setups, an authenticated administrator can manage local users through the Users REST API (/api/v1/users/). The OpenAPI UI is available at localhost:8443/api/v1/swagger/index.html after the instance is running.
Note
If you caught an error about pentagi-network or observability-network or langfuse-network you need to run docker-compose.yml firstly to create these networks and after that run docker-compose-langfuse.yml, docker-compose-graphiti.yml, and docker-compose-observability.yml to use Langfuse, Graphiti, and Observability services.
You have to set at least one Language Model provider (OpenAI, Anthropic, Gemini, AWS Bedrock, or Ollama) to use PentAGI. AWS Bedrock provides enterprise-grade access to multiple foundation models from leading AI companies, while Ollama provides zero-cost local inference if you have sufficient computational resources. Additional API keys for search engines are optional but recommended for better results.
For fully local deployment with advanced models: See our comprehensive guide on Running PentAGI with vLLM and Qwen3.5-27B-FP8 for a production-grade local LLM setup. This configuration achieves ~13,000 TPS for prompt processing and ~650 TPS for completion on 4× RTX 5090 GPUs, supporting 12+ concurrent flows with complete independence from cloud providers.
LLM_SERVER_* environment variables are experimental feature and will be changed in the future. Right now you can use them to specify custom LLM server URL and one model for all agent types.
PROXY_URL is a global proxy URL for all LLM providers and external search systems. You can use it for isolation from external networks.
The docker-compose.yml file runs the PentAGI service as root user because it needs access to docker.sock for container management. If you're using TCP/IP network connection to Docker instead of socket file, you can remove root privileges and use the default pentagi user for better security.
Accessing PentAGI from External Networks
By default, PentAGI binds to 127.0.0.1 (localhost only) for security. To access PentAGI from other machines on your network, you need to configure external access.
Configuration Steps
1. Update .env file with your server's IP address:
Important
• Replace 192.168.1.100 with your actual server's IP address
• Do NOT use 0.0.0.0 in PUBLIC_URL or CORS_ORIGINS - use the actual IP address
• Include both localhost and your server IP in CORS_ORIGINS for flexibility
1. Recreate containers to apply the changes:
1. Verify port binding:
You should see 0.0.0.0:8443->8443/tcp or :::8443->8443/tcp.
If you see 127.0.0.1:8443->8443/tcp, the environment variable wasn't picked up. In this case, directly edit docker-compose.yml line 31:
Then recreate containers again.
1. Configure firewall to allow incoming connections on port 8443:
1. Access PentAGI:
• Local access: localhost:8443
• Network access: your-server-ip:8443
Note
You'll need to accept the self-signed SSL certificate warning in your browser when accessing via IP address.
Running PentAGI with Podman
PentAGI fully supports Podman as a Docker alternative. However, when using Podman in rootless mode, the scraper service requires special configuration because rootless containers cannot bind privileged ports (ports below 1024).
Podman Rootless Configuration
The default scraper configuration uses port 443 (HTTPS), which is a privileged port. For Podman rootless, reconfigure the scraper to use a non-privileged port:
1. Edit docker-compose.yml - modify the scraper service (around line 199):
2. Update .env file - change the scraper URL to use HTTP and port 3000:
Important
Key changes for Podman:
• Use HTTP instead of HTTPS for SCRAPER_PRIVATE_URL
• Use port 3000 instead of 443
• Change internal expose to 3000/tcp
• Update port mapping to target 3000 instead of 443
3. Recreate containers:
4. Test scraper connectivity:
If you see HTML output, the scraper is working correctly.
Podman Rootful Mode
If you're running Podman in rootful mode (with sudo), you can use the default configuration without modifications. The scraper will work on port 443 as intended.
Docker Compatibility
All Podman configurations remain fully compatible with Docker. The non-privileged port approach works identically on both container runtimes.
Assistant Configuration
PentAGI allows you to configure default behavior for assistants:
The ASSISTANT_USE_AGENTS setting affects the initial state of the "Use Agents" toggle when creating a new assistant in the UI:
• false (default): New assistants are created with agent delegation disabled by default
• true: New assistants are created with agent delegation enabled by default
Note that users can always override this setting by toggling the "Use Agents" button in the UI when creating or editing an assistant. This environment variable only controls the initial default state.
How to Use PentAGI After Login
Once the stack is running and you can sign in to the web UI, the fastest way to start is through the Flows workflow.
1. Create your first flow
1. Open Flows in the sidebar.
2. Click New Flow.
3. Choose the mode that fits your goal:
• Automation: fully autonomous execution for a testing goal you want PentAGI to carry out end-to-end
• Assistant: interactive back-and-forth help when you want to steer the investigation step by step. In this mode you can also enable the Use Agents toggle to let PentAGI delegate subtasks to specialized sub-agents for more complex investigations.
4. Select the LLM provider you want to use for this flow.
5. Describe the target and the objective in natural language in the message box.
Good first prompts usually include:
• the target system or URL
• the type of assessment you want
• any scope limitations or rules of engagement
• the result you expect, such as a vulnerability report or validation of a hypothesis
Example:
Only test systems you own or are explicitly authorized to assess. See EULA.md for the acceptable use requirements.
2. Use templates for repeatable workflows
The new flow form includes a template picker, which can prefill the message box with a saved flow template. This is useful when you run similar assessments repeatedly.
• Use an existing template if you already have one saved in Templates
• Start from the example prompt in examples/prompts/base_web_pentest.md if you need a practical baseline for web testing
• Adjust the target, scope, and constraints before starting the flow
Templates are starting points. You do not need special syntax to use PentAGI: plain natural-language instructions work well as long as the target and goal are clear.
3. Monitor execution and review output
After submitting the flow, PentAGI opens the flow page automatically.
• Use the main flow view to follow messages, agent activity, and task progress
• Inspect tool activity and terminal output as the flow runs
• Review generated tasks and subtasks to understand what PentAGI is doing
Once the flow has enough results, use the Report menu on the flow page to:
• open the report in a web view
• copy the generated report to the clipboard
• download the report as Markdown
• download the report as PDF
4. Use the Assistant view to steer an active flow
Each flow also includes an Assistant view for interactive guidance. This is useful when the autonomous run uncovers something that needs human direction instead of a hard restart.
• Open the Assistant view for the same flow when you want to inspect the current state before changing anything.
• Use the assistant to check flow status, stop the current task, submit follow-up instructions, or patch the remaining planned subtasks before the next step runs.
• Treat this as an explicit control path for the current flow, not as an invisible background queue. If you want to change direction, say so clearly and keep the new instruction tied to the current engagement scope.
• This works best for clarifying scope, redirecting priorities after intermediate findings, or answering an automation checkpoint without losing the rest of the flow context.
5. Manage flow-scoped files
Each flow has its own Files tab in the flow page. Files are scoped to the parent flow: they live in {dataDir}/flow-{id}-data/ on the host and never leak into other flows.
The tab exposes three sources of files:
• Uploads (uploads/): files you provide from the web UI. Use the Upload files action, or drag and drop directly onto the Files tab. While the agent container is running, uploaded files are also pushed into it at /work/uploads/ so the agent can read them with normal shell tools.
• Resources (resources/): files attached from your saved user resources library via Attach resources from library. Attached resources are copied into the flow and pushed into the running container at /work/resources/.
• Container (container/): snapshots pulled from the running agent container via Pull file or directory from container. These are read-only on the flow side and are never sent back to the container.
Per-file actions in the Files tab include Download, Copy path, Save as resource (promote a flow file into your reusable resources library), and Delete. The Pull action is disabled when the container is not running, with the tooltip "Container is not running".
Uploaded files and attached resources are listed automatically in the agent's system prompts via the {{.UserFiles}} template variable, which renders a compact XML block (with nested and sections), so the assistant and automation agents can reference them by path without you pasting the contents into chat. Container snapshots are visible in the UI only and are not auto-injected back into the prompt.
Current limits and limitations to be aware of:
• Maximum upload file size is 300 MB; per upload request up to 1000 files and 2 GB total. File names are capped at 255 bytes (roughly 255 ASCII characters; non-ASCII names use multiple bytes per character).
• Uploads and resources are mirrored into the running container at the fixed paths /work/uploads/ and /work/resources/; files written to other container paths are not auto-mirrored back into the flow file model. Container snapshots can originate from any container path you pull (for example /etc/...) and are cached on the flow side under container/; they are not pushed back into the container.
• Container snapshots are point-in-time pulls. Editing a snapshot in the UI does not write back into the running container.
• Deleting a flow today removes the flow record and its long-term memory entries, but does not yet archive or remove the flow's flow-{id}-data/ directory on disk. Operators are still expected to clean up the data directory manually if they want to reclaim the space.
For early testing, start with a narrow target and a single clear objective. This makes the output easier to review and helps you refine your prompts before running larger assessments.
API Access
PentAGI provides comprehensive programmatic access through both REST and GraphQL APIs, allowing you to integrate penetration testing workflows into your automation pipelines, CI/CD processes, and custom applications.
Generating API Tokens
API tokens are managed through the PentAGI web interface:
1. Navigate to Settings → API Tokens in the web UI
2. Click Create Token to generate a new API token
3. Configure token properties:
• Name (optional): A descriptive name for the token
• Expiration Date: When the token will expire (minimum 1 minute, maximum 3 years)
4. Click Create and copy the token immediately - it will only be shown once for security reasons
5. Use the token as a Bearer token in your API requests
Each token is associated with your user account and inherits your role's permissions.
Using API Tokens
Include the API token in the Authorization header of your HTTP requests:
API Exploration and Testing
PentAGI provides interactive documentation for exploring and testing API endpoints:
GraphQL Playground
Access the GraphQL Playground at your-pentagi-instance:8443/api/v1/graphql/playground
1. Click the HTTP Headers tab at the bottom
2. Add your authorization header:
3. Explore the schema, run queries, and test mutations interactively
Swagger UI
Access the REST API documentation at your-pentagi-instance:8443/api/v1/swagger/index.html
1. Click the Authorize button
2. Enter your token in the format: Bearer YOUR_API_TOKEN
3. Click Authorize to apply
4. Test endpoints directly from the Swagger UI
Generating API Clients
You can generate type-safe API clients for your preferred programming language using the schema files included with PentAGI:
GraphQL Clients
The GraphQL schema is available at:
• Web UI: Navigate to Settings to download schema.graphqls
• Direct file: backend/pkg/graph/schema.graphqls in the repository
Generate clients using tools like:
• GraphQL Code Generator (JavaScript/TypeScript): the-guild.dev/graphql/codegen
• genqlient (Go): github.com/Khan/genqlient
• Apollo iOS (Swift): apollographql.com/docs/ios
REST API Clients
The OpenAPI specification is available at:
• Swagger JSON: your-pentagi-instance:8443/api/v1/swagger/doc.json
• Swagger YAML: Available in backend/pkg/server/docs/swagger.yaml
Generate clients using:
• OpenAPI Generator: openapi-generator.tech
• Swagger Codegen: github.com/swagger-api/swagger-codegen
• swagger-typescript-api (TypeScript): github.com/acacode/swagger-typescript-api
API Usage Examples
Creating a New Flow (GraphQL)
Listing Flows (REST API)
Python Client Example
TypeScript Client Example
Security Best Practices
When working with API tokens:
• Never commit tokens to version control - use environment variables or secrets management
• Rotate tokens regularly - set appropriate expiration dates and create new tokens periodically
• Use separate tokens for different applications - makes it easier to revoke access if needed
• Monitor token usage - review API token activity in the Settings page
• Revoke unused tokens - disable or delete tokens that are no longer needed
• Use HTTPS only - never send API tokens over unencrypted connections
Token Management
• View tokens: See all your active tokens in Settings → API Tokens
• Edit tokens: Update token names or revoke tokens
• Delete tokens: Permanently remove tokens (this action cannot be undone)
• Token ID: Each token has a unique ID that can be copied for reference
The token list shows:
• Token name (if provided)
• Token ID (unique identifier)
• Status (active/revoked/expired)
• Creation date
• Expiration date
Custom LLM Provider Configuration
When using custom LLM providers with the LLM_SERVER_* variables, you can fine-tune the reasoning format used in requests.
Tip
For production-grade local deployments, consider using vLLM with Qwen3.5-27B-FP8 for optimal performance. See our comprehensive deployment guide which includes hardware requirements, configuration templates (thinking mode and non-thinking mode), and performance benchmarks showing 13K TPS prompt processing on 4× RTX 5090 GPUs.
The LLM_SERVER_PROVIDER setting is particularly useful when using LiteLLM proxy, which adds a provider prefix to model names. For example, when connecting to Moonshot API through LiteLLM, models like kimi-2.5 become moonshot/kimi-2.5. By setting LLM_SERVER_PROVIDER=moonshot, you can use the same provider configuration file for both direct API access and LiteLLM proxy access without modifications.
The LLM_SERVER_LEGACY_REASONING setting affects how reasoning parameters are sent to the LLM:
• false (default): Uses modern format where reasoning is sent as a structured object with max_tokens parameter
• true: Uses legacy format with string-based reasoning_effort parameter
This setting is important when working with different LLM providers as they may expect different reasoning formats in their API requests. If you encounter reasoning-related errors with custom providers, try changing this setting.
The LLM_SERVER_PRESERVE_REASONING setting controls whether reasoning content is preserved in multi-turn conversations:
• false (default): Reasoning content is not preserved in conversation history
• true: Reasoning content is preserved and sent in subsequent API calls
This setting is required by some LLM providers (e.g., Moonshot) that return errors like "thinking is enabled but reasoning_content is missing in assistant tool call message" when reasoning content is not included in multi-turn conversations. Enable this setting if your provider requires reasoning content to be preserved.
Ollama Provider Configuration
PentAGI supports Ollama for both local LLM inference (zero-cost, enhanced privacy) and Ollama Cloud (managed service with free tier).
Configuration Variables
Ollama Cloud Configuration
Ollama Cloud provides managed inference with a generous free tier and scalable paid plans.
Free Tier Setup (Single Model)
Paid Tier Setup (Multi-Model with Pre-built Configuration)
For paid tiers supporting multiple concurrent models, use the pre-built Ollama Cloud configuration:
The pre-built ollama-cloud.provider.yml configuration includes optimized model assignments for all agent types:
• Simple/Assistant: nemotron-3-super:cloud - Fast general-purpose model
• Primary Agent: qwen3-coder-next:cloud - Advanced reasoning with high effort mode
• Coder/Pentester: qwen3-coder-next:cloud - Specialized coding models
• Searcher: qwen3.5:397b-cloud - Large context for information gathering
• Refiner/Refactor: glm-5:cloud - High-quality text refinement
• Adviser/Enricher: minimax-m2.7:cloud - Efficient advisory tasks
• Installer: devstral-2:123b-cloud - Installation and setup tasks
Custom Configuration (Advanced)
To create your own agent configuration, mount a custom file from your host filesystem:
The PENTAGI_OLLAMA_SERVER_CONFIG_PATH environment variable maps your host configuration file to /opt/pentagi/conf/ollama.provider.yml inside the container.
Example custom configuration (my-ollama-config.yml):
Local Ollama Configuration
For self-hosted Ollama instances:
Performance Considerations:
• Model Discovery (OLLAMA_SERVER_LOAD_MODELS_ENABLED=true): Adds 1-2s startup latency querying Ollama API
• Auto-pull (OLLAMA_SERVER_PULL_MODELS_ENABLED=true): First startup may take several minutes downloading models
• Pull timeout (OLLAMA_SERVER_PULL_MODELS_TIMEOUT=900): 15 minutes in seconds
• Static Config: Disable both flags and specify models in config file for fastest startup
Creating Custom Ollama Models with Extended Context
PentAGI requires models with larger context windows than the default Ollama configurations. You need to create custom models with increased num_ctx parameter through Modelfiles. While typical agent workflows consume around 64K tokens, PentAGI uses 110K context size for safety margin and handling complex penetration testing scenarios.
Important: The num_ctx parameter can only be set during model creation via Modelfile - it cannot be changed after model creation or overridden at runtime.
Example: Qwen3 32B FP16 with Extended Context
Create a Modelfile named Modelfile_qwen3_32b_fp16_tc:
Build the custom model:
Example: QwQ 32B FP16 with Extended Context
Create a Modelfile named Modelfile_qwq_32b_fp16_tc:
Build the custom model:
Note: The QwQ 32B FP16 model requires approximately 71.3 GB VRAM for inference. Ensure your system has sufficient GPU memory before attempting to use this model.
These custom models are referenced in the pre-built provider configuration files (ollama-qwen332b-fp16-tc.provider.yml and ollama-qwq32b-fp16-tc.provider.yml) that are included in the Docker image at /opt/pentagi/conf/.
OpenAI Provider Configuration
PentAGI integrates with OpenAI's comprehensive model lineup, featuring advanced reasoning capabilities with extended chain-of-thought, agentic models with enhanced tool integration, and specialized code models for security engineering.
Configuration Variables
Configuration Examples
Supported Models
PentAGI supports 31 OpenAI models with tool calling, streaming, reasoning modes, and prompt caching. Models marked with * are used in default configuration.
GPT-5.2 Series - Latest Flagship Agentic (December 2025)
GPT-5/5.1 Series - Advanced Agentic Models
GPT-5/5.1 Codex Series - Code-Specialized
GPT-4.1 Series - Enhanced Intelligence
GPT-4o Series - Multimodal Flagship
o-Series - Advanced Reasoning Models
Prices: Per 1M tokens. Reasoning models include thinking tokens in output pricing.
Warning
GPT-5 Models - Trusted Access Required*
All GPT-5 series models (gpt-5, gpt-5.1, gpt-5.2, gpt-5-pro, gpt-5.2-pro, and all Codex variants) work unstably with PentAGI and may trigger OpenAI's cybersecurity safety mechanisms without verified access.
To use GPT-5 models reliably:*
1. Individual users: Verify your identity at chatgpt.com/cyber
2. Enterprise teams: Request trusted access through your OpenAI representative
3. Security researchers: Apply for the Cybersecurity Grant Program (includes $10M in API credits)
Recommended alternatives without verification:
• Use o-series models (o3, o4-mini, o1) for reasoning tasks
• Use gpt-4.1 series for general intelligence and function calling
• All o-series and gpt-4.x models work reliably without special access
Reasoning Effort Levels:
• High: Maximum reasoning depth (refiner - o3 with high effort)
• Medium: Balanced reasoning (primary_agent, assistant, reflector - o4-mini/o3 with medium effort)
• Low: Efficient targeted reasoning (coder, installer, pentester - o3/o4-mini with low effort; adviser - gpt-5.2 with low effort)
Key Features:
• Extended Reasoning: o-series models with chain-of-thought for complex security analysis
• Agentic Intelligence: GPT-5/5.1/5.2 series with enhanced tool integration and autonomous capabilities
• Prompt Caching: Cost reduction on repeated context (10-50% of input price)
• Code Specialization: Dedicated Codex models for vulnerability discovery and exploit development
• Multimodal Support: GPT-4o series for vision-based security assessments
• Tool Calling: Robust function calling across all models for pentesting tool orchestration
• Streaming: Real-time response streaming for interactive workflows
• Proven Track Record: Industry-leading models with CVE discoveries and real-world security applications
Anthropic Provider Configuration
PentAGI integrates with Anthropic's Claude models, featuring advanced extended thinking capabilities, exceptional safety mechanisms, and sophisticated understanding of complex security contexts with prompt caching.
Configuration Variables
Configuration Examples
Note
Google Vertex AI for Claude models
PentAGI does not currently expose a dedicated Google Vertex AI configuration path for Anthropic Claude in .env. There is no separate Vertex AI API key field at this time, and the existing Anthropic variables (ANTHROPIC_API_KEY, ANTHROPIC_SERVER_URL) target the direct Anthropic API. Supported routes for Claude are:
• Direct Anthropic API: ANTHROPIC_API_KEY and ANTHROPIC_SERVER_URL (see above).
• AWS Bedrock: BEDROCK_* variables (see AWS Bedrock Provider Configuration).
If you need to use Vertex AI today, the safest supported workaround is to expose Vertex AI through an OpenAI-compatible proxy or gateway that translates Vertex AI calls into the Chat Completions format while preserving the chat and tool-call behavior PentAGI relies on, then point the Custom LLM provider at that gateway via LLM_SERVER_URL, LLM_SERVER_KEY, and LLM_SERVER_MODEL. This path is only as reliable as the gateway you choose.
Supported Models
PentAGI supports 10 Claude models with tool calling, streaming, extended thinking, adaptive thinking, and prompt caching. Models marked with * are used in default configuration.
Claude 4 Series - Latest Models (2025-2026)
Legacy Models - Still Supported
Deprecated Models - Migrate to Current Models
Prices: Per 1M tokens. Cache pricing includes both Read and Write costs.
Extended Thinking Configuration:
• Max Tokens 4096: Generator (claude-opus-4-6) for maximum reasoning depth on complex exploit development
• Max Tokens 2048: Coder (claude-sonnet-4-6) for balanced code analysis and vulnerability research
• Max Tokens 1024: Primary agent, assistant, refiner, adviser, reflector, searcher, installer, pentester for focused reasoning on specific tasks
• Extended Thinking: All Claude 4.5+ and 4.6 models support configurable extended thinking for deep reasoning tasks
Key Features:
• Extended Thinking: All Claude 4.5+ and 4.6 models with configurable chain-of-thought reasoning depths for complex security analysis
• Adaptive Thinking: Claude 4.6 series (Opus/Sonnet) dynamically adjusts reasoning depth based on task complexity for optimal performance
• Prompt Caching: Significant cost reduction with separate read/write pricing (10% read, 125% write of input)
• Extended Context Window: 200K tokens standard, up to 1M tokens (beta) for Claude Opus/Sonnet 4.6 for comprehensive codebase analysis
• Tool Calling: Robust function calling with exceptional accuracy for security tool orchestration
• Streaming: Real-time response streaming for interactive penetration testing workflows
• Safety-First Design: Built-in safety mechanisms ensuring responsible security testing practices
• Multimodal Support: Vision capabilities in latest models for screenshot analysis and UI security assessment
• Constitutional AI: Advanced safety training providing reliable and ethical security guidance
Google AI (Gemini) Provider Configuration
PentAGI integrates with Google's Gemini models through the Google AI API, offering state-of-the-art multimodal reasoning capabilities with extended thinking and context caching.
Configuration Variables
Configuration Examples
Supported Models
PentAGI supports 9 Gemini models with tool calling, streaming, thinking modes, and context caching. Models marked with * are used in default configuration.
Gemini 3.5 Series - Latest Stable Flash (May 2026)
Gemini 3.1 Series - Stable Flash-Lite + Pro Preview (Feb-May 2026)
Gemini 2.5 Series - Advanced Thinking Models (active until October 16, 2026)
Gemma 4 Open-Source Models (Apache 2.0, Free Tier)
Prices: Per 1M tokens (Standard Paid tier). Context window is input token limit.
Note
Gemini 2.5 Series Shutdown
gemini-2.5-pro, gemini-2.5-flash, and gemini-2.5-flash-lite will be shut down on October 16, 2026. Recommended migrations:
• gemini-2.5-pro → gemini-3.1-pro-preview (same $2.00 input pricing tier)
• gemini-2.5-flash → gemini-3.5-flash (improved frontier capabilities)
• gemini-2.5-flash-lite → gemini-3.1-flash-lite (same $0.25 input pricing)
Default Model Assignments (config.yml):
• gemini-3.1-pro-preview - primary_agent, assistant, generator, refiner, adviser, coder, pentester
• gemini-3.5-flash - reflector, searcher, enricher, installer
• gemini-3.1-flash-lite - simple, simple_json
Key Features:
• Extended Thinking: Step-by-step reasoning for complex security analysis (all Gemini 3.x, 2.5 series, and Gemma 4 with toggleable thinking)
• Context Caching: Significant cost reduction on repeated context (10% of input price for most models)
• Ultra-Long Context: 1M tokens for Gemini chat models, 256K tokens for Gemma 4 open-source models
• Multimodal Support: Text, image, video, audio, and PDF processing for comprehensive assessments
• Tool Calling: Seamless integration with 20+ pentesting tools via function calling
• Streaming: Real-time response streaming for interactive security workflows
• Code Execution: Built-in code execution for offensive tool testing and exploit validation
• Search Grounding: Google Search integration for threat intelligence and CVE research
• File Search: Document retrieval and RAG capabilities for knowledge-based assessments
• Batch API: 50% cost reduction for non-real-time batch processing
• Custom Tools Endpoint: Dedicated gemini-3.1-pro-preview-customtools route for tool-heavy agentic workflows that prefer registered tools over bash
Reasoning Effort Levels:
• High: Maximum thinking depth for complex multi-step analysis (generator)
• Medium: Balanced reasoning for general agentic tasks (primary_agent, assistant, refiner, adviser)
• Low: Efficient thinking for focused tasks (coder, installer, pentester)
AWS Bedrock Provider Configuration
PentAGI integrates with Amazon Bedrock, offering access to 20+ foundation models from leading AI companies including Anthropic, Amazon, Cohere, DeepSeek, OpenAI, Qwen, Mistral, and Moonshot.
Configuration Variables
Authentication Priority: BEDROCK_DEFAULT_AUTH → BEDROCK_BEARER_TOKEN → BEDROCK_ACCESS_KEY_ID+BEDROCK_SECRET_ACCESS_KEY
Configuration Examples
Supported Models
PentAGI supports 21 AWS Bedrock models with tool calling, streaming, and multimodal capabilities. Models marked with * are used in default configuration.
Prices: Per 1M tokens. Models with thinking/reasoning support additional compute costs during reasoning phase.
Tested but Incompatible Models
Some AWS Bedrock models were tested but are not supported due to technical limitations:
Important
Rate Limits & Quota Management
Default AWS Bedrock quotas for Claude models are extremely restrictive (2-20 requests/minute for new accounts). For production penetration testing:
1. Request quota increases through AWS Service Quotas console for models you plan to use
2. Use Amazon Nova models - higher default quotas and excellent performance
3. Enable provisioned throughput for consistent high-volume testing
4. Monitor usage - AWS throttles aggressively at quota limits
Without quota increases, expect frequent delays and workflow interruptions.
Warning
Converse API Requirements
PentAGI uses Amazon Bedrock Converse API for unified model access. All supported models require:
• ✅ Converse/ConverseStream API support
• ✅ Tool use (function calling) for penetration testing workflows
• ✅ Streaming tool use for real-time feedback
Verify model capabilities at: AWS Bedrock Model Features
Key Features:
• Automatic Prompt Caching: 40-70% cost reduction on repeated context (Claude 4.x models)
• Extended Thinking: Step-by-step reasoning for complex security analysis (Claude, DeepSeek R1, OpenAI GPT)
• Multimodal Analysis: Process screenshots, diagrams, video for comprehensive testing (Nova, Claude, Mistral, Kimi)
• Tool Calling: Seamless integration with 20+ pentesting tools via function calling
• Streaming: Real-time response streaming for interactive security assessment workflows
DeepSeek Provider Configuration
PentAGI integrates with DeepSeek, providing access to advanced AI models with strong reasoning, coding capabilities, and context caching at competitive prices.
Configuration Variables
Configuration Examples
Supported Models
PentAGI supports 2 DeepSeek V4 models with tool calling, streaming, hybrid thinking/non-thinking modes, and context caching. Both models support thinking mode by default and can be switched to non-thinking mode via extra_body. Models marked with * are used in default configuration.
Prices: Per 1M tokens. Cache pricing applies to prompt tokens served from cache (input cache hit, reduced to 1/10 of launch price since 2026-04-26). Both models support hybrid thinking — thinking mode is enabled by default; pass extra_body.thinking.type: disabled to switch to non-thinking mode for faster/cheaper responses.
Pricing Note (deepseek-v4-pro): The 75% promotional discount on deepseek-v4-pro officially ended on 2026-05-31 15:59 UTC. The prices above reflect the standard post-promotional pricing. If you have legacy configurations using the discounted prices ($0.435/$0.87/$0.003625), update them to the current rates for accurate cost tracking.
The legacy model names deepseek-chat and deepseek-reasoner are scheduled for deprecation by DeepSeek on 2026-07-24. Existing user configurations referencing the legacy names continue to work until then; the defaults above use the current V4 names. deepseek-chat maps to deepseek-v4-flash non-thinking mode; deepseek-reasoner maps to deepseek-v4-flash thinking mode.
Default Agent Configuration:
Strategy: prefer deepseek-v4-flash (12x cheaper input, 12x cheaper output) as the workhorse for utility/lightweight agents; reserve deepseek-v4-pro for complex multi-step reasoning. The installer agent runs on Flash with thinking enabled because environment setup tasks (shell commands, config edits) rarely require pro-level reasoning. Run A/B tests on your own workloads before promoting more agents to Pro.
Note: When thinking mode is enabled, DeepSeek silently ignores temperature, top_p, presence_penalty, and frequency_penalty. The langchaingo client automatically nullifies temperature/top_p when reasoning_effort is set, so they appear as "(auto)" in the table above. All thinking-enabled agents also explicitly pass extra_body.thinking.type: enabled as defensive coding against future provider default changes.
Key Features:
• Hybrid Thinking Modes: Switch between thinking (deep reasoning) and non-thinking (fast) modes via extra_body.thinking.type
• Automatic Prompt Caching: Significant cost reduction on repeated context via cache-hit pricing (1/10 of launch price)
• Extended Thinking: Reinforcement learning CoT for complex security analysis (both V4 models)
• Strong Coding: Optimized for code generation and exploit development
• Long Context: 1M token context window with up to 384K output tokens
• Tool Calling: Seamless integration with 20+ pentesting tools via function calling
• Streaming: Real-time response streaming for interactive workflows
• Multilingual: Strong Chinese and English support
• Additional Features: JSON Output, Chat Prefix Completion (beta), FIM/Fill-in-the-Middle Completion (non-thinking mode only)
Concurrency Limits: deepseek-v4-flash: 2500 concurrent requests; deepseek-v4-pro: 500 concurrent requests.
LiteLLM Integration: Set DEEPSEEK_PROVIDER=deepseek to enable model name prefixing when using default PentAGI configurations with LiteLLM proxy. Leave empty for direct API usage.
GLM Provider Configuration
PentAGI integrates with GLM from Zhipu AI (Z.AI), providing advanced language models with MoE architecture, strong reasoning, and agentic capabilities developed by Tsinghua University.
Configuration Variables
Configuration Examples
Supported Models
PentAGI supports 13 GLM models with tool calling, streaming, hybrid thinking modes, and prompt caching. Models marked with * are used in default configuration. Thinking is controlled via extra_body.thinking.type ("enabled"/"disabled"); unlike Kimi, GLM is permissive about temperature in either mode.
GLM-5.x Series - Latest Generation (200K context, 128K max output)
GLM-4.7 Series - Premium with Interleaved Thinking
GLM-4.6 Series - Balanced with Auto-Thinking
GLM-4.5 Series - Unified Reasoning/Coding/Agents
GLM-4 Legacy - Dense Architecture
Prices: Per 1M tokens. Cache pricing is for prompt cache hit; cache storage is currently free per Z.AI promotion. GLM-4-32B has no cache support.
Default Agent Configuration:
Strategy: glm-5.1 (newest flagship, $1.40 input) for critical reasoning, glm-5-turbo (OpenClaw-native, agent-optimized) for orchestration, glm-4.5-air (cheap MoE with hybrid thinking and reliable RPM) for all utility/installer agents. glm-4.7-flashx is avoided as default due to lower RPM limits causing frequent 429 errors at high frequency.
Note on temperature: GLM accepts both 1.0 and 0.6 in either thinking/non-thinking mode (per Z.AI docs). langchaingo's IsReasoningModel matches glm-4.5/glm-4.6/glm-4.7* prefixes and force-overrides temperature to 1.0 in createChatRequest — this is harmless for GLM (unlike Kimi) but means temperature values for those models in YAML are advisory. glm-5/glm-5.1/glm-5-turbo are not matched, so explicit values pass through unchanged.
Thinking Modes:
• Hybrid (GLM-5.x, GLM-4.7): Explicit toggle via extra_body.thinking.type
• Auto (GLM-4.6, GLM-4.5 series): Model automatically determines when reasoning is needed
• Preserved Thinking (Z.AI Coding capability): all thinking-enabled agents in PentAGI also pass extra_body.thinking.clear_thinking: false so that reasoning_content from previous assistant turns is retained across the conversation. This is required on the standard API endpoint (/api/paas/v4) — on the Coding Plan endpoint it would be enabled by default. Improves reasoning continuity and cache hit rates in multi-turn tool call chains.
• All thinking-enabled agents also pass extra_body.tool_choice: auto defensively
Key Features:
• Long-Horizon Tasks: GLM-5.1 supports 8-hour sustained autonomous execution, ideal for complex multi-stage agentic workflows
• OpenClaw-Native Orchestration: GLM-5-Turbo is specifically optimized for tool invocation, instruction following, and long-chain execution
• Prompt Caching: Significant cost reduction on repeated context (cached input pricing shown)
• Ultra-Long Context: 200K tokens for GLM-5.x/4.7/4.6 series
• MoE Architecture: Efficient 744B/40B active (GLM-5/5.1), 355B/32B (GLM-4.5), 106B/12B (GLM-4.5-Air)
• Tool Calling: Seamless integration with 20+ pentesting tools via function calling
• Streaming: Real-time streaming with streaming tool calls support (GLM-4.6+)
• Multilingual: Exceptional Chinese and English NLP capabilities
• Free Options: GLM-4.7-Flash and GLM-4.5-Flash for prototyping and experimentation
LiteLLM Integration: Set GLM_PROVIDER=zai to enable model name prefixing when using default PentAGI configurations with LiteLLM proxy. Leave empty for direct API usage.
Kimi Provider Configuration
PentAGI integrates with Kimi from Moonshot AI, providing ultra-long context models with multimodal capabilities perfect for analyzing extensive codebases and documentation.
Configuration Variables
Configuration Examples
Supported Models
PentAGI supports 8 Kimi/Moonshot models with tool calling, streaming, hybrid thinking modes, and multimodal capabilities (text/image/video for K2.x). All kimi-k2- legacy models (turbo-preview, 0905-preview, 0711-preview, thinking, thinking-turbo) were deprecated by Moonshot on 2026-05-25 and are NOT included. Models marked with are used in default configuration.
Kimi K2.x Series - Multimodal Flagship
Moonshot V1 Series - Generation Models (Flexible Parameters)
Moonshot V1 Vision Series - Image Understanding
Prices: Per 1M tokens. Cache pricing applies to prompt tokens served from automatic context cache (only Kimi K2.x models support cache).
CRITICAL — Kimi K2.6/K2.5 parameter constraints: API returns invalid_request_error for any deviation:
• temperature: MUST be 1.0 in thinking mode, MUST be 0.6 in non-thinking mode
• top_p: MUST be 0.95
• n: MUST be 1
• presence_penalty and frequency_penalty: MUST be 0 (not modifiable)
Moonshot V1 models use standard OpenAI-compatible parameters with no such constraints.
Default Agent Configuration:
Strategy: prefer kimi-k2.5 as cost-effective workhorse (36% cheaper input vs kimi-k2.6); reserve kimi-k2.6 for critical reasoning. All kimi-k2.x agents are configured with the API-required fixed parameters (temp/top_p/n) and explicit extra_body.thinking.type. For thinking-enabled agents, extra_body.thinking.keep: "all" is set to preserve historical reasoning_content in multi-turn tool call chains (without it Moonshot returns "thinking is enabled but reasoning_content is missing").
Key Features:
• Ultra-Long Context: Up to 256K tokens (K2.x) for comprehensive codebase/documentation analysis
• Native Multimodal: K2.6/K2.5 support text + image + video input out of the box
• Hybrid Thinking: K2.6/K2.5 toggle between thinking and non-thinking via extra_body.thinking.type
• Preserved Thinking (K2.6): thinking.keep: "all" preserves historical reasoning_content across turns — required for multi-turn tool call chains
• Automatic Context Caching: K2.x models cache repeated prefixes (~17% of miss price for K2.6, ~17% for K2.5)
• Tool Calling: Full function-calling support for K2.x and Moonshot V1
• Self-Correction: K2.6 features improved instruction compliance and self-correction
• Multilingual: Strong Chinese, English, and multi-language support
Multi-turn with thinking + tool calls: PentAGI's universal reasoning preservation pattern (TextPartWithReasoning + WithPreserveReasoningContent) automatically ensures reasoning_content is sent back in the required TextContent → ToolCall order, satisfying Moonshot's "thinking is enabled but reasoning_content is missing in assistant tool call message" requirement.
LiteLLM Integration: Set KIMI_PROVIDER=moonshot to enable model name prefixing when using default PentAGI configurations with LiteLLM proxy. Leave empty for direct API usage.
Qwen Provider Configuration
PentAGI integrates with Qwen from Alibaba Cloud Model Studio (DashScope), providing powerful multilingual models with reasoning capabilities and context caching support.
Configuration Variables
Configuration Examples
Supported Models
PentAGI supports 33 Qwen models curated for agent workflows: text reasoning, code generation, and vision-language (browser screenshots). All models are non-snapshot main aliases with tool calling, streaming, thinking modes, and context caching. Models marked with * are used in default configuration.
Flagship Models (Top-tier Reasoning)
Balanced Plus Models (Mid-tier)
Fast Flash Models (Cost-optimized)
Code-Specialized Models
Vision-Language Models (Browser & Screenshot Analysis)
Open-Source Qwen3.6 Series
Open-Source Qwen3.5 Series
Open-Source Qwen3 Coder Series
Open-Source Qwen3 Dense & MoE Series
Prices: Per 1M tokens. Cache pricing reflects implicit cache hit (when available); MoE/dense open-source models do not expose cache pricing. Tiered models (Max/Plus) show lowest-tier pricing (typically ≤32k or ≤256k input); larger contexts incur higher rates per Alibaba Cloud pricing.
Region Availability:
• Intl (International): Singapore region (dashscope-intl.aliyuncs.com)
• Global/US: US Virginia region (dashscope-us.aliyuncs.com)
• China: Chinese Mainland Beijing region (dashscope.aliyuncs.com)
Default Agent Configuration:
Key Features:
• Agent-Centric Design: Qwen3.7-Max is purpose-built for long-horizon autonomous execution and tool invocation
• Automatic Context Caching: 30-50% cost reduction on repeated context with implicit cache
• Extended Thinking: Chain-of-thought reasoning for complex security analysis (Qwen3.7/3.6/3.5/3-Max, QVQ-Max)
• Code Specialization: Qwen3-Coder series with multi-turn tool interaction and repository-level understanding
• Vision-Language: Qwen3-VL series for browser screenshot triage, 2D/3D localization, OCR-level analysis
• Tool Calling: Seamless integration with 20+ pentesting tools via function calling
• Streaming: Real-time response streaming for interactive workflows
• Multilingual: Strong Chinese, English, and multi-language support
• Open-Source Variants: Dense and MoE models from 0.6B to 480B for on-premises/air-gapped deployments
LiteLLM Integration: Set QWEN_PROVIDER=dashscope to enable model name prefixing when using default PentAGI configurations with LiteLLM proxy. Leave empty for direct API usage.
Alternative Integrations
DashScope is fully OpenAI-compatible, so Qwen can also power two other PentAGI subsystems through the standard OpenAI client.
As embedding provider (text-embedding-v4, see Alibaba Cloud Model Studio pricing):
Note: the Global/US DashScope endpoint (dashscope-us.aliyuncs.com) does not expose embedding APIs — use the International or China endpoints for text-embedding-v4.
As OpenAI-typed custom LLM provider: instead of the dedicated QWEN_* variables, you can wire any Qwen chat model through PentAGI's custom OpenAI-compatible provider by pointing OPENAI_SERVER_URL (or a custom provider entry) to the DashScope /compatible-mode/v1 endpoint and selecting the desired Qwen model name. Useful when you already manage all model traffic through a single OpenAI-shaped client (e.g. shared with LiteLLM/OneAPI proxies).
Advanced Setup
Langfuse Integration
Langfuse provides advanced capabilities for monitoring and analyzing AI agent operations.
1. Configure Langfuse environment variables in existing .env file.
Langfuse valuable environment variables
Database Credentials
• LANGFUSE_POSTGRES_USER and LANGFUSE_POSTGRES_PASSWORD - Langfuse PostgreSQL credentials
• LANGFUSE_CLICKHOUSE_USER and LANGFUSE_CLICKHOUSE_PASSWORD - ClickHouse credentials
• LANGFUSE_REDIS_AUTH - Redis password
Encryption and Security Keys
• LANGFUSE_SALT - Salt for hashing in Langfuse Web UI
• LANGFUSE_ENCRYPTION_KEY - Encryption key (32 bytes in hex)
• LANGFUSE_NEXTAUTH_SECRET - Secret key for NextAuth
Admin Credentials
• LANGFUSE_INIT_USER_EMAIL - Admin email
• LANGFUSE_INIT_USER_PASSWORD - Admin password
• LANGFUSE_INIT_USER_NAME - Admin username
API Keys and Tokens
• LANGFUSE_INIT_PROJECT_PUBLIC_KEY - Project public key (used from PentAGI side too)
• LANGFUSE_INIT_PROJECT_SECRET_KEY - Project secret key (used from PentAGI side too)
S3 Storage
• LANGFUSE_S3_ACCESS_KEY_ID - S3 access key ID
• LANGFUSE_S3_SECRET_ACCESS_KEY - S3 secret access key
1. Enable integration with Langfuse for PentAGI service in .env file.
1. Run the Langfuse stack:
Visit localhost:4000 to access Langfuse Web UI with credentials from .env file:
• LANGFUSE_INIT_USER_EMAIL - Admin email
• LANGFUSE_INIT_USER_PASSWORD - Admin password
Monitoring and Observability
For detailed system operation tracking, integration with monitoring tools is available.
1. Enable integration with OpenTelemetry and all observability services for PentAGI in .env file.
1. Run the observability stack:
Visit localhost:3000 to access Grafana Web UI.
Note
If you want to use Observability stack with Langfuse, you need to enable integration in .env file to set LANGFUSE_OTEL_EXPORTER_OTLP_ENDPOINT to otelcol:4318.
To run all available stacks together (Langfuse, Graphiti, and Observability):
You can also register aliases for these commands in your shell to run it faster:
Knowledge Graph Integration (Graphiti)
Important
The Graphiti integration is currently a beta feature and has notable provider limitations. See Current Limitations below before enabling it in production.
PentAGI integrates with Graphiti, a temporal knowledge graph system powered by Neo4j, to provide advanced semantic understanding and relationship tracking for AI agent operations. The vxcontrol fork provides custom entity and edge types that are specific to pentesting purposes.
What is Graphiti?
Graphiti automatically extracts and stores structured knowledge from agent interactions, building a graph of entities, relationships, and temporal context. This enables:
• Semantic Memory: Store and recall relationships between tools, targets, vulnerabilities, and techniques
• Contextual Understanding: Track how different pentesting actions relate to each other over time
• Knowledge Reuse: Learn from past penetration tests and apply insights to new assessments
• Advanced Querying: Search for complex patterns like "What tools were effective against similar targets?"
Enabling Graphiti
The Graphiti knowledge graph is optional and disabled by default. To enable it:
1. Configure Graphiti environment variables in .env file:
1. Run the Graphiti stack along with the main PentAGI services:
1. Verify Graphiti is running:
Note
The Graphiti service is defined in docker-compose-graphiti.yml as a separate stack. You must run both compose files together to enable the knowledge graph functionality. The pre-built Docker image vxcontrol/graphiti:latest is used by default.
What Gets Stored
When enabled, PentAGI automatically captures:
• Agent Responses: All agent reasoning, analysis, and decisions
• Tool Executions: Commands executed, tools used, and their results
• Context Information: Flow, task, and subtask hierarchy
Current Limitations
The Graphiti integration is currently a beta feature. Operators should plan around the following constraints before enabling it in production:
• OpenAI-compatible LLM only. The bundled vxcontrol/graphiti image authenticates against a single OpenAI-compatible endpoint configured through PentAGI's .env variables OPEN_AI_KEY and OPEN_AI_SERVER_URL (default api.openai.com/v1). docker-compose-graphiti.yml maps these into the container as OPENAI_API_KEY and OPENAI_BASE_URL, so operators do not set the container variables directly. Provider credentials configured elsewhere in PentAGI for Anthropic, Google AI (Gemini), AWS Bedrock, DeepSeek, GLM, Kimi, or Qwen are not used by Graphiti for entity extraction. If your deployment cannot reach an OpenAI-compatible endpoint, leave GRAPHITI_ENABLED=false.
• Single fixed model per deployment. Graphiti uses one model name (GRAPHITI_MODEL_NAME, default gpt-5-mini) for all extractions. The model cannot be selected per agent or per flow.
• Independent billing. Even when a flow runs against a non-OpenAI provider, Graphiti still incurs cost on the configured OpenAI-compatible endpoint.
• No in-app graph explorer yet. Browsing the captured graph relies on the Neo4j Browser at localhost:7474 and the Graphiti Swagger UI at localhost:8000/docs. There is no PentAGI UI surface for the graph today.
When GRAPHITI_ENABLED=false, PentAGI continues to operate with its primary memory and vector store; only the additional knowledge graph features are skipped.
GitHub and Google OAuth Integration
OAuth integration with GitHub and Google allows users to authenticate using their existing accounts on these platforms. This provides several benefits:
• Simplified login process without need to create separate credentials
• Enhanced security through trusted identity providers
• Access to user profile information from GitHub/Google accounts
• Seamless integration with existing development workflows
PentAGI uses PUBLIC_URL as the public origin/base URL for OAuth redirects. In the default deployment, both GitHub and Google callbacks are handled by:
For GitHub OAuth:
1. Create a new OAuth App in your GitHub account.
2. Set Homepage URL to your PUBLIC_URL.
3. Set Authorization callback URL to ${PUBLIC_URL}/api/v1/auth/login-callback.
4. Add the client credentials to your .env file:
For Google OAuth:
1. Create OAuth credentials in your Google Cloud project.
2. Use the same callback endpoint: ${PUBLIC_URL}/api/v1/auth/login-callback.
3. Add the client credentials to your .env file:
Make sure PUBLIC_URL matches the externally accessible HTTPS address of your PentAGI instance and does not include the callback path itself. If the URL configured in the OAuth provider does not exactly match the callback generated by PentAGI, the provider will reject the login attempt with a redirect URI mismatch error.
Docker Image Configuration
PentAGI allows you to configure Docker image selection for executing various tasks. The system automatically chooses the most appropriate image based on the task type, but you can constrain this selection by specifying your preferred images:
PENTAGI_IMAGE changes the image used by the main pentagi service in docker-compose.yml. The DOCKER_DEFAULT_IMAGE and DOCKER_DEFAULT_IMAGE_FOR_PENTEST variables only affect automatic worker image selection for task execution inside PentAGI. They do not rewrite the rest of the Compose stack, so services such as pgvector, scraper, and the optional graphiti stack still use the image references defined in the compose files.
When DOCKER_DEFAULT_IMAGE and DOCKER_DEFAULT_IMAGE_FOR_PENTEST are set, AI agents will be limited to the image choices you specify. This is particularly useful for:
• Security Enforcement: Restricting usage to only verified and trusted images
• Environment Standardization: Using corporate or customized images across all operations
• Performance Optimization: Utilizing pre-built images with necessary tools already installed
Configuration examples:
Note
If a user explicitly specifies a particular Docker image in their task, the system will try to use that exact image, ignoring these settings. These variables only affect the system's automatic image selection process.
For an advanced OpenVAS/GVM experiment that uses a custom pentest image, see OpenVAS via a Custom Pentest Image.
Restricted Networks, Docker Mirrors, and Proxies
If your environment cannot reach Docker Hub (docker.io) directly, changing PentAGI environment variables is usually not enough to fix image download failures. PentAGI still relies on Docker's own registry access for Compose-managed services, and the installer network checks also validate Docker Hub reachability.
For restricted networks:
1. Confirm that the host can resolve and reach docker.io.
2. If your environment requires an outbound proxy for PentAGI or installer HTTP traffic, set the PROXY_URL environment variable. To route Docker image pulls through a proxy, configure the Docker daemon or Docker Desktop proxy separately — Docker does not use PentAGI's PROXY_URL for registry access.
3. If Docker Hub is blocked or heavily rate-limited, configure an organization-approved registry mirror or registry proxy before running the installer or docker compose up.
4. Restart Docker after changing the daemon configuration, then rerun the installer checks or Compose startup.
Example Docker daemon mirror configuration:
On Linux, this is typically configured in /etc/docker/daemon.json. On Docker Desktop, use the equivalent Docker Engine or proxy settings. A Docker Hub mirror covers Docker Hub-hosted images such as vxcontrol/*, but the main Compose stack already includes quay.io/prometheuscommunity/postgres-exporter, and the optional observability stack includes gcr.io/cadvisor/cadvisor. Those registries still need direct access or individually approved proxy/mirror paths.
See the official Docker documentation for registry mirrors and daemon proxy configuration.
Development
Development Requirements
• golang
• nodejs
• docker
• postgres
• commitlint
Environment Setup
Backend Setup
Run once cd backend && go mod download to install needed packages.
For generating swagger files have to run
before installing swag package via
For generating graphql resolver files have to run
after that you can see the generated files in pkg/graph folder.
For generating ORM methods (database package) from sqlc configuration
For generating Langfuse SDK from OpenAPI specification
and to install fern-cli
Testing
For running tests cd backend && go test -v ./...
Frontend Setup
Run once cd frontend && pnpm install to install needed packages.
For generating graphql files have to run pnpm run graphql:generate which using graphql-codegen.ts file.
Be sure that you have graphql-codegen installed globally:
After that you can run:
• pnpm run prettier to check if your code is formatted correctly
• pnpm run prettier:fix to fix it
• pnpm run lint to check if your code is linted correctly
• pnpm run lint:fix to fix it
For generating SSL certificates you need to run pnpm run ssl:generate which using generate-ssl.ts file or it will be generated automatically when you run pnpm run dev.
Backend Configuration
Edit the configuration for backend in .vscode/launch.json file:
• DATABASE_URL - PostgreSQL database URL (eg. postgres://postgres:postgres@localhost:5432/pentagidb?sslmode=disable)
• DOCKER_HOST - Docker SDK API (eg. for macOS DOCKER_HOST=unix:///Users//Library/Containers/com.docker.docker/Data/docker.raw.sock) more info
Optional:
• SERVER_PORT - Port to run the server (default: 8443)
• SERVER_USE_SSL - Enable SSL for the server (default: false)
PostgreSQL / pgvector connection pool sizing
PentAGI opens two independent connection pools to the same Postgres instance:
Additional tuning knob:
• DATABASE_MAX_IDLE_CONNS — maximum idle connections kept open in the sql.DB pool between requests (default: 5).
Budget for the stock vxcontrol/pgvector image (max_connections = 100, superuser_reserved_connections = 3):
The defaults are sized for 10 parallel flows with concurrent API requests. If you run more flows or deploy multiple PentAGI instances against the same Postgres, raise max_connections via the command override in docker-compose.yml and increase the pool sizes proportionally:
To inspect the live connection budget on a running deployment:
Frontend Configuration
Edit the configuration for frontend in .vscode/launch.json file:
• VITE_API_URL - Backend API URL. Omit the URL scheme (e.g., localhost:8080 NOT localhost:8080)
• VITE_USE_HTTPS - Enable SSL for the server (default: false)
• VITE_PORT - Port to run the server (default: 8000)
• VITE_HOST - Host to run the server (default: 0.0.0.0)
Running the Application
Backend
Run the command(s) in backend folder:
• Use .env file to set environment variables like a source .env
• Run go run cmd/pentagi/main.go to start the server
Note
The first run can take a while as dependencies and docker images need to be downloaded to setup the backend environment.
Frontend
Run the command(s) in frontend folder:
• Run pnpm install to install the dependencies
• Run pnpm run dev to run the web app
• Run pnpm run build to build the web app
Open your browser and visit the web app URL.
Testing LLM Agents
PentAGI includes a powerful utility called ctester for testing and validating LLM agent capabilities. This tool helps ensure your LLM provider configurations work correctly with different agent types, allowing you to optimize model selection for each specific agent role.
The utility features parallel testing of multiple agents, detailed reporting, and flexible configuration options.
Key Features
• Parallel Testing: Tests multiple agents simultaneously for faster results
• Comprehensive Test Suite: Evaluates basic completion, JSON responses, function calling, and penetration testing knowledge
• Detailed Reporting: Generates markdown reports with success rates and performance metrics
• Flexible Configuration: Test specific agents or test groups as needed
• Specialized Test Groups: Includes domain-specific tests for cybersecurity and penetration testing scenarios
Usage Scenarios
For Developers (with local Go environment)
If you've cloned the repository and have Go installed:
For Users (using Docker image)
If you prefer to use the pre-built Docker image without setting up a development environment:
点赞
收藏
点踩
分享