GitHub Go Weekly Trending Repositories

Tencent/WeKnora

Open-source LLM knowledge platform: turn raw documents into a queryable RAG, an autonomous reasoning agent, and a self-maintaining Wiki.

https://weknora.weixin.qq.com

| English | 简体中文 | 日本語 | 한국어 |

Overview • Architecture • Key Features • Getting Started • API Reference • Developer Guide

💡 WeKnora — Turn Documents into Living Knowledge with RAG, Agents and Auto-Wiki

📌 Overview

WeKnora is an open-source, LLM-powered knowledge framework built for enterprise-grade document understanding, semantic retrieval, and autonomous reasoning.

https://github.com/user-attachments/assets/19b28ce2-a62f-4f54-b289-c983576259bc

2:25 · 1080p · English narration & captions.

It is organized around three core capabilities: RAG-based Quick Q&A for everyday lookups, a ReAct Agent that autonomously orchestrates retrieval, MCP tools, a tenant skill catalog, session-persistent Docker / E2B / Cube sandboxes and web search to handle complex multi-step tasks, and a brand-new Wiki Mode in which agents distill raw documents into a self-maintaining, interlinked markdown knowledge base with an interactive knowledge graph, complete with manual editing, revision history and one-click rollback. Cross-session long-term memory remembers who you are and what you keep asking about. Knowledge curation is equally hands-on: a tree-structured folder view preserves the directory layout of uploads, and chunk editing with revision history lets retrieval chunks be edited, diffed and reverted like documents. Combined with multi-source ingestion (Feishu wiki / Feishu Drive / GitLab / Tencent IMA / Notion / Yuque / RSS, and growing), website embed widgets for publishing agents to external sites, scoped API keys with a principal model for programmatic integrations, multi-instance storage backends per workspace for flexible data placement, 20+ LLM provider integrations (including LiteLLM), full Langfuse observability plus a runtime task-queue dashboard with worker-pool governance, enterprise-ready multi-workspace RBAC (4-tier role matrix + per-resource ownership + per-workspace audit log), and a fully self-hostable modular architecture, WeKnora turns scattered documents into a queryable, reasoning-capable, continuously evolving knowledge asset.

The framework supports auto-syncing knowledge from Feishu, GitLab, Tencent IMA, Notion, and Yuque (more data sources coming soon), handles 10+ document formats including PDF, Word, images, Excel and XMind, and can serve Q&A directly through IM channels like WeCom, Feishu, Slack, and Telegram. It is compatible with major LLM providers including OpenAI, DeepSeek, Qwen (Alibaba Cloud), Zhipu, Hunyuan, Gemini, MiniMax, NVIDIA, LiteLLM, and Ollama. Office files can be parsed in-process with anydoc. Its fully modular design allows swapping LLMs, vector databases, and storage backends, with support for local and private cloud deployment ensuring complete data sovereignty. WeKnora also integrates with Langfuse for comprehensive observability into agent reasoning, token usage, and pipeline tracing.

✨ Latest Updates

v0.8.0 — Skill sandbox runtime (session-persistent Docker / E2B / Cube backends with per-tenant network policy; Local host-process backend removed; Docker opt-in); tenant skill catalog (install from ClawHub / SkillHub / git / zip, per-sandbox snapshots, live progress, file browse/edit, personal and workspace env vars); cross-session long-term memory (profile / preference / fact / task / interest, auto-extract with confirm, search_memory); in-process anydoc office parser; official DeepSeek Harness plugin @wxg-prc-cpg/dsh-weknora; GitLab and Tencent IMA data sources; LiteLLM; Exa and Metaso web search; XMind parsing; chat artifacts, question outline and timestamps; context compaction and provider prompt-cache markers. Plus OIDC JWKS verification, optional complex passwords, document auto-tagging, and broad sandbox/security hardening. See CHANGELOG.md.
v0.7.2 — Launched the official product documentation site (VitePress; six sections, ~50 pages covering ~360 API endpoints and ~150 environment variables, with standalone Docker/Nginx deployment, quickstart sample data and a local MCP demo); knowledge base folder tree (upload paths stored as first-class data, browse/rename/re-file documents like a file manager); chunk editing with revision history (edit retrieval chunks in the UI, per-version diff and rollback, automatic reindexing, plus custom document metadata); Wiki page revision history (snapshots + line-level diff + one-click rollback + in-browser manual editing); directly loadable file URLs via resource_urls=public / RESOURCE_URL_MODE (third-party apps render images and files without a second authenticated proxy call); Feishu Drive data source and docx sync through the blocks API; batch document tagging; MCP Server 1.1.x (migrated to the mcp 2.x high-level API, official PyPI package tencent-weknora-mcp, new create_knowledge_from_text and list_shared_knowledge_bases for 29 tools total); AWS S3 default credential chain (IAM Role / IRSA); local HTML upload parsing; QQBot markdown replies; new PR CI checks for app / frontend / docreader / mcp-server. Plus large-scale router and modelcontext refactors, rerank and chunking quality work, and broad stability fixes. See CHANGELOG.md.
v0.7.1 — New Yunzhijia (云之家) IM integration (WebSocket + image messages + markdown replies); Volcengine rerank provider (with request batching) and Zhipu AI web search provider; platform-scoped API keys for control-plane automation (tenant management, system settings, runtime queues, audit logs); per-KB activity audit trail; FAQ management enhancements (filtering, tagging, export, import tracking); Langfuse OTLP/OTel tracing migration with W3C traceparent propagation; chat header actions with one-click Markdown export and wiki tool results in the references drawer; prompt-cache observability; session channel governance (admin-scoped IM/embed/API sessions); resilient Feishu large-wiki sync; and removal of the legacy Neo4j conversation-memory dependency. Plus broad slug-integrity, SSRF-transport, and state-sync hardening. See CHANGELOG.md.
v0.7.0 — Fine-grained scoped API keys & principal model (capability-level grants + per-KB restriction + API integration playground); runtime task-queue observability dashboard & worker-pool governance (per-stage pools + per-model concurrency governors + failed-task inspection/retry); multi-instance storage backends (multiple storage instances per workspace, per-KB binding, default instance); session-scoped temporary attachments (async image/doc parsing + combined limits); question & follow-up suggestions; stable resource registry with LLM-context alias compaction; @Skill / @MCP mentions with scoped agent runtime; mid-conversation MCP OAuth; QQBot & Lark (Feishu International) IM integration; Redis TLS; Requesty model provider + Keenable web search; tenantless provisioning & gated self-service workspaces; admin password reset; knowledge base duplicate flow; weknora CLI v0.10. Plus broad security hardening (SSRF, secret redaction, SQL validation, IDOR). See CHANGELOG.md.
v0.6.3 — Website embed widget & Integrations Center (secure-mode token exchange + rate limits); chat experience overhaul (citation popovers, RAG pipeline progress, streaming markdown); document multi-tag & batch reparse; Wiki folders & hierarchy navigation; RSS data source; MCP OAuth2; EPUB / MHTML parsing; agent model-readiness checks; model test debugger; session source filter; workspace deletion UI. See CHANGELOG.md.
v0.6.2 — Per-upload process configuration with upload-confirm dialog; document reparse with process_config; weknora CLI v0.9 (bundled Agent Skills, session stop, auth/profile harmonization); KB marquee multi-select; HNSW index for 1024-dim pgvector embeddings; chat resources store refactor; Langfuse-only tracing (Jaeger removed). See CHANGELOG.md.
v0.6.1 — Document parsing trace timeline (Langfuse-style span tree with stage-by-stage progress + stop-parse); OpenSearch vector store driver; declarative built-in models via YAML; system admin & consolidated platform settings + audit log; new-user onboarding guide; settings UI redesign; weknora CLI v0.7 / v0.8 (agent-first wire contract, NDJSON, --dry-run); OpenDataLoader + PaddleOCR-VL parsers; MCP server multi-transport (stdio / SSE / HTTP); per-model thinking-mode config; Tencent LKEAP rerank + native Gemini embeddings + MiniMax-M3. See CHANGELOG.md.
v0.6.0 — Workspace RBAC (4-tier role matrix Owner / Admin / Contributor / Viewer + per-KB ownership + per-workspace audit log), workspace member management & multi-workspace UX, self-service workspaces; weknora CLI v0.4 GA with mcp serve; KB retrieval fan-out across vector stores; AES-256-GCM credential encryption + docreader gRPC TLS + Token; Zhipu embedder + Huawei OBS; server-side user preferences; Go 1.26.0. See docs/RBAC说明.md and CHANGELOG.md.
v0.5.2 — Wiki ingest scales to 40k-document KBs (task queue + DLQ); MCP human-in-the-loop tool approval; Anthropic / Apache Doris / Tencent VectorDB / KS3 / SearXNG backends; adaptive 3-tier chunking with live preview; global ⌘K command palette; Yuque connector + WeChat Mini Program; weknora CLI preview.
v0.5.1 — Knowledge-base batch management; workspace-wide IM channels overview; session search + user-scoped pinning; unified Model / Web Search / MCP settings cards; per-agent LLM timeout; desktop workspace switching.
v0.5.0 — Wiki Mode GA — agents auto-generate structured, interlinked Markdown wiki pages with a knowledge graph; wiki browser + visual graph in the UI.
v0.4.0 — WeKnora Cloud (hosted LLM + parsing); Chrome Extension; ClawHub Skill; WeChat IM; attachment processing; Azure OpenAI / Alibaba OSS; Notion connector; Baidu + Ollama web search; VectorStore management.
v0.3.6 — ASR (audio); Feishu data-source auto-sync; OIDC; IM quote-reply context + thread-based sessions; document summarization; Tavily search; parallel tool calling; agent @mention scope restriction.
v0.3.5 — Telegram / DingTalk / Mattermost IM; IM slash commands + QA queue; suggested questions; VLM auto-describe MCP tool images; Novita AI; channel tracking.
v0.3.4 — WeCom / Feishu / Slack IM; multimodal image support; NVIDIA model API; Weaviate; AWS S3; AES-256-GCM API-key encryption; built-in MCP service; hybrid-search optimization; final_answer tool.
v0.3.3 — Parent-child chunking; KB pinning; fallback response; passage cleaning for rerank; storage auto-creation; Milvus.
v0.3.2 — Knowledge Search entry; per-source parser & storage engine config; image rendering in local storage; document preview; Volcengine TOS; Mermaid rendering; batch session management; memory graph preview.
v0.3.0 — Shared Space; Agent Skills + sandboxed execution; custom agents; Data Analyst agent; thinking mode; Bing / Google web search; API Key auth; Helm chart; Korean i18n; Qdrant.
v0.2.0 — Agent Mode (ReACT); multi-type knowledge bases (FAQ + document); conversation strategy config; DuckDuckGo web search; MCP tool integration; new UI with agent mode switching; MQ async task management.

📱 Interface Showcase

🛠️ Skill Sandbox Chat · generate and preview a Word file
📦 Skill Catalog · install onto an E2B sandbox	🤖 Agent Mode · search, read a skill, write sandbox files
💬 Intelligent Q&A Conversation
📖 Wiki Browser	🕸️ Wiki Knowledge Graph
🕘 Wiki Page Revision History & Rollback	✂️ Chunk Editing & Revision History
📁 Folder Tree & Batch Operations	🔭 Observability · Langfuse Tracing

🏗️ Architecture

Fully modular pipeline from document parsing, vectorization, and retrieval to LLM inference — every component is swappable and extensible. Supports local / private cloud deployment with full data sovereignty and a zero-barrier Web UI for quick onboarding.

🧩 Feature Overview

Intelligent Conversation

Capability	Details
Intelligent Reasoning	ReACT progressive multi-step reasoning, autonomously orchestrating knowledge retrieval, MCP tools, skill sandboxes, and web search
Quick Q&A	RAG-based Q&A over knowledge bases for fast and accurate answers
Wiki Mode	Agent-driven auto-generation of structured, interlinked markdown Wiki pages from raw documents; in-browser manual editing, page revision history, line-level diff and one-click rollback
Skill Catalog & Sandbox	Workspace skill catalog (ClawHub / SkillHub / git / zip) installed onto session-persistent Docker / E2B / Cube sandboxes; `shell_exec`, file tools, artifacts, per-config network policy; Local host-process backend removed
Long-term Memory	Cross-session memory (profile / preference / fact / task / interest) with auto-extract, user confirm, and on-demand `search_memory`
Tool Calling	Built-in tools, MCP tools (incl. OAuth2 remote services, mid-conversation OAuth), web search; `@Skill / @MCP` mentions to scope the agent runtime per turn
Conversation Strategy	Online Prompt editing, retrieval threshold tuning, multi-turn context awareness, per-agent citation output toggle
Suggested Questions	Auto-generated question suggestions and after-answer follow-ups based on knowledge base content
Temporary Attachments	Session-scoped image / document uploads with async parsing for one-off Q&A, with a combined image + attachment limit
Citations & RAG Progress	Inline citation popovers and a references drawer (web / KB source distinction), shared markdown rendering, and stage-by-stage RAG pipeline progress in chat
Session Management	Filter and group sidebar sessions by source (Web / IM / Embed), with inline session-title rename

Knowledge Management

Capability	Details
Knowledge Base Types	FAQ / Document / Wiki with folder import, URL import, multi-tag management, and online entry
Folder Tree	Folder uploads keep their original directory structure, with a sidebar tree for browsing, folder rename, and re-filing documents into another folder
Chunk Editing & Revisions	Edit retrieval chunks directly in the UI with per-version snapshots, diff and one-click rollback, and automatic reindexing after an edit; generated questions can be added, edited, deleted and regenerated; custom document metadata supported
Per-Upload Process Config	Override parser, chunking, multimodal (VLM / ASR), graph extraction, and question generation per upload batch via upload-confirm dialog or `process_config` API; reparse with new settings
Batch Reparse	Re-queue parsing for multiple documents at once with optional per-batch `process_config`
Data Source Import	Auto-sync from Feishu wiki / Feishu Drive / Lark / GitLab / Tencent IMA / Notion / Yuque / RSS feeds (more data sources coming soon); incremental and full sync
Document Formats	PDF / Word / Txt / Markdown / HTML / EPUB / MHTML / Images / CSV / Excel / PPT / JSON / XMind
Auto-Tagging	After parse, pick matching tags from the knowledge base's existing set without creating tags or overwriting manual ones
Retrieval Strategies	BM25 sparse / Dense retrieval / GraphRAG / parent-child chunking / HNSW-accelerated pgvector (1024-dim) / multi-dimensional indexing
Batch Selection & Tagging	Marquee drag-select multiple documents in the KB list for batch reparse and batch tagging (common tags pre-selected)
E2E Testing	Full-pipeline visualization with recall hit rate, BLEU / ROUGE metric evaluation

Integrations & Extensions

Capability	Details
LLMs	OpenAI / Azure OpenAI / Anthropic (Claude) / DeepSeek / Qwen (Alibaba Cloud) / Zhipu / Hunyuan / Doubao (Volcengine) / Gemini / MiniMax / NVIDIA / Novita AI / SiliconFlow / OpenRouter / Requesty / LiteLLM / Ollama
Embeddings	Ollama / BGE / GTE / Zhipu / OpenAI-compatible APIs
Vector DBs	PostgreSQL (pgvector) / Elasticsearch / OpenSearch / Milvus / Weaviate / Qdrant / Apache Doris / Tencent VectorDB
Object Storage	Local / MinIO / AWS S3 (IAM Role / IRSA default credential chain) / Volcengine TOS / Alibaba Cloud OSS / Kingsoft Cloud KS3 / Huawei Cloud OBS; multiple storage instances per workspace with per-KB binding and a default instance
IM Channels	WeCom / Feishu / Lark (Feishu International) / QQBot / Slack / Telegram / DingTalk / Mattermost / WeChat / Yunzhijia
Website Embed	Publish agents via embed widget with domain allowlists, rate limits, and secure-mode token exchange
Web Search	DuckDuckGo / Bing / Google / Tavily / Baidu / Ollama / SearXNG / Keenable / Zhipu AI / Exa / Metaso
API Integration	Scoped API keys (capability-level grants + per-KB restriction + throttled last-used tracking) with an API integration playground; MCP OAuth and embed sessions isolated per principal; `resource_urls=public` returns directly loadable file/image URLs, removing the second authenticated proxy call
MCP Server	Official PyPI package `tencent-weknora-mcp` with 29 tools over stdio / SSE / HTTP transports

Platform

Capability	Details
Deployment	Local / Docker / Kubernetes (Helm) with private and offline support
UI	Web UI / RESTful API / CLI (`weknora`) / Chrome Extension / Website Embed Widget / WeChat Mini Program
Access Control	Workspace RBAC with 4-tier role matrix (Owner / Admin / Contributor / Viewer), per-KB resource ownership, per-workspace audit log, invite-only workspaces, tenantless provisioning & gated self-service workspace creation, admin password reset (session revocation), cross-workspace superuser, scoped API keys
Security	AES-256-GCM at-rest encryption for API keys and MCP / data-source credentials with graceful key rotation; gRPC TLS + Token between app and docreader; Redis TLS; SSRF-safe HTTP client (data sources, URL import, redirect chains); secret redaction in responses; skill sandbox isolation (Docker opt-in / E2B / Cube) with per-config network policy; OIDC ID-token JWKS verification; optional complex-password policy
Observability	Integrated Langfuse (sole tracing backend) for ReAct loops, token tracking, tool calls, and pipeline tracing; built-in Langfuse-style document parsing trace timeline with stage-by-stage progress; system-admin runtime task-queue dashboard (queue depth, per-model concurrency, failed-task inspection & manual retry)
Task Management	MQ async tasks with per-stage worker-pool governance (core / post-process / enrichment / maintenance + elastic shared pool, plus an independent Wiki pool) and per-model background concurrency governors; automatic database migration on version upgrade
Model Management	Centralized config, declarative built-in models via YAML, per-knowledge-base model selection, per-model thinking-mode and embedding-dimension overrides, interactive model test debugger, multi-workspace built-in model sharing, WeKnora Cloud hosted models and parsing

🧩 Chrome Extension

WeKnora Chrome Extension lets you capture web content directly into your WeKnora knowledge base. Select text, images, or entire pages in the browser and save them as knowledge entries with one click — no copy-paste or file upload needed.

📱 WeChat Mini Program

The WeKnora Mini Program provides a lightweight mobile client for configuring WeKnora API access, selecting knowledge bases, importing URLs, and asking knowledge chat from WeChat.

🦞 ClawHub Skill

WeKnora ClawHub Skill is a WeKnora skill published on the ClawHub platform. Once installed, it enables document import (file / URL / Markdown), hybrid search (vector + keyword) across knowledge bases, and knowledge entry management — all through the WeKnora REST API.

Document Import — Upload files, import web pages, or write Markdown knowledge via the agent
Hybrid Search — Search within or across knowledge bases with vector + keyword retrieval
Knowledge Management — List, browse, edit, and delete knowledge entries programmatically

🐋 DeepSeek Harness Plugin

@wxg-prc-cpg/dsh-weknora is the official DeepSeek Harness (dsh) plugin (docs). The harness ships no retrieval, embedding or knowledge-base capability of its own, so the plugin gives a coding agent your documents: dsh plugin --profile web add @wxg-prc-cpg/dsh-weknora, point it at a deployment, and four read-only tools appear in the agent's tool set.

weknora_search — hybrid retrieval returning source passages verbatim, each with a reusable knowledge_id
weknora_read_document — one document's passages reassembled in order, with paging
weknora_ask — WeKnora's own composed answer with citations, over the RAG or the ReAct pipeline
weknora_list_knowledge_bases — knowledge base names and ids, so the agent can scope its own search

⌨️ Command-Line Interface

weknora is the official CLI for driving the API from a terminal or an AI agent. It is agent-first: every command emits a stable JSON envelope by default (with typed error codes mapped to exit codes), and --format text renders for humans. It also serves a curated MCP tool surface (weknora mcp serve) and ships bundled Agent Skills.

weknora profile add prod --host https://kb.example.com --use
weknora auth login
weknora kb list
weknora link --kb my-knowledge-base    # bind the current directory
weknora doc upload notes.md
weknora chat "summarise the design doc"

For headless / CI use, set WEKNORA_API_KEY + WEKNORA_HOST and skip auth login entirely — no credentials written to disk.

See cli/README.md for install + 5-minute quickstart and cli/AGENTS.md for the operational contract AI agents rely on.

🚀 Getting Started

🛠 Prerequisites

Docker & Docker Compose
Git

📦 Installation & Launch

git clone https://github.com/Tencent/WeKnora.git
cd WeKnora
cp .env.example .env   # Edit .env as needed, see comments in the file
docker compose pull     # Pull the latest images
docker compose up -d    # Start core services

Once started, visit http://localhost to get started.

To use a local Ollama model, run ollama serve > /dev/null 2>&1 & first.

🔄 Upgrading

If you already have WeKnora running and downloaded a newer release:

# Set WEKNORA_VERSION in .env to the target release (e.g. 0.7.0), or keep latest
docker compose pull     # Pull images matching WEKNORA_VERSION
docker compose up -d    # Recreate containers with new images

docker compose up -d alone reuses locally cached images and may leave the UI version out of sync with the release you downloaded.

🔧 Optional Services (Docker Compose Profiles)

Add --profile flags to enable additional components. Multiple profiles can be combined:

Profile	Description	Command
(default)	Core services	`docker compose pull && docker compose up -d`
`full`	All features	`docker compose --profile full pull && docker compose --profile full up -d`
`neo4j`	Knowledge Graph (Neo4j)	`docker compose --profile neo4j pull && docker compose --profile neo4j up -d`
`minio`	Object Storage (MinIO)	`docker compose --profile minio pull && docker compose --profile minio up -d`
`langfuse`	Tracing (Langfuse)	`docker compose --profile langfuse pull && docker compose --profile langfuse up -d`

Combine profiles: docker compose --profile neo4j --profile minio pull && docker compose --profile neo4j --profile minio up -d

Stop services: docker compose down

🌐 Service URLs

Service	URL
Web UI	`http://localhost`
Backend API	`http://localhost:8080`
Langfuse Tracing	`http://localhost:3000`

MCP Server

Please refer to the MCP Configuration Guide for the necessary setup.

🔌 Using WeChat Dialog Open Platform

WeKnora serves as the core technology framework for the WeChat Dialog Open Platform, providing a more convenient usage approach:

Zero-code Deployment: Simply upload knowledge to quickly deploy intelligent Q&A services within the WeChat ecosystem, achieving an "ask and answer" experience
Efficient Question Management: Support for categorized management of high-frequency questions, with rich data tools to ensure accurate, reliable, and easily maintainable answers
WeChat Ecosystem Integration: Through the WeChat Dialog Open Platform, WeKnora's intelligent Q&A capabilities can be seamlessly integrated into WeChat Official Accounts, Mini Programs, and other WeChat scenarios, enhancing user interaction experiences

📘 API Reference

Official product documentation: website-docs/ — the complete documentation set organized as Getting Started → Architecture → Features → API → Clients → Development, covering ~360 API endpoints, ~150 environment variables, and 9 extension points. The directory is also a VitePress site: run cd website-docs && npm install && npm run dev to preview locally, or deploy it standalone with the Dockerfile inside.

Troubleshooting FAQ: Troubleshooting FAQ

Detailed API documentation is available at: API Docs

Product plans and upcoming features: Roadmap

🧭 Developer Guide

⚡ Fast Development Mode (Recommended)

If you need to frequently modify code, you don't need to rebuild Docker images every time! Use fast development mode:

# Start infrastructure
make dev-start

# Start backend (new terminal)
make dev-app

# Start frontend (new terminal)
make dev-frontend

Development Advantages:

✅ Frontend modifications auto hot-reload (no restart needed)
✅ Backend modifications quick restart (5-10 seconds, supports Air hot-reload)
✅ No need to rebuild Docker images
✅ Support IDE breakpoint debugging

Detailed Documentation: Development Environment Quick Start

🤝 Contributing

Welcome to submit Issues or Pull Requests.

Process: Fork → Create branch → Commit changes → Open PR

Standards: Format code with gofmt, follow Conventional Commits (feat: / fix: / docs: / test: / refactor:)

Validation

For a focused PR, validate the changed scope first:

git fetch origin main
git diff --check origin/main...HEAD
golangci-lint run --new-from-rev=origin/main ./...
go test ./path/to/changed/package -count=1

Run gofmt on changed Go files before committing. For frontend changes, run the relevant tests from frontend/ and use npm run type-check when the change affects TypeScript or Vue components.

The full maintainer gate remains:

make fmt
make lint
make test

make fmt formats the entire Go repository, so run it only with a clean worktree and review the resulting diff. Some full-suite tests require local infrastructure or service configuration. If a full check fails for an unrelated baseline or environment reason, include the exact command and failure in the PR while still providing passing targeted tests for your change.

🔒 Security Notice

Important: Starting from v0.1.3, WeKnora includes login authentication functionality to enhance system security. For production deployments, we strongly recommend:

Deploy WeKnora services in internal/private network environments rather than public internet
Avoid exposing the service directly to public networks to prevent potential information leakage
Configure proper firewall rules and access controls for your deployment environment
Regularly update to the latest version for security patches and improvements

👥 Contributors

Thanks to these excellent contributors:

📄 License

This project is licensed under the MIT License. You are free to use, modify, and distribute the code with proper attribution.

vxcontrol/pentagi

Fully autonomous AI Agents system capable of performing complex penetration testing tasks

https://pentagi.com

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.

⠀

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:

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.
Optional 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, Firecrawl, 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, MiniMax, Custom) plus aggregators (OpenRouter, DeepInfra, Atlas Cloud, OpenCode Go plan). 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

flowchart TB
    classDef person fill:#08427B,stroke:#073B6F,color:#fff
    classDef system fill:#1168BD,stroke:#0B4884,color:#fff
    classDef external fill:#666666,stroke:#0B4884,color:#fff

    pentester["👤 Security Engineer
    (User of the system)"]

    pentagi["✨ PentAGI
    (Autonomous penetration testing system)"]

    target["🎯 target-system
    (System under test)"]
    llm["🧠 llm-provider
    (OpenAI/Anthropic/Ollama/Bedrock/Gemini/Custom)"]
    search["🔍 search-systems
    (Google/DuckDuckGo/Tavily/Firecrawl/Traversaal/Perplexity/Sploitus/Searxng)"]
    langfuse["📊 langfuse-ui
    (LLM Observability Dashboard)"]
    grafana["📈 grafana
    (System Monitoring Dashboard)"]

    pentester --> |Uses HTTPS| pentagi
    pentester --> |Monitors AI HTTPS| langfuse
    pentester --> |Monitors System HTTPS| grafana
    pentagi --> |Tests Various protocols| target
    pentagi --> |Queries HTTPS| llm
    pentagi --> |Searches HTTPS| search
    pentagi --> |Reports HTTPS| langfuse
    pentagi --> |Reports HTTPS| grafana

    class pentester person
    class pentagi system
    class target,llm,search,langfuse,grafana external

    linkStyle default stroke:#ffffff,color:#ffffff

Container Architecture (click to expand)

graph TB
    subgraph Core Services
        UI[Frontend UI<br/>React + TypeScript]
        API[Backend API<br/>Go + GraphQL]
        DB[(Vector Store<br/>PostgreSQL + pgvector)]
        MQ[Task Queue<br/>Async Processing]
        Agent[AI Agents<br/>Multi-Agent System]
    end

    subgraph Knowledge Graph
        Graphiti[Graphiti<br/>Knowledge Graph API]
        Neo4j[(Neo4j<br/>Graph Database)]
    end

    subgraph Monitoring
        Grafana[Grafana<br/>Dashboards]
        VictoriaMetrics[VictoriaMetrics<br/>Time-series DB]
        Jaeger[Jaeger<br/>Distributed Tracing]
        Loki[Loki<br/>Log Aggregation]
        OTEL[OpenTelemetry<br/>Data Collection]
    end

    subgraph Analytics
        Langfuse[Langfuse<br/>LLM Analytics]
        ClickHouse[ClickHouse<br/>Analytics DB]
        Redis[Redis<br/>Cache + Rate Limiter]
        MinIO[MinIO<br/>S3 Storage]
    end

    subgraph Security Tools
        Scraper[Web Scraper<br/>Isolated Browser]
        PenTest[Security Tools<br/>20+ Pro Tools<br/>Sandboxed Execution]
    end

    UI --> |HTTP/WS| API
    API --> |SQL| DB
    API --> |Events| MQ
    MQ --> |Tasks| Agent
    Agent --> |Commands| PenTest
    Agent --> |Queries| DB
    Agent --> |Knowledge| Graphiti
    Graphiti --> |Graph| Neo4j

    API --> |Telemetry| OTEL
    OTEL --> |Metrics| VictoriaMetrics
    OTEL --> |Traces| Jaeger
    OTEL --> |Logs| Loki

    Grafana --> |Query| VictoriaMetrics
    Grafana --> |Query| Jaeger
    Grafana --> |Query| Loki

    API --> |Analytics| Langfuse
    Langfuse --> |Store| ClickHouse
    Langfuse --> |Cache| Redis
    Langfuse --> |Files| MinIO

    classDef core fill:#f9f,stroke:#333,stroke-width:2px,color:#000
    classDef knowledge fill:#ffa,stroke:#333,stroke-width:2px,color:#000
    classDef monitoring fill:#bbf,stroke:#333,stroke-width:2px,color:#000
    classDef analytics fill:#bfb,stroke:#333,stroke-width:2px,color:#000
    classDef tools fill:#fbb,stroke:#333,stroke-width:2px,color:#000

    class UI,API,DB,MQ,Agent core
    class Graphiti,Neo4j knowledge
    class Grafana,VictoriaMetrics,Jaeger,Loki,OTEL monitoring
    class Langfuse,ClickHouse,Redis,MinIO analytics
    class Scraper,PenTest tools

Entity Relationship (click to expand)

erDiagram
    Flow ||--o{ Task : contains
    Task ||--o{ SubTask : contains
    SubTask ||--o{ Action : contains
    Action ||--o{ Artifact : produces
    Action ||--o{ Memory : stores

    Flow {
        string id PK
        string name "Flow name"
        string description "Flow description"
        string status "active/completed/failed"
        json parameters "Flow parameters"
        timestamp created_at
        timestamp updated_at
    }

    Task {
        string id PK
        string flow_id FK
        string name "Task name"
        string description "Task description"
        string status "pending/running/done/failed"
        json result "Task results"
        timestamp created_at
        timestamp updated_at
    }

    SubTask {
        string id PK
        string task_id FK
        string name "Subtask name"
        string description "Subtask description"
        string status "queued/running/completed/failed"
        string agent_type "researcher/developer/executor"
        json context "Agent context"
        timestamp created_at
        timestamp updated_at
    }

    Action {
        string id PK
        string subtask_id FK
        string type "command/search/analyze/etc"
        string status "success/failure"
        json parameters "Action parameters"
        json result "Action results"
        timestamp created_at
    }

    Artifact {
        string id PK
        string action_id FK
        string type "file/report/log"
        string path "Storage path"
        json metadata "Additional info"
        timestamp created_at
    }

    Memory {
        string id PK
        string action_id FK
        string type "observation/conclusion"
        vector embedding "Vector representation"
        text content "Memory content"
        timestamp created_at
    }

Agent Interaction (click to expand)

sequenceDiagram
    participant O as Orchestrator
    participant R as Researcher
    participant D as Developer
    participant E as Executor
    participant VS as Vector Store
    participant KB as Knowledge Base

    Note over O,KB: Flow Initialization
    O->>VS: Query similar tasks
    VS-->>O: Return experiences
    O->>KB: Load relevant knowledge
    KB-->>O: Return context

    Note over O,R: Research Phase
    O->>R: Analyze target
    R->>VS: Search similar cases
    VS-->>R: Return patterns
    R->>KB: Query vulnerabilities
    KB-->>R: Return known issues
    R->>VS: Store findings
    R-->>O: Research results

    Note over O,D: Planning Phase
    O->>D: Plan attack
    D->>VS: Query exploits
    VS-->>D: Return techniques
    D->>KB: Load tools info
    KB-->>D: Return capabilities
    D-->>O: Attack plan

    Note over O,E: Execution Phase
    O->>E: Execute plan
    E->>KB: Load tool guides
    KB-->>E: Return procedures
    E->>VS: Store results
    E-->>O: Execution status

Memory System (click to expand)

graph TB
    subgraph "Long-term Memory"
        VS[(Vector Store<br/>Embeddings DB)]
        KB[Knowledge Base<br/>Domain Expertise]
        Tools[Tools Knowledge<br/>Usage Patterns]
    end

    subgraph "Working Memory"
        Context[Current Context<br/>Task State]
        Goals[Active Goals<br/>Objectives]
        State[System State<br/>Resources]
    end

    subgraph "Episodic Memory"
        Actions[Past Actions<br/>Commands History]
        Results[Action Results<br/>Outcomes]
        Patterns[Success Patterns<br/>Best Practices]
    end

    Context --> |Query| VS
    VS --> |Retrieve| Context

    Goals --> |Consult| KB
    KB --> |Guide| Goals

    State --> |Record| Actions
    Actions --> |Learn| Patterns
    Patterns --> |Store| VS

    Tools --> |Inform| State
    Results --> |Update| Tools

    VS --> |Enhance| KB
    KB --> |Index| VS

    classDef ltm fill:#f9f,stroke:#333,stroke-width:2px,color:#000
    classDef wm fill:#bbf,stroke:#333,stroke-width:2px,color:#000
    classDef em fill:#bfb,stroke:#333,stroke-width:2px,color:#000

    class VS,KB,Tools ltm
    class Context,Goals,State wm
    class Actions,Results,Patterns em

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.

flowchart TD
    A[Input Chain] --> B{Needs Summarization?}
    B -->|No| C[Return Original Chain]
    B -->|Yes| D[Convert to ChainAST]
    D --> E[Apply Section Summarization]
    E --> F[Process Oversized Pairs]
    F --> G[Manage Last Section Size]
    G --> H[Apply QA Summarization]
    H --> I[Rebuild Chain with Summaries]
    I --> J{Is New Chain Smaller?}
    J -->|Yes| K[Return Optimized Chain]
    J -->|No| C

    classDef process fill:#bbf,stroke:#333,stroke-width:2px,color:#000
    classDef decision fill:#bfb,stroke:#333,stroke-width:2px,color:#000
    classDef output fill:#fbb,stroke:#333,stroke-width:2px,color:#000

    class A,D,E,F,G,H,I process
    class B,J decision
    class C,K output

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

Parameter	Environment Variable	Default	Description
Preserve Last	`SUMMARIZER_PRESERVE_LAST`	`true`	Whether to keep all messages in the last section intact
Use QA Pairs	`SUMMARIZER_USE_QA`	`true`	Whether to use QA pair summarization strategy
Summarize Human in QA	`SUMMARIZER_SUM_MSG_HUMAN_IN_QA`	`false`	Whether to summarize human messages in QA pairs
Last Section Size	`SUMMARIZER_LAST_SEC_BYTES`	`51200`	Maximum byte size for last section (50KB)
Max Body Pair Size	`SUMMARIZER_MAX_BP_BYTES`	`16384`	Maximum byte size for a single body pair (16KB)
Max QA Sections	`SUMMARIZER_MAX_QA_SECTIONS`	`10`	Maximum QA pair sections to preserve
Max QA Size	`SUMMARIZER_MAX_QA_BYTES`	`65536`	Maximum byte size for QA pair sections (64KB)
Keep QA Sections	`SUMMARIZER_KEEP_QA_SECTIONS`	`1`	Number of recent QA sections to keep without summarization

Assistant Summarizer Configuration Options

Assistant instances can use customized summarization settings to fine-tune context management behavior:

Parameter	Environment Variable	Default	Description
Preserve Last	`ASSISTANT_SUMMARIZER_PRESERVE_LAST`	`true`	Whether to preserve all messages in the assistant's last section
Last Section Size	`ASSISTANT_SUMMARIZER_LAST_SEC_BYTES`	`76800`	Maximum byte size for assistant's last section (75KB)
Max Body Pair Size	`ASSISTANT_SUMMARIZER_MAX_BP_BYTES`	`16384`	Maximum byte size for a single body pair in assistant context (16KB)
Max QA Sections	`ASSISTANT_SUMMARIZER_MAX_QA_SECTIONS`	`7`	Maximum QA sections to preserve in assistant context
Max QA Size	`ASSISTANT_SUMMARIZER_MAX_QA_BYTES`	`76800`	Maximum byte size for assistant's QA sections (75KB)
Keep QA Sections	`ASSISTANT_SUMMARIZER_KEEP_QA_SECTIONS`	`3`	Number of recent QA sections to preserve without summarization

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

# Default values for global summarizer logic
SUMMARIZER_PRESERVE_LAST=true
SUMMARIZER_USE_QA=true
SUMMARIZER_SUM_MSG_HUMAN_IN_QA=false
SUMMARIZER_LAST_SEC_BYTES=51200
SUMMARIZER_MAX_BP_BYTES=16384
SUMMARIZER_MAX_QA_SECTIONS=10
SUMMARIZER_MAX_QA_BYTES=65536
SUMMARIZER_KEEP_QA_SECTIONS=1

# Default values for assistant summarizer logic
ASSISTANT_SUMMARIZER_PRESERVE_LAST=true
ASSISTANT_SUMMARIZER_LAST_SEC_BYTES=76800
ASSISTANT_SUMMARIZER_MAX_BP_BYTES=16384
ASSISTANT_SUMMARIZER_MAX_QA_SECTIONS=7
ASSISTANT_SUMMARIZER_MAX_QA_BYTES=76800
ASSISTANT_SUMMARIZER_KEEP_QA_SECTIONS=3

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 <original_result> and <mentor_analysis> 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 <task_assignment> 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:

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
Optional 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
- When enabled, automatically captures agent responses and tool executions for a flow-scoped knowledge base
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
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
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
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

For a step-by-step walkthrough that connects installation, configuration, LLM and embedding provider testing, and your first login, see the Installing and Configuring PentAGI guide. The sections below remain the detailed reference for each step.

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

macOS security warning: If macOS flags a downloaded installer, use only the official PentAGI links above, choose the archive that matches your CPU architecture, verify the source before continuing, and follow the installer troubleshooting guide before allowing the app to run.

Quick Installation (Linux amd64):

# Create installation directory
mkdir -p pentagi && cd pentagi

# Download installer
wget -O installer.zip https://pentagi.com/downloads/linux/amd64/installer-latest.zip

# Extract
unzip installer.zip

# Run interactive installer
./installer

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:
```
sudo ./installer
```
Option 2 (Development environments): Grant your user access to the Docker socket by adding them to the docker group:
```
# Add your user to the docker group
sudo usermod -aG docker $USER

# Log out and log back in, or activate the group immediately
newgrp docker

# Verify Docker access (should run without sudo)
docker ps
```
⚠️ 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:

System Checks: Verify Docker, network connectivity, and system requirements
Environment Setup: Create and configure .env file with optimal defaults
Provider Configuration: Set up LLM providers (OpenAI, Anthropic, Gemini, Bedrock, Ollama, DeepSeek, GLM, Kimi, Qwen, MiniMax, Custom)
Search Engines: Configure DuckDuckGo, Google, Tavily, Firecrawl, Traversaal, Perplexity, Sploitus, Searxng, and the optional internal browser-analytics fallback engine
Security Hardening: Generate secure credentials and configure SSL certificates
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, FIRECRAWL_API_*, TRAVERSAAL_API_KEY, PERPLEXITY_*, SEARXNG_*, SPLOITUS_ENABLED, and the optional WEB_SEARCH_INTERNAL_* browser-analytics fallback settings.
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

Giving Agents Docker Without Giving Away the Host

Many pentest workflows need docker inside the agent's sandbox. There are two ways to provide it, and they differ sharply in risk.

Recommended — point sandboxes at a hardened dind daemon over TLS. Set DOCKER_INSIDE=true, leave DOCKER_SOCKET empty, and configure the daemon the sandbox may talk to:

DOCKER_INSIDE=true
DOCKER_SOCKET=                                          # mount no socket
DOCKER_INSIDE_HOST=tcp://10.0.0.5:3376                  # hardened dind endpoint
DOCKER_INSIDE_TLS_VERIFY=1
DOCKER_INSIDE_CERT_PATH=/etc/docker/dind/certs/client   # path on the worker node

PentAGI injects these into every worker container as DOCKER_HOST, DOCKER_TLS_VERIFY and DOCKER_CERT_PATH (the _INSIDE_ segment is dropped) and bind-mounts the certificate directory read-only at the same path, so docker works inside the sandbox with no further setup.

Not recommended — bind-mounting a Docker socket (DOCKER_SOCKET). This has two failure modes:

Boot-order race: a bind-mount source that does not exist yet is created by Docker as a directory. After a worker-node reboot, a worker container can start before dind has recreated its socket — Docker then puts a directory where the socket belongs, and dind cannot start until it is removed by hand.
Blast radius: the race is only reliably avoided when the mounted socket is the host daemon's, since that one always exists first. But that grants an autonomous agent the host Docker API: it can start a privileged container, mount /, and compromise the entire node — PentAGI included.

Use DOCKER_SOCKET only on single-node development setups where the host daemon is already trusted.

See: Worker Node Setup for the full dind hardening and TLS configuration, and Worker Docker Access for the exact resolution algorithm.

Running Several Instances (`TENANT_ID`)

A single PentAGI installation needs none of this — leave TENANT_ID empty (the default) and nothing changes.

Set it when several PentAGI installations share external resources: one PostgreSQL server, one worker node, one Neo4j/Graphiti, one Langfuse. The typical case is a management backend per server with a common worker node and database. Because every instance numbers its flows from 1, they would otherwise collide on container names, database rows, knowledge-graph namespaces and session cookies. TENANT_ID namespaces all of it:

Area	Effect when `TENANT_ID=acme`
PostgreSQL	The instance creates and works inside schema `acme` instead of `public`; extensions stay shared in `DATABASE_EXTENSIONS_SCHEMA` (default `public`, `extensions` on Supabase)
Worker containers	`acme-pentagi-terminal-<flow>` instead of `pentagi-terminal-<flow>`; volumes and hostnames follow, and both carry a `pentagi.tenant` label
Knowledge graph	Graphiti/Neo4j group ids become `acme-flow-<id>`
Auth	Cookie and API token keys are derived from `COOKIE_SIGNING_SALT` plus the tenant, and the session cookie is renamed
Telemetry	Langfuse traces carry the tenant as their `environment` and a `tenant:acme` tag; OTel resources gain `tenant_id`

The value must match ^[a-z][a-z0-9_]{0,31}$ — an invalid one aborts startup rather than being silently normalised.

Some things stay yours to set per instance, because they are host resources rather than names: DATA_DIR (two instances sharing it will overwrite each other's flow data), DOCKER_PORTS_BASE, the published ports, and INSTALLATION_ID. The effective values are printed at startup under Instance identity.

The installer provisions one instance per server. Running several on one server is possible — for example behind a shared nginx — but the stock docker-compose.yml uses fixed container and network names, so it has to be adapted to your own network layout first.

See: Multi-Instance Deployment for validation rules, upgrade notes and the full list of operator responsibilities.

Manual Installation

Create a working directory or clone the repository:

mkdir pentagi && cd pentagi

Copy .env.example to .env or download it:

curl -o .env https://raw.githubusercontent.com/vxcontrol/pentagi/master/.env.example

Touch examples files (example.custom.provider.yml, example.ollama.provider.yml) or download it:

curl -o example.custom.provider.yml https://raw.githubusercontent.com/vxcontrol/pentagi/master/examples/configs/custom-openai.provider.yml
curl -o example.ollama.provider.yml https://raw.githubusercontent.com/vxcontrol/pentagi/master/examples/configs/ollama-llama318b.provider.yml

Fill in the required API keys in .env file.

# Required: At least one of these LLM providers
OPEN_AI_KEY=your_openai_key
ANTHROPIC_API_KEY=your_anthropic_key
GEMINI_API_KEY=your_gemini_key

# Optional: AWS Bedrock provider (enterprise-grade models)
BEDROCK_REGION=us-east-1
# Choose one authentication method:
BEDROCK_DEFAULT_AUTH=true                        # Option 1: Use AWS SDK default credential chain (recommended for EC2/ECS)
# BEDROCK_BEARER_TOKEN=your_bearer_token         # Option 2: Bearer token authentication
# BEDROCK_ACCESS_KEY_ID=your_aws_access_key      # Option 3: Static credentials
# BEDROCK_SECRET_ACCESS_KEY=your_aws_secret_key

# Optional: Ollama provider (local or cloud)
# OLLAMA_SERVER_URL=http://ollama-server:11434   # Local server
# OLLAMA_SERVER_URL=https://ollama.com           # Cloud service
# OLLAMA_SERVER_API_KEY=your_ollama_cloud_key    # Required for cloud, empty for local

# Optional: Chinese AI providers
# DEEPSEEK_API_KEY=your_deepseek_key             # DeepSeek (strong reasoning)
# GLM_API_KEY=your_glm_key                       # GLM (Zhipu AI)
# KIMI_API_KEY=your_kimi_key                     # Kimi (Moonshot AI, ultra-long context)
# QWEN_API_KEY=your_qwen_key                     # Qwen (Alibaba Cloud, multimodal)
# MINIMAX_API_KEY=your_minimax_key               # MiniMax

# Optional: Local LLM provider (zero-cost inference)
OLLAMA_SERVER_URL=http://localhost:11434
OLLAMA_SERVER_MODEL=your_model_name

# Optional: Additional search capabilities
DUCKDUCKGO_ENABLED=true
DUCKDUCKGO_REGION=us-en
DUCKDUCKGO_SAFESEARCH=
DUCKDUCKGO_TIME_RANGE=
SPLOITUS_ENABLED=true
GOOGLE_API_KEY=your_google_key
GOOGLE_CX_KEY=your_google_cx
TAVILY_API_KEY=your_tavily_key
FIRECRAWL_API_KEY=your_firecrawl_key
FIRECRAWL_API_URL=
TRAVERSAAL_API_KEY=your_traversaal_key
PERPLEXITY_API_KEY=your_perplexity_key
PERPLEXITY_MODEL=sonar-pro
PERPLEXITY_CONTEXT_SIZE=medium

# Searxng meta search engine (aggregates results from multiple sources)
SEARXNG_URL=http://your-searxng-instance:8080
SEARXNG_CATEGORIES=general
SEARXNG_LANGUAGE=
SEARXNG_SAFESEARCH=0
SEARXNG_TIME_RANGE=
SEARXNG_TIMEOUT=

# Optional: internal browser-analytics fallback engine for web_search (off by default;
# scrapes and summarizes pages instead of calling a paid analytic API)
WEB_SEARCH_INTERNAL_ENABLED=false
WEB_SEARCH_INTERNAL_MAX_SITES=5
WEB_SEARCH_INTERNAL_MAX_SITE_BYTES=10240

## Graphiti knowledge graph settings
GRAPHITI_ENABLED=false
GRAPHITI_TIMEOUT=30
GRAPHITI_URL=

# Neo4j settings (used by Graphiti stack)
NEO4J_USER=neo4j
NEO4J_DATABASE=neo4j
NEO4J_PASSWORD=devpassword
NEO4J_URI=bolt://neo4j:7687

# Assistant configuration
ASSISTANT_USE_AGENTS=false         # Default value for agent usage when creating new assistants

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. https://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)
TENANT_ID - Leave empty unless this instance shares external resources with another PentAGI installation. When set, it is mixed into the cookie and API token signing keys and renames the session cookie, so a session minted by one instance is rejected by the others even though they share the same COOKIE_SIGNING_SALT. See Running Several Instances

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)

Remove all inline comments from .env file if you want to use it in VSCode or other IDEs as a envFile option:

perl -i -pe 's/\s+#.*$//' .env

Run the PentAGI stack:

curl -O https://raw.githubusercontent.com/vxcontrol/pentagi/master/docker-compose.yml
docker compose up -d

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 https://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

Update .env file with your server's IP address:

# Network binding - allow external connections
PENTAGI_LISTEN_IP=0.0.0.0
PENTAGI_LISTEN_PORT=8443

# Public URL - use your actual server IP or hostname
# Replace 192.168.1.100 with your server's IP address
PUBLIC_URL=https://192.168.1.100:8443

# CORS origins - list all URLs that will access PentAGI
# Include localhost for local access AND your server IP for external access
CORS_ORIGINS=https://localhost:8443,https://192.168.1.100:8443

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

Recreate containers to apply the changes:

docker compose down
docker compose up -d --force-recreate

Verify port binding:

docker ps | grep pentagi

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:

ports:
  - "0.0.0.0:8443:8443"

Then recreate containers again.

Configure firewall to allow incoming connections on port 8443:

# Ubuntu/Debian with UFW
sudo ufw allow 8443/tcp
sudo ufw reload

# CentOS/RHEL with firewalld
sudo firewall-cmd --permanent --add-port=8443/tcp
sudo firewall-cmd --reload

Access PentAGI:

Local access: https://localhost:8443
Network access: https://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):

scraper:
  image: vxcontrol/scraper:latest
  restart: unless-stopped
  container_name: scraper
  hostname: scraper
  expose:
    - 3000/tcp  # Changed from 443 to 3000
  ports:
    - "${SCRAPER_LISTEN_IP:-127.0.0.1}:${SCRAPER_LISTEN_PORT:-9443}:3000"  # Map to port 3000
  environment:
    - MAX_CONCURRENT_SESSIONS=${LOCAL_SCRAPER_MAX_CONCURRENT_SESSIONS:-10}
    - USERNAME=${LOCAL_SCRAPER_USERNAME:-someuser}
    - PASSWORD=${LOCAL_SCRAPER_PASSWORD:-somepass}
  logging:
    options:
      max-size: 50m
      max-file: "7"
  volumes:
    - scraper-ssl:/usr/src/app/ssl
  networks:
    - pentagi-network
  shm_size: 2g

2. Update .env file - change the scraper URL to use HTTP and port 3000:

# Scraper configuration for Podman rootless
SCRAPER_PRIVATE_URL=http://someuser:somepass@scraper:3000/
LOCAL_SCRAPER_USERNAME=someuser
LOCAL_SCRAPER_PASSWORD=somepass

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:

podman-compose down
podman-compose up -d --force-recreate

4. Test scraper connectivity:

# Test from within the pentagi container
podman exec -it pentagi wget -O- "http://someuser:somepass@scraper:3000/html?url=http://example.com"

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:

Variable	Default	Description
`ASSISTANT_USE_AGENTS`	`false`	Controls the default value for agent usage when creating new 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

Open Flows in the sidebar.
Click New Flow.
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.
Select the LLM provider you want to use for this flow.
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:

Assess https://target.example for common web application vulnerabilities. Focus on authentication, file handling, and injection issues. Stay within the provided target only and summarize confirmed findings with reproduction steps.

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 <task_files> XML block (with nested <uploads> and <resources> 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:

Navigate to Settings → API Tokens in the web UI
Click Create Token to generate a new API token
Configure token properties:
- Name (optional): A descriptive name for the token
- Expiration Date: When the token will expire (minimum 1 minute, maximum 3 years)
Click Create and copy the token immediately - it will only be shown once for security reasons
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:

# GraphQL API example
curl -X POST https://your-pentagi-instance:8443/api/v1/graphql \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query": "{ flows { id title status } }"}'

# REST API example
curl https://your-pentagi-instance:8443/api/v1/flows \
  -H "Authorization: Bearer YOUR_API_TOKEN"

API Exploration and Testing

PentAGI provides interactive documentation for exploring and testing API endpoints:

GraphQL Playground

Access the GraphQL Playground at https://your-pentagi-instance:8443/api/v1/graphql/playground

Click the HTTP Headers tab at the bottom

Add your authorization header:

{
  "Authorization": "Bearer YOUR_API_TOKEN"
}

Explore the schema, run queries, and test mutations interactively

Swagger UI

Access the REST API documentation at https://your-pentagi-instance:8443/api/v1/swagger/index.html

Click the Authorize button
Enter your token in the format: Bearer YOUR_API_TOKEN
Click Authorize to apply
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): https://the-guild.dev/graphql/codegen
genqlient (Go): https://github.com/Khan/genqlient
Apollo iOS (Swift): https://www.apollographql.com/docs/ios

REST API Clients

The OpenAPI specification is available at:

Swagger JSON: https://your-pentagi-instance:8443/api/v1/swagger/doc.json
Swagger YAML: Available in backend/pkg/server/docs/swagger.yaml

Generate clients using:

OpenAPI Generator: https://openapi-generator.tech

openapi-generator-cli generate \
  -i https://your-pentagi-instance:8443/api/v1/swagger/doc.json \
  -g python \
  -o ./pentagi-client

Swagger Codegen: https://github.com/swagger-api/swagger-codegen

swagger-codegen generate \
  -i https://your-pentagi-instance:8443/api/v1/swagger/doc.json \
  -l typescript-axios \
  -o ./pentagi-client

swagger-typescript-api (TypeScript): https://github.com/acacode/swagger-typescript-api

npx swagger-typescript-api \
  -p https://your-pentagi-instance:8443/api/v1/swagger/doc.json \
  -o ./src/api \
  -n pentagi-api.ts

API Usage Examples

Creating a New Flow (GraphQL)

mutation CreateFlow {
  createFlow(
    modelProvider: "openai"
    input: "Test the security of https://example.com"
  ) {
    id
    title
    status
    createdAt
  }
}

Listing Flows (REST API)

curl https://your-pentagi-instance:8443/api/v1/flows \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  | jq '.flows[] | {id, title, status}'

Python Client Example

import requests

class PentAGIClient:
    def __init__(self, base_url, api_token):
        self.base_url = base_url
        self.headers = {
            "Authorization": f"Bearer {api_token}",
            "Content-Type": "application/json"
        }
    
    def create_flow(self, provider, target):
        query = """
        mutation CreateFlow($provider: String!, $input: String!) {
          createFlow(modelProvider: $provider, input: $input) {
            id
            title
            status
          }
        }
        """
        response = requests.post(
            f"{self.base_url}/api/v1/graphql",
            json={
                "query": query,
                "variables": {
                    "provider": provider,
                    "input": target
                }
            },
            headers=self.headers
        )
        return response.json()
    
    def get_flows(self):
        response = requests.get(
            f"{self.base_url}/api/v1/flows",
            headers=self.headers
        )
        return response.json()

# Usage
client = PentAGIClient(
    "https://your-pentagi-instance:8443",
    "your_api_token_here"
)

# Create a new flow
flow = client.create_flow("openai", "Scan https://example.com for vulnerabilities")
print(f"Created flow: {flow}")

# List all flows
flows = client.get_flows()
print(f"Total flows: {len(flows['flows'])}")

TypeScript Client Example

import axios, { AxiosInstance } from 'axios';

interface Flow {
  id: string;
  title: string;
  status: string;
  createdAt: string;
}

class PentAGIClient {
  private client: AxiosInstance;

  constructor(baseURL: string, apiToken: string) {
    this.client = axios.create({
      baseURL: `${baseURL}/api/v1`,
      headers: {
        'Authorization': `Bearer ${apiToken}`,
        'Content-Type': 'application/json',
      },
    });
  }

  async createFlow(provider: string, input: string): Promise<Flow> {
    const query = `
      mutation CreateFlow($provider: String!, $input: String!) {
        createFlow(modelProvider: $provider, input: $input) {
          id
          title
          status
          createdAt
        }
      }
    `;

    const response = await this.client.post('/graphql', {
      query,
      variables: { provider, input },
    });

    return response.data.data.createFlow;
  }

  async getFlows(): Promise<Flow[]> {
    const response = await this.client.get('/flows');
    return response.data.flows;
  }

  async getFlow(flowId: string): Promise<Flow> {
    const response = await this.client.get(`/flows/${flowId}`);
    return response.data;
  }
}

// Usage
const client = new PentAGIClient(
  'https://your-pentagi-instance:8443',
  'your_api_token_here'
);

// Create a new flow
const flow = await client.createFlow(
  'openai',
  'Perform penetration test on https://example.com'
);
console.log('Created flow:', flow);

// List all flows
const flows = await client.getFlows();
console.log(`Total flows: ${flows.length}`);

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.

Variable	Default	Description
`LLM_SERVER_URL`		Base URL for the custom LLM API endpoint
`LLM_SERVER_KEY`		API key for the custom LLM provider
`LLM_SERVER_MODEL`		Default model to use (can be overridden in provider config)
`LLM_SERVER_CONFIG_PATH`		Path to the YAML configuration file for agent-specific models
`LLM_SERVER_PROVIDER`		Provider name prefix for model names (e.g., `openrouter`, `deepseek` for LiteLLM proxy)
`LLM_SERVER_LEGACY_REASONING`	`false`	Controls reasoning format in API requests
`LLM_SERVER_PRESERVE_REASONING`	`false`	Preserve reasoning content in multi-turn conversations (required by some providers)

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.

Troubleshooting: tool-call (function-call) parser errors

PentAGI drives its agents with tool calls (also called function calls), so any custom OpenAI-compatible backend configured through LLM_SERVER_* must return valid tool-call JSON in the format the OpenAI Chat Completions API defines. When the backend emits malformed, truncated, or non-conforming tool-call arguments, the agent chain cannot continue.

Self-hosted engines such as llama.cpp, SGLang, and vLLM usually require a specific tool-call parser and a matching chat template to produce correct tool-call output. If the parser is missing or mismatched for the model you are serving, tool-call arguments can come back corrupted. Compatibility therefore depends on the backend's tool-call/function-call behavior and configuration, not on PentAGI alone; not every llama.cpp or SGLang setup produces valid tool calls out of the box.

Typical symptoms:

Backend or proxy errors such as Failed to parse tool call arguments as JSON (often surfaced through a LiteLLM proxy as an HTTP 500), or other unexpected 5xx/4xx responses from the LLM endpoint.
A flow that runs for a few steps and then stops responding to new input in the UI.
Repeated or looping tool calls that never converge.
A flow that fails right at the start with failed to select primary docker image via llm call, because the first action in a flow is an LLM tool call to choose the container image; a backend that cannot return a valid tool call fails at this step too.

How to investigate:

Check both sides of the connection: the PentAGI logs (docker compose logs -f pentagi) and the inference backend or proxy logs (llama.cpp, SGLang, vLLM, or LiteLLM). The backend log usually shows the same parse error when it produced the malformed tool call.
Validate the provider before running a full flow with the ctester utility, which exercises tool-calling agent types directly. See Testing LLM Agents.
Confirm the backend's tool-call parser and chat template are the ones recommended for the model you are serving, and that the model itself supports tool calling.
Update PentAGI to the latest build. Recent versions sanitize malformed function-call arguments returned by the model so a single bad response no longer stalls the whole flow; older builds forwarded the corrupted arguments and could get stuck.

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

Variable	Default	Description
`OLLAMA_SERVER_URL`		URL of your Ollama server or Ollama Cloud
`OLLAMA_SERVER_API_KEY`		API key for Ollama Cloud authentication
`OLLAMA_SERVER_MODEL`		Default model for inference
`OLLAMA_SERVER_CONFIG_PATH`		Path to custom agent configuration file
`OLLAMA_SERVER_PULL_MODELS_TIMEOUT`	`600`	Timeout for model downloads (seconds)
`OLLAMA_SERVER_PULL_MODELS_ENABLED`	`false`	Auto-download models on startup
`OLLAMA_SERVER_LOAD_MODELS_ENABLED`	`false`	Query server for available models

Ollama Cloud Configuration

Ollama Cloud provides managed inference with a generous free tier and scalable paid plans.

Free Tier Setup (Single Model)

# Free tier allows one model at a time
OLLAMA_SERVER_URL=https://ollama.com
OLLAMA_SERVER_API_KEY=your_ollama_cloud_api_key
OLLAMA_SERVER_MODEL=gpt-oss:120b  # Example: OpenAI OSS 120B model

Paid Tier Setup (Multi-Model with Pre-built Configuration)

For paid tiers supporting multiple concurrent models, use the pre-built Ollama Cloud configuration:

# Using pre-built Ollama Cloud configuration (included in Docker image)
OLLAMA_SERVER_URL=https://ollama.com
OLLAMA_SERVER_API_KEY=your_ollama_cloud_api_key
OLLAMA_SERVER_CONFIG_PATH=/opt/pentagi/conf/ollama-cloud.provider.yml

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:

# Using custom provider configuration
OLLAMA_SERVER_URL=https://ollama.com
OLLAMA_SERVER_API_KEY=your_ollama_cloud_api_key
OLLAMA_SERVER_CONFIG_PATH=/opt/pentagi/conf/ollama.provider.yml

# Mount custom configuration from host filesystem (in .env or docker-compose override)
PENTAGI_OLLAMA_SERVER_CONFIG_PATH=/path/on/host/my-ollama-config.yml

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):

primary_agent:
  model: "qwen3-coder-next:cloud"
  temperature: 1.0
  top_p: 0.9
  max_tokens: 32768
  reasoning:
    effort: high

coder:
  model: "qwen3-coder:32b"
  temperature: 1.0
  max_tokens: 20480

Local Ollama Configuration

For self-hosted Ollama instances:

# Basic local Ollama setup
OLLAMA_SERVER_URL=http://localhost:11434
OLLAMA_SERVER_MODEL=llama3.1:8b-instruct-q8_0

# Production setup with auto-pull and model discovery
OLLAMA_SERVER_URL=http://ollama-server:11434
OLLAMA_SERVER_PULL_MODELS_ENABLED=true
OLLAMA_SERVER_PULL_MODELS_TIMEOUT=900
OLLAMA_SERVER_LOAD_MODELS_ENABLED=true

# Using pre-built configurations from Docker image
OLLAMA_SERVER_CONFIG_PATH=/opt/pentagi/conf/ollama-llama318b.provider.yml
# or
OLLAMA_SERVER_CONFIG_PATH=/opt/pentagi/conf/ollama-qwen332b-fp16-tc.provider.yml
# or
OLLAMA_SERVER_CONFIG_PATH=/opt/pentagi/conf/ollama-qwq32b-fp16-tc.provider.yml

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:

FROM qwen3:32b-fp16
PARAMETER num_ctx 110000
PARAMETER temperature 0.3
PARAMETER top_p 0.8
PARAMETER min_p 0.0
PARAMETER top_k 20
PARAMETER repeat_penalty 1.1

Build the custom model:

ollama create qwen3:32b-fp16-tc -f Modelfile_qwen3_32b_fp16_tc

Example: QwQ 32B FP16 with Extended Context

Create a Modelfile named Modelfile_qwq_32b_fp16_tc:

FROM qwq:32b-fp16
PARAMETER num_ctx 110000
PARAMETER temperature 0.2
PARAMETER top_p 0.7
PARAMETER min_p 0.0
PARAMETER top_k 40
PARAMETER repeat_penalty 1.2

Build the custom model:

ollama create qwq:32b-fp16-tc -f Modelfile_qwq_32b_fp16_tc

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

Variable	Default	Description
`OPEN_AI_KEY`		API key for OpenAI services
`OPEN_AI_SERVER_URL`	`https://api.openai.com/v1`	OpenAI API endpoint

Configuration Examples

# Basic OpenAI setup
OPEN_AI_KEY=your_openai_api_key
OPEN_AI_SERVER_URL=https://api.openai.com/v1

# Using with proxy for enhanced security
OPEN_AI_KEY=your_openai_api_key
PROXY_URL=http://your-proxy:8080

Supported Models

PentAGI supports 32 OpenAI models with tool calling, streaming, reasoning modes, and prompt caching. Models marked with * are used in default configuration. Models marked ⚠️ are deprecated by OpenAI and kept only for backward compatibility with agent configs already pinned to those names — avoid them for new assignments.

GPT-5.6 Series - Latest Frontier (Feb 2026 knowledge cutoff, 1.05M context, 128K max output)

Model ID	Thinking	Reasoning Effort	Price (Input/Output/Cache)	Use Case
`gpt-5.6-sol`	✅	low/medium/high/xhigh	$5.00/$30.00/$0.50	Frontier model for complex professional work, most demanding autonomous pentesting, sophisticated exploit chain development, deep multi-stage attack simulation
`gpt-5.6-terra`*	✅	low/medium/high/xhigh	$2.50/$15.00/$0.25	Balances intelligence and cost; multi-phase security assessments, coordinated multi-tool pentesting (generator/refiner/adviser/coder default)
`gpt-5.6-luna`	✅	low/medium/high/xhigh	$1.00/$6.00/$0.10	Optimized for cost-sensitive, high-volume workloads; rapid reconnaissance, bulk vulnerability scanning, real-time monitoring

GPT-5.5 Series - Frontier (Dec 2025 knowledge cutoff, 1.05M context, 128K max output)

Model ID	Thinking	Reasoning Effort	Price (Input/Output/Cache)	Use Case
`gpt-5.5`	✅	none/low/medium/high/xhigh	$5.00/$30.00/$0.50	New class of intelligence for coding and professional work; complex security research, advanced autonomous pentesting
`gpt-5.5-pro`	✅	medium/high/xhigh	$30.00/$180.00/$0.00	Uses more compute for smarter, more precise responses; no cached-input discount; mission-critical security research, zero-day discovery

GPT-5.4 Series - Advanced Reasoning at Scale (1M context)

Model ID	Thinking	Reasoning Effort	Price (Input/Output/Cache)	Use Case
`gpt-5.4`	✅	low/medium/high/xhigh	$2.50/$15.00/$0.25	Best intelligence at scale for agentic, coding, and professional workflows; maximum cognitive depth for pentesting
`gpt-5.4-mini`*	✅	low/medium/high/xhigh	$0.75/$4.50/$0.075	Strongest mini model for coding, computer use, subagents (primary_agent/assistant/reflector/installer/pentester default)
`gpt-5.4-nano`*	✅	low/medium/high/xhigh	$0.20/$1.25/$0.02	Cheapest GPT-5.4-class model for simple, high-volume tasks (simple/simple_json/searcher/enricher default)

GPT-5.2 Series - Previous Flagship Agentic

Model ID	Thinking	Reasoning Effort	Price (Input/Output/Cache)	Use Case
`gpt-5.2`	✅	low/medium/high/xhigh	$1.75/$14.00/$0.175	Superseded by 5.4/5.6; autonomous security research, complex exploit chain development
`gpt-5.2-pro`	✅	medium/high/xhigh	$21.00/$168.00/$0.00	Superior agentic coding and long-context performance, mission-critical security research, zero-day discovery

GPT-5/5.1 Series - Advanced Agentic Models

Model ID	Thinking	Price (Input/Output/Cache)	Use Case
`gpt-5`	✅	$1.25/$10.00/$0.125	Autonomous security research, exploit chain development, coordinating multi-tool pentesting workflows
`gpt-5.1`	✅	$1.25/$10.00/$0.125	Bridges GPT-5 and GPT-5.2 with faster responses; balanced penetration testing with strong tool coordination
`gpt-5-pro`	✅ (high)	$15.00/$120.00/$0.00	Reduced hallucinations, exceptional accuracy, critical security operations
`gpt-5-mini`	✅	$0.25/$2.00/$0.025	Automated vulnerability analysis, exploit generation with strong function calling
`gpt-5-nano`	✅	$0.05/$0.40/$0.005	High-throughput security scanning, reconnaissance, real-time monitoring

GPT-4.1 Series - Enhanced Intelligence (Non-Reasoning)

Model ID	Thinking	Price (Input/Output/Cache)	Use Case
`gpt-4.1`	❌	$2.00/$8.00/$0.50	Superior function calling, complex threat analysis, sophisticated exploit development
`gpt-4.1-mini`	❌	$0.40/$1.60/$0.10	Routine security assessments, automated code analysis (no longer used in default configuration)

GPT-4o Series - Multimodal (Non-Reasoning)

Model ID	Thinking	Price (Input/Output/Cache)	Use Case
`gpt-4o-mini`	❌	$0.15/$0.60/$0.075	Compact multimodal with strong function calling, high-frequency scanning, cost-effective bulk operations

o-Series - Advanced Reasoning Models (Current)

Model ID	Thinking	Price (Input/Output/Cache)	Use Case
`o3`	✅	$2.00/$8.00/$0.50	Succeeded by GPT-5; multi-stage attack chains, deep vulnerability analysis
`o3-pro`	✅	$20.00/$80.00/$0.00	More compute for better responses; zero-day research, critical security investigations

Deprecated Models - Kept for Backward Compatibility ⚠️

These models were marked deprecated by OpenAI. PentAGI keeps them defined only so that pre-existing agent configs pinned to these names keep working; do not assign them to new agents.

Model ID	Thinking	Price (Input/Output/Cache)	Notes
`gpt-5.2-codex`	✅	$1.75/$14.00/$0.175	Superseded code-specialized model; use `gpt-5.6-terra`/`gpt-5.4-mini` instead
`gpt-5.1-codex-max`	✅	$1.25/$10.00/$0.125	Superseded; enhanced reasoning for coding workflows
`gpt-5.1-codex`	✅	$1.25/$10.00/$0.125	Superseded standard code-optimized model
`gpt-5-codex`	✅	$1.25/$10.00/$0.125	Superseded foundational code-specialized model
`gpt-5.1-codex-mini`	✅	$0.25/$2.00/$0.025	Superseded compact code model
`codex-mini-latest`	✅	$1.50/$6.00/$0.375	Superseded compact code model
`gpt-4o`	❌	$2.50/$10.00/$1.25	Superseded by GPT-5.x/5.6 series multimodal flagship
`gpt-4.1-nano`	❌	$0.10/$0.40/$0.025	Superseded ultra-fast lightweight model
`o3-mini`	✅	$1.10/$4.40/$0.55	Superseded compact reasoning model
`o4-mini`	✅	$1.10/$4.40/$0.275	Succeeded by `gpt-5-mini`
`o1`	✅	$15.00/$60.00/$7.50	Superseded premier reasoning model
`o1-pro`	✅	$150.00/$600.00/$0.00	Superseded, highest cost point of the o-series

Prices: Per 1M tokens. Reasoning models include thinking tokens in output pricing.

Warning

GPT-5/5.1/5.2 Models - Trusted Access Required

The original GPT-5, GPT-5.1, and GPT-5.2 models (gpt-5, gpt-5.1, gpt-5.2, gpt-5-pro, gpt-5.2-pro, and all deprecated Codex variants) work unstably with PentAGI and may trigger OpenAI's cybersecurity safety mechanisms without verified access. This does not affect the newer GPT-5.4/5.5/5.6 series used in PentAGI's default configuration below.

To use these models reliably:

Individual users: Verify your identity at chatgpt.com/cyber
Enterprise teams: Request trusted access through your OpenAI representative
Security researchers: Apply for the Cybersecurity Grant Program (includes $10M in API credits)

Recommended alternatives without verification:

Use PentAGI's defaults — gpt-5.4-mini/gpt-5.4-nano/gpt-5.6-terra — which work out of the box
Use o3/o3-pro for reasoning tasks
Use gpt-4.1 series for general intelligence and function calling without reasoning

Reasoning Configuration:

Reasoning forced off by default: every default agent assigned gpt-5.4-mini or gpt-5.6-terra (primary_agent, assistant, generator, refiner, adviser, reflector, coder, installer, pentester) sets reasoning: {mode: off} — this genuinely disables reasoning, it is not simply "low effort". PentAGI calls OpenAI exclusively through /v1/chat/completions (never /v1/responses), and this endpoint rejects requests that combine function tools with these models' default-on thinking; forcing thinking off is required for tool calls to work reliably (see the investigation notes in backend/pkg/providers/openai/config.yml).
No override needed for gpt-5.4-nano: used for simple, simple_json, searcher, and enricher, this tier does not default to thinking on, so tools attach without conflict and no reasoning override is required.
Manual tuning available: outside the default assignments, GPT-5.6/5.5/5.4/5.2 series models expose explicit reasoning effort levels (low/medium/high/xhigh, plus none on GPT-5.5) for custom agent configs that need variable reasoning depth with tool calling disabled or via /v1/responses.

Key Features:

Extended Reasoning: GPT-5.4/5.5/5.6 and o-series models with chain-of-thought for complex security analysis
Agentic Intelligence: GPT-5.4/5.5/5.6 series with enhanced tool integration, million-token context windows, and autonomous capabilities
Prompt Caching: Cost reduction on repeated context (10-50% of input price)
Code Specialization: Legacy Codex models remain available (deprecated) for vulnerability discovery and exploit development in pinned configs
Multimodal Support: gpt-4o-mini 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

Variable	Default	Description
`ANTHROPIC_API_KEY`		API key for Anthropic services
`ANTHROPIC_SERVER_URL`	`https://api.anthropic.com/v1`	Anthropic API endpoint

Configuration Examples

# Basic Anthropic setup
ANTHROPIC_API_KEY=your_anthropic_api_key
ANTHROPIC_SERVER_URL=https://api.anthropic.com/v1

# Using with proxy for secure environments
ANTHROPIC_API_KEY=your_anthropic_api_key
PROXY_URL=http://your-proxy:8080

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 9 Claude models with tool calling, streaming, extended thinking, adaptive thinking, and prompt caching. Models marked with * are used in default configuration.

Claude 5 Series - Newest Models (2026)

Model ID	Thinking	Release Date	Price (Input/Output/Cache R/W)	Use Case
`claude-sonnet-5`*	✅	Jul 2026	$3.00/$15.00/$0.30/$3.75	Best combination of speed and intelligence for coding, agents, and professional work at scale. Adaptive thinking only (manual budget thinking rejected); sampling parameters not supported. Default model for primary agent, assistant, coder, adviser, installer, pentester
`claude-fable-5`	✅	Jun 2026	$10.00/$50.00/$1.00/$12.50	Anthropic's most capable widely released model for long-running agents and the most demanding reasoning workloads. Adaptive thinking always on (budget thinking and an explicit disable are rejected); sampling parameters not supported

Claude 4 Series

Model ID	Thinking	Release Date	Price (Input/Output/Cache R/W)	Use Case
`claude-opus-4-8`*	✅	May 2026	$5.00/$25.00/$0.50/$6.25	Flagship for coding, agents, and deep reasoning in enterprise security workflows. Adaptive thinking only — budget thinking and sampling params (temperature/top_p/top_k) are rejected. Default model for generator and refiner; most demanding exploit development and multi-stage attack simulation
`claude-opus-4-7`	✅	Apr 2026	$5.00/$25.00/$0.50/$6.25	Advanced software engineering and long-running agentic security analysis. Adaptive thinking only (manual budget thinking rejected)
`claude-sonnet-4-6`	✅	Feb 2026	$3.00/$15.00/$0.30/$3.75	Best speed/intelligence balance with adaptive thinking. Multi-phase security assessments, intelligent vulnerability analysis, real-time threat hunting
`claude-opus-4-6`	✅	Feb 2026	$5.00/$25.00/$0.50/$6.25	Most intelligent model for autonomous agents and coding. Extended + adaptive thinking for complex exploit development, multi-stage attack simulation
`claude-haiku-4-5`*	❌	Oct 2025	$1.00/$5.00/$0.10/$1.25	Fast and efficient model with exceptional function calling and low latency, no thinking support. Default model for simple, simple_json, reflector, searcher, enricher; high-frequency scanning, real-time monitoring, bulk automated testing

Legacy Models - Still Supported

Model ID	Thinking	Release Date	Price (Input/Output/Cache R/W)	Use Case
`claude-sonnet-4-5`	✅	Sep 2025	$3.00/$15.00/$0.30/$3.75	State-of-the-art reasoning (superseded by sonnet-4-6/sonnet-5). Sophisticated penetration testing, advanced threat analysis
`claude-opus-4-5`	✅	Nov 2025	$5.00/$25.00/$0.50/$6.25	Ultimate reasoning (superseded by opus-4-6/4-7/4-8). Critical security research, zero-day discovery, red team operations

Prices: Per 1M tokens. Cache pricing includes both Read and Write costs.

Extended Thinking Configuration (default agent config, see backend/pkg/providers/anthropic/config.yml):

Generator / Refiner (claude-opus-4-8): adaptive reasoning at xhigh/high effort for maximum reasoning depth on complex exploit development
Primary agent, assistant, coder, adviser, installer, pentester (claude-sonnet-5): adaptive reasoning (adviser at xhigh effort) for balanced code analysis and vulnerability research
Reflector, searcher (claude-haiku-4-5): fixed reasoning budget of 1024 tokens for focused reasoning on specific tasks
Simple, simple_json, enricher (claude-haiku-4-5): no thinking, optimized for speed

Key Features:

Extended Thinking: All Claude 4.5+ models support 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; Claude Opus 4.7/4.8 and the Claude 5 series (Sonnet/Fable) are adaptive-thinking-only (manual budget thinking and sampling parameters are rejected with HTTP 400)
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

Variable	Default	Description
`GEMINI_API_KEY`		API key for Google AI services
`GEMINI_SERVER_URL`	`https://generativelanguage.googleapis.com`	Google AI API endpoint

Configuration Examples

# Basic Gemini setup
GEMINI_API_KEY=your_gemini_api_key
GEMINI_SERVER_URL=https://generativelanguage.googleapis.com

# Using with proxy
GEMINI_API_KEY=your_gemini_api_key
PROXY_URL=http://your-proxy:8080

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)

Model ID	Thinking	Context	Price (Input/Output/Cache)	Use Case
`gemini-3.5-flash`*	✅	1M	$1.50/$9.00/$0.15	Most intelligent Flash model with sustained frontier performance on agentic and coding tasks, superior search and grounding

Gemini 3.1 Series - Stable Flash-Lite + Pro Preview (Feb-May 2026)

Model ID	Thinking	Context	Price (Input/Output/Cache)	Use Case
`gemini-3.1-pro-preview`*	✅	1M	$2.00/$12.00/$0.20	Latest flagship with refined thinking, improved token efficiency, optimized for software engineering and agentic workflows
`gemini-3.1-pro-preview-customtools`	✅	1M	$2.00/$12.00/$0.20	Custom tools endpoint optimized for bash and custom tools (view_file, search_code) prioritization
`gemini-3.1-flash-lite`*	✅	1M	$0.25/$1.50/$0.025	Most cost-efficient stable multimodal model, frontier-class performance for high-volume agentic tasks and low-latency applications

Gemini 2.5 Series - Advanced Thinking Models (active until October 16, 2026)

Model ID	Thinking	Context	Price (Input/Output/Cache)	Use Case
`gemini-2.5-pro`	✅	1M	$1.25/$10.00/$0.125	State-of-the-art for complex coding and reasoning, sophisticated threat modeling
`gemini-2.5-flash`	✅	1M	$0.30/$2.50/$0.03	First hybrid reasoning model with thinking budgets, best price-performance for large-scale assessments
`gemini-2.5-flash-lite`	✅	1M	$0.10/$0.40/$0.01	Smallest and most cost-effective for at-scale usage, high-throughput scanning

Gemma 4 Open-Source Models (Apache 2.0, Free Tier)

Model ID	Thinking	Context	Price (Input/Output/Cache)	Use Case
`gemma-4-31b-it`	✅	256K	Free/Free/Free	Largest open-source Gemma 4 dense model (~31B params), multimodal text+image, 140+ languages, on-premises security operations
`gemma-4-26b-a4b-it`	✅	256K	Free/Free/Free	MoE architecture (~26B total / ~3.8B active params), highly efficient inference on consumer GPUs for on-premises high-throughput scanning

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

Variable	Default	Description
`BEDROCK_REGION`	`us-east-1`	AWS region for Bedrock service
`BEDROCK_DEFAULT_AUTH`	`false`	Use AWS SDK default credential chain (environment, EC2 role, ~/.aws/credentials) - highest priority
`BEDROCK_BEARER_TOKEN`		Bearer token authentication - priority over static credentials
`BEDROCK_ACCESS_KEY_ID`		AWS access key ID for static credentials
`BEDROCK_SECRET_ACCESS_KEY`		AWS secret access key for static credentials
`BEDROCK_SESSION_TOKEN`		AWS session token for temporary credentials (optional, used with static credentials)
`BEDROCK_SERVER_URL`		Custom Bedrock endpoint (VPC endpoints, local testing)
`BEDROCK_CONFIG_PATH`		Path to a custom YAML provider config file (overrides the built-in default config for model/pricing definitions)

Authentication Priority: BEDROCK_DEFAULT_AUTH → BEDROCK_BEARER_TOKEN → BEDROCK_ACCESS_KEY_ID+BEDROCK_SECRET_ACCESS_KEY

Configuration Examples

# Recommended: Default AWS SDK authentication (EC2/ECS/Lambda roles)
BEDROCK_REGION=us-east-1
BEDROCK_DEFAULT_AUTH=true

# Bearer token authentication (AWS STS, custom auth)
BEDROCK_REGION=us-east-1
BEDROCK_BEARER_TOKEN=your_bearer_token

# Static credentials (development, testing)
BEDROCK_REGION=us-east-1
BEDROCK_ACCESS_KEY_ID=your_aws_access_key
BEDROCK_SECRET_ACCESS_KEY=your_aws_secret_key

# With proxy and custom endpoint
BEDROCK_REGION=us-east-1
BEDROCK_DEFAULT_AUTH=true
BEDROCK_SERVER_URL=https://bedrock-runtime.us-east-1.vpce-xxx.amazonaws.com
PROXY_URL=http://your-proxy:8080

Custom Provider Config and Models (advanced)

By default the Bedrock provider uses a per-agent config and model catalog compiled into the binary. One optional path overrides them without rebuilding:

BEDROCK_CONFIG_PATH — a YAML file (same shape as the other provider configs) that replaces the built-in per-agent model/price assignments. See examples/configs/bedrock-glm-flash.provider.yml.

This is useful to expose a Bedrock model newer than the compiled-in catalog — for example Z.AI's zai.glm-4.7-flash. Use the exact Model ID from the model's AWS Bedrock detail page; add a us./eu./apac. inference-profile prefix only when that page marks the model as requiring cross-region inference (zai.glm-4.7-flash is In-Region, so it is used as-is, with no prefix).

With Docker Compose, set the host-side mount source and the in-container path together:

# host file mounted into the container at /opt/pentagi/conf/bedrock.provider.yml
PENTAGI_BEDROCK_CONFIG_PATH=./examples/configs/bedrock-glm-flash.provider.yml
# tell the backend to read the mounted file
BEDROCK_CONFIG_PATH=/opt/pentagi/conf/bedrock.provider.yml

Supported Models

PentAGI supports 24 AWS Bedrock models with tool calling, streaming, and multimodal capabilities. Models marked with * are used in default configuration.

Model ID	Provider	Thinking	Multimodal	Price (Input/Output)	Use Case
`us.amazon.nova-2-lite-v1:0`	Amazon Nova	❌	✅	$0.33/$2.75	Adaptive reasoning, efficient thinking
`us.amazon.nova-premier-v1:0`	Amazon Nova	❌	✅	$2.50/$12.50	Complex reasoning, advanced analysis
`us.amazon.nova-pro-v1:0`	Amazon Nova	❌	✅	$0.80/$3.20	Balanced accuracy, speed, cost
`us.amazon.nova-lite-v1:0`	Amazon Nova	❌	✅	$0.06/$0.24	Fast processing, high-volume operations
`us.amazon.nova-micro-v1:0`	Amazon Nova	❌	❌	$0.035/$0.14	Ultra-low latency, real-time monitoring
`us.anthropic.claude-opus-4-8`	Anthropic	✅	✅	$5.00/$25.00	Flagship coding/agents/deep reasoning; adaptive thinking only (sampling params rejected)
`us.anthropic.claude-opus-4-7`	Anthropic	✅	✅	$5.00/$25.00	Advanced engineering, long-running agents; adaptive thinking only
`us.anthropic.claude-opus-4-6-v1`*	Anthropic	✅	✅	$5.00/$25.00	World-class coding, enterprise agents
`us.anthropic.claude-sonnet-4-6`	Anthropic	✅	✅	$3.00/$15.00	Frontier intelligence, enterprise scale
`us.anthropic.claude-opus-4-5-20251101-v1:0`	Anthropic	✅	✅	$5.00/$25.00	Multi-day software development
`us.anthropic.claude-haiku-4-5-20251001-v1:0`*	Anthropic	✅	✅	$1.00/$5.00	Near-frontier performance, high speed
`us.anthropic.claude-sonnet-4-5-20250929-v1:0`*	Anthropic	✅	✅	$3.00/$15.00	Real-world agents, coding excellence
`us.anthropic.claude-sonnet-4-20250514-v1:0`	Anthropic	✅	✅	$3.00/$15.00	Balanced performance, production-ready
`us.anthropic.claude-3-5-haiku-20241022-v1:0`	Anthropic	❌	❌	$0.80/$4.00	Fastest model, cost-effective scanning
`cohere.command-r-plus-v1:0`	Cohere	❌	❌	$3.00/$15.00	Large-scale operations, superior RAG
`deepseek.v3.2`	DeepSeek	❌	❌	$0.58/$1.68	Long-context reasoning, efficiency
`openai.gpt-oss-120b-1:0`*	OpenAI (OSS)	✅	❌	$0.15/$0.60	Strong reasoning, scientific analysis
`openai.gpt-oss-20b-1:0`	OpenAI (OSS)	✅	❌	$0.07/$0.30	Efficient coding, software development
`qwen.qwen3-next-80b-a3b`	Qwen	❌	❌	$0.15/$1.20	Ultra-long context, flagship reasoning
`qwen.qwen3-32b-v1:0`	Qwen	❌	❌	$0.15/$0.60	Balanced reasoning, research use cases
`qwen.qwen3-coder-30b-a3b-v1:0`	Qwen	❌	❌	$0.15/$0.60	Vibe coding, natural-language first
`qwen.qwen3-coder-next`	Qwen	❌	❌	$0.45/$1.80	Tool use, function calling optimized
`mistral.mistral-large-3-675b-instruct`	Mistral	❌	✅	$4.00/$12.00	Advanced multimodal, long-context
`moonshotai.kimi-k2.5`	Moonshot	❌	✅	$0.60/$3.00	Vision, language, code in one model

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:

Model Family	Reason for Incompatibility
GLM (Z.AI)	Tool calling format incompatible with Converse API (expects string instead of JSON)
AI21 Jamba	Severe rate limits (1-2 req/min) prevent reliable testing and production use
Meta Llama 3.3/3.1	Unstable tool call result processing, causes unexpected failures in multi-turn workflows
Mistral Magistral	Tool calling not supported by the model
Moonshot K2-Thinking	Unstable streaming behavior with tool calls, unreliable in production
Qwen3-VL	Unstable streaming with tool calling, multimodal + tools combination fails intermittently

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:

Request quota increases through AWS Service Quotas console for models you plan to use
Use Amazon Nova models - higher default quotas and excellent performance
Enable provisioned throughput for consistent high-volume testing
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

Variable	Default Value	Description
`DEEPSEEK_API_KEY`		DeepSeek API key for authentication
`DEEPSEEK_SERVER_URL`	`https://api.deepseek.com`	DeepSeek API endpoint URL
`DEEPSEEK_PROVIDER`		Provider prefix for LiteLLM integration (optional)

Configuration Examples

# Direct API usage
DEEPSEEK_API_KEY=your_deepseek_api_key
DEEPSEEK_SERVER_URL=https://api.deepseek.com

# With LiteLLM proxy
DEEPSEEK_API_KEY=your_litellm_key
DEEPSEEK_SERVER_URL=http://litellm-proxy:4000
DEEPSEEK_PROVIDER=deepseek  # Adds prefix to model names (deepseek/deepseek-v4-flash) for LiteLLM

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.

Model ID	Thinking	Max Output	Context	Price (Input/Output/Cache)	Use Case
`deepseek-v4-flash`*	✅ hybrid	384K	1M	$0.14/$0.28/$0.0028	Utility agents, general dialogue, fast tool calling
`deepseek-v4-pro`*	✅ hybrid	384K	1M	$1.74/$3.48/$0.0145	Advanced reasoning, complex logic, security analysis

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.

Agent Role	Default Model	Thinking	Reasoning Effort	Max Output	Temperature	Top P
Generator / Refiner	`deepseek-v4-pro`	Enabled	High	32768	(auto)	(auto)
Coder	`deepseek-v4-pro`	Enabled	High	20480	(auto)	(auto)
Primary Agent / Assistant / Pentester	`deepseek-v4-pro`	Enabled	High	16384	(auto)	(auto)
Adviser (mentor/planner)	`deepseek-v4-pro`	Enabled	High	8192	(auto)	(auto)
Installer	`deepseek-v4-flash`	Enabled	High	12288	(auto)	(auto)
Reflector / Searcher / Enricher	`deepseek-v4-flash`	Disabled	—	4096	0.5	0.9
Simple / Simple JSON	`deepseek-v4-flash`	Disabled	—	2048	0.3	0.9

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

Variable	Default Value	Description
`GLM_API_KEY`		GLM API key for authentication
`GLM_SERVER_URL`	`https://api.z.ai/api/paas/v4`	GLM API endpoint URL (international)
`GLM_PROVIDER`		Provider prefix for LiteLLM integration (optional)

Configuration Examples

# Direct API usage (international endpoint)
GLM_API_KEY=your_glm_api_key
GLM_SERVER_URL=https://api.z.ai/api/paas/v4

# Alternative endpoints
GLM_SERVER_URL=https://open.bigmodel.cn/api/paas/v4  # China
GLM_SERVER_URL=https://api.z.ai/api/coding/paas/v4   # Coding-specific

# With LiteLLM proxy
GLM_API_KEY=your_litellm_key
GLM_SERVER_URL=http://litellm-proxy:4000
GLM_PROVIDER=zai  # Adds prefix to model names (zai/glm-4) for LiteLLM

Supported Models

PentAGI supports 14 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)

Model ID	Thinking	Context	Max Output	Price (Input/Output/Cache)	Use Case
`glm-5.2`*	✅ Hybrid	200K	128K	$1.40/$4.40/$0.26	Newest flagship, improves on GLM-5.1. Supports explicit `reasoning_effort` (high/max) (generator/refiner/adviser/coder/pentester default)
`glm-5.1`	✅ Hybrid	200K	128K	$1.40/$4.40/$0.26	Long-horizon tasks: 8h sustained autonomous execution, Claude Opus 4.6-aligned coding
`glm-5`	✅ Hybrid	200K	128K	$1.00/$3.20/$0.20	Foundation for Agentic Engineering, MoE 744B/40B active, Claude Opus 4.5-level coding
`glm-5-turbo`*	✅ Hybrid	200K	128K	$1.20/$4.00/$0.24	OpenClaw-native: optimized for tool invocation, persistent tasks, long-chain execution (primary_agent/assistant default)

GLM-4.7 Series - Premium with Interleaved Thinking

Model ID	Thinking	Context	Max Output	Price (Input/Output/Cache)	Use Case
`glm-4.7`	✅ Hybrid	200K	128K	$0.60/$2.20/$0.11	Enhanced programming, stable multi-step reasoning
`glm-4.7-flashx`	✅ Hybrid	200K	128K	$0.07/$0.40/$0.01	Ultra-cheap with priority GPU, but lower RPM limits (avoid for high-frequency use)
`glm-4.7-flash`	✅ Hybrid	200K	128K	Free/Free/Free	Free ~30B SOTA model, 1 concurrent request

GLM-4.6 Series - Balanced with Auto-Thinking

Model ID	Thinking	Context	Max Output	Price (Input/Output/Cache)	Use Case
`glm-4.6`	✅ Auto	200K	128K	$0.60/$2.20/$0.11	Balanced, streaming tool calls, token-efficient

GLM-4.5 Series - Unified Reasoning/Coding/Agents

Model ID	Thinking	Context	Max Output	Price (Input/Output/Cache)	Use Case
`glm-4.5`	✅ Auto	128K	96K	$0.60/$2.20/$0.11	Unified, MoE 355B/32B active
`glm-4.5-x`	✅ Auto	128K	96K	$2.20/$8.90/$0.45	Ultra-fast premium, lowest latency
`glm-4.5-air`*	✅ Auto	128K	96K	$0.20/$1.10/$0.03	Cost-effective MoE 106B/12B (simple/simple_json/reflector/searcher/enricher/installer default)
`glm-4.5-airx`	✅ Auto	128K	96K	$1.10/$4.50/$0.22	Accelerated Air with priority GPU
`glm-4.5-flash`	✅ Auto	128K	96K	Free/Free/Free	Free with reasoning/coding/agents support

GLM-4 Legacy - Dense Architecture

Model ID	Thinking	Context	Max Output	Price (Input/Output)	Use Case
`glm-4-32b-0414-128k`	❌	128K	16K	$0.10/$0.10	Ultra-budget dense 32B, parsing without reasoning

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.2 (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.

Agent Role	Default Model	Thinking	Temperature	Top P	Max Output
Generator / Refiner	`glm-5.2`	Enabled	1.0	0.95	32768
Coder	`glm-5.2`	Enabled	1.0	0.95	20480
Adviser / Pentester	`glm-5.2`	Enabled	1.0	0.95	16384
Primary Agent / Assistant	`glm-5-turbo`	Enabled	1.0	0.95	16384
Installer	`glm-4.5-air`	Enabled	1.0	0.95	16384
Simple / Reflector	`glm-4.5-air`	Disabled	0.6	0.9	8192
Searcher / Enricher / Simple JSON	`glm-4.5-air`	Disabled	0.6	0.9	4096

Generator, refiner, and adviser additionally set reasoning.effort: max, which layers llms.WithReasoning(ReasoningMax, 0) on top of extra_body.thinking.type=enabled — this reasoning_effort parameter is only supported by glm-5.2.

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.2/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
Reasoning Effort (GLM-5.2 only): supports an explicit reasoning_effort parameter (high/max) on top of hybrid thinking, for finer control over reasoning depth than the other GLM-5.x models
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

Variable	Default Value	Description
`KIMI_API_KEY`		Kimi API key for authentication
`KIMI_SERVER_URL`	`https://api.moonshot.ai/v1`	Kimi API endpoint URL (international)
`KIMI_PROVIDER`		Provider prefix for LiteLLM integration (optional)

Configuration Examples

# Direct API usage (international endpoint)
KIMI_API_KEY=your_kimi_api_key
KIMI_SERVER_URL=https://api.moonshot.ai/v1

# Alternative endpoint
KIMI_SERVER_URL=https://api.moonshot.cn/v1  # China

# With LiteLLM proxy
KIMI_API_KEY=your_litellm_key
KIMI_SERVER_URL=http://litellm-proxy:4000
KIMI_PROVIDER=moonshot  # Adds prefix to model names (moonshot/kimi-k2.5) for LiteLLM

Supported Models

PentAGI supports 11 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 K3 - Flagship (Always Reasoning)

Model ID	Thinking	Multimodal	Context	Price (Input Miss / Output / Cache Hit)	Use Case
`kimi-k3`*	✅ always	❌	1M	$3.00 / $15.00 / $0.30	Flagship for long-horizon coding and end-to-end knowledge work. Always reasons — no `thinking` toggle, depth set via top-level `reasoning_effort` (currently `max` only) (generator/refiner/adviser default)

Kimi K2.7 Code Series - Coding-Focused

Model ID	Thinking	Multimodal	Context	Price (Input Miss / Output / Cache Hit)	Use Case
`kimi-k2.7-code`*	✅ hybrid	✅	256K	$0.95 / $4.00 / $0.19	Coding-focused, higher success rates on long-context programming tasks (coder/pentester default)
`kimi-k2.7-code-highspeed`*	✅ hybrid	✅	256K	$1.90 / $8.00 / $0.38	Same model as `kimi-k2.7-code` with higher output throughput (~180-260 tokens/s) (primary_agent/assistant default)

Kimi K2.x Series - Multimodal Flagship

Model ID	Thinking	Multimodal	Context	Price (Input Miss / Output / Cache Hit)	Use Case
`kimi-k2.6`	✅ hybrid	✅	256K	$0.95 / $4.00 / $0.16	Latest multimodal flagship: native architecture, stronger code, improved instruction compliance (not used by default config)
`kimi-k2.5`*	✅ hybrid	✅	256K	$0.60 / $3.00 / $0.10	Previous-gen: 36% cheaper input than K2.6 (simple/simple_json/reflector/searcher/enricher/installer default)

Moonshot V1 Series - Generation Models (Flexible Parameters)

Model ID	Thinking	Multimodal	Context	Price (Input / Output)	Use Case
`moonshot-v1-8k`	❌	❌	8K	$0.20 / $2.00	Short text generation, ultra-cheap
`moonshot-v1-32k`	❌	❌	32K	$1.00 / $3.00	Long text generation
`moonshot-v1-128k`	❌	❌	128K	$2.00 / $5.00	Very long context

Moonshot V1 Vision Series - Image Understanding

Model ID	Thinking	Multimodal	Context	Price (Input / Output)	Use Case
`moonshot-v1-8k-vision-preview`	❌	✅	8K	$0.20 / $2.00	Vision + short context
`moonshot-v1-32k-vision-preview`	❌	✅	32K	$1.00 / $3.00	Vision + medium context
`moonshot-v1-128k-vision-preview`	❌	✅	128K	$2.00 / $5.00	Vision + long context

Prices: Per 1M tokens. Cache pricing applies to prompt tokens served from automatic context cache (only Kimi K3/K2.7/K2.x models support cache).

CRITICAL — Kimi parameter constraints per model family: API returns invalid_request_error for any deviation:

kimi-k3: always reasons, no thinking param at all; reasoning depth is set via the top-level reasoning_effort field (low/high/max, default max) — PentAGI pins it to max for all agents using this model. temperature MUST be 1.0, top_p MUST be 0.95, n MUST be 1, presence_penalty/frequency_penalty MUST be 0. Do not switch effort per call — it invalidates the prefix cache.

kimi-k2.7-code / kimi-k2.7-code-highspeed: thinking may be omitted; if set explicitly, only {"type":"enabled","keep":"all"} is accepted (type: disabled is rejected). reasoning_effort is not supported. temperature MUST be 1.0, top_p MUST be 0.95, n MUST be 1; tool_choice: required is not supported (use auto).

kimi-k2.6: thinking mode needs temperature=1.0, top_p=0.95, n=1, thinking.keep="all"; non-thinking mode needs temperature=0.6, top_p=0.95, n=1.

kimi-k2.5: thinking mode needs temperature=1.0, top_p=0.95, n=1 (no keep support); non-thinking mode needs temperature=0.6, top_p=0.95, n=1.

All Kimi models: presence_penalty=0, frequency_penalty=0, tool_choice in {auto, none}.

Moonshot V1 models use standard OpenAI-compatible parameters with no such constraints.

Default Agent Configuration:

Strategy: kimi-k2.5 for utility/orchestration, kimi-k2.7-code-highspeed for the primary/assistant loop, kimi-k3 (always-thinking flagship) for critical reasoning (generator/refiner/adviser), kimi-k2.7-code for coder/pentester. kimi-k2.6 is not used in the default configuration. All kimi-k2.x/k2.7 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 (where supported) to preserve historical reasoning_content in multi-turn tool call chains (without it Moonshot returns "thinking is enabled but reasoning_content is missing").

Agent Role	Default Model	Thinking	Temperature	Top P	Max Output
Generator / Refiner	`kimi-k3`	Always (effort=max)	1.0	0.95	32768
Adviser (mentor/planner)	`kimi-k3`	Always (effort=max)	1.0	0.95	8192
Coder	`kimi-k2.7-code`	Enabled (keep=all)	1.0	0.95	20480
Pentester	`kimi-k2.7-code`	Enabled (keep=all)	1.0	0.95	16384
Primary Agent / Assistant	`kimi-k2.7-code-highspeed`	Enabled (keep=all)	1.0	0.95	16384
Installer	`kimi-k2.5`	Enabled	1.0	0.95	16384
Reflector / Searcher / Enricher	`kimi-k2.5`	Disabled	0.6	0.95	4096
Simple	`kimi-k2.5`	Disabled	0.6	0.95	8192
Simple JSON	`kimi-k2.5`	Disabled	0.6	0.95	4096

Note: for kimi-k2.5 non-thinking agents, PentAGI also duplicates temperature: 0.6 into extra_body as a workaround — langchaingo's IsReasoningModel matches the substring 2.5 and force-overrides temperature to 1.0, and extra_body bypasses that override.

Key Features:

Always-On Reasoning Flagship: kimi-k3 never disables thinking and offers a 1M token context for the most demanding long-horizon coding and knowledge work
Ultra-Long Context: Up to 256K tokens (K2.7/K2.x) or 1M tokens (K3) for comprehensive codebase/documentation analysis
Native Multimodal: K2.7/K2.6/K2.5 support text + image + video input out of the box
Hybrid Thinking: K2.7/K2.6/K2.5 toggle between thinking and non-thinking via extra_body.thinking.type
Preserved Thinking (K2.7, K2.6): thinking.keep: "all" preserves historical reasoning_content across turns — required for multi-turn tool call chains
Automatic Context Caching: K3/K2.7/K2.x models cache repeated prefixes
Tool Calling: Full function-calling support for K3, K2.7, K2.x, and Moonshot V1
Coding-Optimized Variants: kimi-k2.7-code/kimi-k2.7-code-highspeed target higher success rates on long-context programming tasks, with the highspeed variant tuned for throughput
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

Variable	Default Value	Description
`QWEN_API_KEY`		Qwen API key for authentication
`QWEN_SERVER_URL`	`https://dashscope-us.aliyuncs.com/compatible-mode/v1`	Qwen API endpoint URL (international)
`QWEN_PROVIDER`		Provider prefix for LiteLLM integration (optional)

Configuration Examples

# Direct API usage (Global/US endpoint)
QWEN_API_KEY=your_qwen_api_key
QWEN_SERVER_URL=https://dashscope-us.aliyuncs.com/compatible-mode/v1

# Alternative endpoints
QWEN_SERVER_URL=https://dashscope-intl.aliyuncs.com/compatible-mode/v1  # International (Singapore)
QWEN_SERVER_URL=https://dashscope.aliyuncs.com/compatible-mode/v1       # Chinese Mainland (Beijing)

# With LiteLLM proxy
QWEN_API_KEY=your_litellm_key
QWEN_SERVER_URL=http://litellm-proxy:4000
QWEN_PROVIDER=dashscope  # Adds prefix to model names (dashscope/qwen-plus) for LiteLLM

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)

Model ID	Thinking	Intl	Global/US	China	Price (Input/Output/Cache)	Use Case
`qwen3.7-max`*	✅	✅	✅	✅	$2.50/$7.50/$0.50	Next-gen flagship for agent-centric era (generator/refiner/adviser default)
`qwen3.6-max-preview`	✅	✅	✅	✅	$1.30/$7.80/$0.13	Preview Max with enhanced vibe coding & front-end skills
`qwen3-max`	✅	✅	✅	✅	$1.20/$6.00/$0.24	Previous-gen flagship with agent programming upgrades
`qwen-plus`	✅	✅	✅	✅	$0.40/$4.00/$0.08	Qwen3-backbone Plus with switchable thinking modes

Balanced Plus Models (Mid-tier)

Model ID	Thinking	Intl	Global/US	China	Price (Input/Output/Cache)	Use Case
`qwen3.6-plus`*	✅	✅	✅	✅	$0.50/$3.00/$0.05	Native VL Plus with agentic coding (primary/assistant/pentester default)
`qwen3.5-plus`	✅	✅	✅	✅	$0.40/$2.40/$0.04	Previous-gen native VL with strong multimodal capabilities

Fast Flash Models (Cost-optimized)

Model ID	Thinking	Intl	Global/US	China	Price (Input/Output/Cache)	Use Case
`qwen3.6-flash`	✅	✅	✅	✅	$0.25/$1.50/$0.025	Latest Flash with significant agentic-coding boost
`qwen3.5-flash`*	✅	✅	✅	✅	$0.10/$0.40/$0.01	Ultra-fast lightweight (simple/reflector/searcher/enricher default)
`qwen-flash`	✅	✅	✅	✅	$0.05/$0.40/$0.01	Qwen3-series Flash with 1M context, tiered pricing

Code-Specialized Models

Model ID	Thinking	Intl	Global/US	China	Price (Input/Output/Cache)	Use Case
`qwen3-coder-plus`*	❌	✅	✅	✅	$1.00/$5.00/$0.20	Strong coding agent with autonomous programming (coder default)
`qwen3-coder-flash`*	❌	✅	✅	✅	$0.30/$1.50/$0.06	Fast code-gen with multi-turn tool stability (installer default)
`qwen3-coder-next`	❌	✅	✅	✅	$0.30/$1.50/—	Open-source code generation, SOTA at same scale

Vision-Language Models (Browser & Screenshot Analysis)

Model ID	Thinking	Intl	Global/US	China	Price (Input/Output/Cache)	Use Case
`qwen3-vl-plus`	✅	✅	✅	✅	$0.20/$1.60/$0.04	VL with visual agent capabilities, ultra-long video understanding
`qwen3-vl-flash`	✅	✅	✅	✅	$0.05/$0.40/$0.01	Small VL with 2D/3D localization for browser triage
`qvq-max`	✅	✅	✅	✅	$1.20/$4.80/—	Visual reasoning with chain-of-thought

Open-Source Qwen3.6 Series

Model ID	Thinking	Intl	Global/US	China	Price (Input/Output/Cache)	Use Case
`qwen3.6-27b`	✅	✅	✅	✅	$0.60/$3.60/—	Native VL on hybrid architecture, on-premises ready
`qwen3.6-35b-a3b`	✅	✅	✅	✅	$0.25/$1.49/—	Efficient 35B MoE (~3B active) for continuous monitoring

Open-Source Qwen3.5 Series

Model ID	Thinking	Intl	Global/US	China	Price (Input/Output/Cache)	Use Case
`qwen3.5-397b-a17b`	✅	✅	✅	✅	$0.60/$3.60/—	Largest 397B params (~17B active), exceptional reasoning
`qwen3.5-122b-a10b`	✅	✅	✅	✅	$0.40/$3.20/—	Large 122B params (~10B active), strong balance
`qwen3.5-35b-a3b`	✅	✅	✅	✅	$0.25/$2.00/—	Efficient 35B MoE (~3B active), cost-effective
`qwen3.5-27b`	✅	✅	✅	✅	$0.30/$2.40/—	Medium 27B with hybrid linear attention + sparse MoE

Open-Source Qwen3 Coder Series

Model ID	Thinking	Intl	Global/US	China	Price (Input/Output/Cache)	Use Case
`qwen3-coder-480b-a35b-instruct`	❌	✅	✅	✅	$1.50/$7.50/—	Largest open coder MoE (480B/~35B active)
`qwen3-coder-30b-a3b-instruct`	❌	✅	✅	✅	$0.45/$2.25/—	Efficient 30B MoE (~3B active), repository-scale

Open-Source Qwen3 Dense & MoE Series

Model ID	Thinking	Intl	Global/US	China	Price (Input/Output/Cache)	Use Case
`qwen3-next-80b-a3b-thinking`	✅	✅	✅	✅	$0.15/$1.20/—	Next-gen 80B MoE (~3B active) thinking-only
`qwen3-next-80b-a3b-instruct`	❌	✅	✅	✅	$0.15/$1.20/—	Next-gen 80B MoE instruction-following
`qwen3-235b-a22b`	✅	✅	✅	✅	$0.70/$8.40/—	Dual-mode 235B MoE (~22B active)
`qwen3-32b`	✅	✅	✅	✅	$0.16/$0.64/—	Versatile 32B dense dual-mode
`qwen3-30b-a3b`	✅	✅	✅	✅	$0.20/$2.40/—	Efficient 30B MoE (~3B active)
`qwen3-14b`	✅	✅	✅	✅	$0.35/$4.20/—	Medium 14B dense performance-cost balance
`qwen3-8b`	✅	✅	✅	✅	$0.18/$2.10/—	Compact 8B dense efficiency
`qwen3-4b`	✅	✅	✅	✅	$0.11/$1.26/—	Lightweight 4B dense for simple tasks
`qwen3-1.7b`	✅	✅	✅	✅	$0.11/$1.26/—	Ultra-compact 1.7B basic checks
`qwen3-0.6b`	✅	✅	✅	✅	$0.11/$1.26/—	Smallest 0.6B for edge monitoring

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:

Agent Role	Default Model	Tier
Generator / Refiner / Adviser (planning, mentor)	`qwen3.7-max`	Flagship
Primary / Assistant / Pentester	`qwen3.6-plus`	Balanced
Coder (exploit development)	`qwen3-coder-plus`	Code+
Installer (env setup)	`qwen3-coder-flash`	Code Fast
Simple / Reflector / Searcher / Enricher	`qwen3.5-flash`	Fast

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):

EMBEDDING_PROVIDER=openai
EMBEDDING_URL=https://dashscope-intl.aliyuncs.com/compatible-mode/v1  # International (Singapore)
# EMBEDDING_URL=https://dashscope.aliyuncs.com/compatible-mode/v1     # Chinese Mainland
EMBEDDING_KEY=sk-*******
EMBEDDING_MODEL=text-embedding-v4
EMBEDDING_BATCH_SIZE=         # optional, default applies
EMBEDDING_STRIP_NEW_LINES=    # optional, default applies

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).

MiniMax Provider Configuration

PentAGI integrates with MiniMax's M-series through the OpenAI-compatible https://api.minimax.io/v1 endpoint: large-context agentic models with tool calling, JSON output, and streaming.

Configuration Variables

Variable	Default Value	Description
`MINIMAX_API_KEY`		MiniMax API key for authentication
`MINIMAX_SERVER_URL`	`https://api.minimax.io/v1`	MiniMax API endpoint URL
`MINIMAX_PROVIDER`		Provider prefix for LiteLLM integration (optional)

Configuration Examples

# Direct API usage
MINIMAX_API_KEY=your_minimax_api_key
MINIMAX_SERVER_URL=https://api.minimax.io/v1

# With LiteLLM proxy
MINIMAX_API_KEY=your_litellm_key
MINIMAX_SERVER_URL=http://litellm-proxy:4000
MINIMAX_PROVIDER=minimax  # Adds prefix to model names (minimax/MiniMax-M3) for LiteLLM

Supported Models

PentAGI ships 3 MiniMax models with tool calling, JSON output, and streaming. MiniMax-M3 is the default for all agent types.

Model ID	Context	Price (Input/Output, ≤512K context)	Use Case
`MiniMax-M3`*	~1M	$0.30/$1.20 (2x above 512K tokens)	Latest flagship for agentic reasoning, tool use, code generation, and long-context tasks (default)
`MiniMax-M2.7`	204K	$0.30/$1.20	Previous-generation model with strong reasoning and coding
`MiniMax-M2.7-highspeed`	204K	$0.60/$2.40	Low-latency variant of M2.7 for fast-response scenarios

LiteLLM Integration: Set MINIMAX_PROVIDER=minimax to enable model name prefixing when using default PentAGI configurations with LiteLLM proxy. Leave empty for direct API usage.

Advanced Setup

Langfuse Integration

Langfuse provides advanced capabilities for monitoring and analyzing AI agent operations.

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

Enable integration with Langfuse for PentAGI service in .env file.

LANGFUSE_BASE_URL=http://langfuse-web:3000
LANGFUSE_PROJECT_ID= # default: value from ${LANGFUSE_INIT_PROJECT_ID}
LANGFUSE_PUBLIC_KEY= # default: value from ${LANGFUSE_INIT_PROJECT_PUBLIC_KEY}
LANGFUSE_SECRET_KEY= # default: value from ${LANGFUSE_INIT_PROJECT_SECRET_KEY}

Run the Langfuse stack:

curl -O https://raw.githubusercontent.com/vxcontrol/pentagi/master/docker-compose-langfuse.yml
docker compose -f docker-compose.yml -f docker-compose-langfuse.yml up -d

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.

Enable integration with OpenTelemetry and all observability services for PentAGI in .env file.

OTEL_HOST=otelcol:8148

Run the observability stack:

curl -O https://raw.githubusercontent.com/vxcontrol/pentagi/master/docker-compose-observability.yml
docker compose -f docker-compose.yml -f docker-compose-observability.yml up -d

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 http://otelcol:4318.

To run all available stacks together (Langfuse, Graphiti, and Observability):

docker compose -f docker-compose.yml -f docker-compose-langfuse.yml -f docker-compose-graphiti.yml -f docker-compose-observability.yml up -d

You can also register aliases for these commands in your shell to run it faster:

alias pentagi="docker compose -f docker-compose.yml -f docker-compose-langfuse.yml -f docker-compose-graphiti.yml -f docker-compose-observability.yml"
alias pentagi-up="docker compose -f docker-compose.yml -f docker-compose-langfuse.yml -f docker-compose-graphiti.yml -f docker-compose-observability.yml up -d"
alias pentagi-down="docker compose -f docker-compose.yml -f docker-compose-langfuse.yml -f docker-compose-graphiti.yml -f docker-compose-observability.yml down"

Knowledge Graph Integration (Graphiti)

Important

Graphiti is an optional beta integration and is disabled by default. Review Limitations and Security 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 asynchronously extracts structured knowledge from agent interactions and builds a graph of entities, relationships, evidence, and temporal context. PentAGI sends agent responses and tool executions to Graphiti and exposes the graphiti_search tool to enabled agents. Graphiti complements the primary pgvector memory; it does not replace it.

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
Flow-Scoped Recall: Reuse knowledge within the active flow without exposing data from other engagements by default
Advanced Querying: Search temporal context, relationships, successful tools, recent episodes, and entities by type

When enabled, PentAGI captures agent responses, tool execution details, and flow/task/subtask context. Ingestion is asynchronous, so newly submitted events can take time to become searchable.

Deployment Modes and Enabling

Graphiti can run as the bundled Neo4j + Graphiti stack, as an external service, or remain disabled.

For the bundled stack, configure .env:

GRAPHITI_ENABLED=true
GRAPHITI_TIMEOUT=30
GRAPHITI_URL=http://graphiti:8000
GRAPHITI_LLM_CLIENT_TYPE=openai

# Reused by the Graphiti OpenAI preset
OPEN_AI_KEY=your_openai_api_key
OPEN_AI_SERVER_URL=https://api.openai.com/v1

# Bundled Neo4j
NEO4J_USER=neo4j
NEO4J_DATABASE=neo4j
NEO4J_PASSWORD=replace_with_a_strong_password
NEO4J_URI=bolt://neo4j:7687

Download the optional compose file when installing manually, then start both stacks:

curl -O https://raw.githubusercontent.com/vxcontrol/pentagi/master/docker-compose-graphiti.yml
docker compose -f docker-compose.yml -f docker-compose-graphiti.yml up -d

The base stack must create the external pentagi-network before the Graphiti stack can start. The installer handles stack ordering automatically.

For an external Graphiti deployment, set GRAPHITI_ENABLED=true and point GRAPHITI_URL to its API. Do not start docker-compose-graphiti.yml; configure providers, embeddings, the graph database, and ingest tuning on the external service itself.

PentAGI enables its client only when both GRAPHITI_ENABLED=true and GRAPHITI_URL is non-empty. At startup it performs three health-check attempts with a two-second backoff. If they all fail, PentAGI logs a warning and continues with Graphiti disabled.

LLM Provider and Model Presets

GRAPHITI_LLM_CLIENT_TYPE selects one deployment-wide preset. Model names and call parameters are not environment variables; they live in graphiti/<provider>.yaml.

Preset	Credentials and endpoint	Shipped main model
`openai`	`OPEN_AI_KEY`, `OPEN_AI_SERVER_URL`	`openai/gpt-5-mini`
`gemini`	`GEMINI_API_KEY`, `GEMINI_SERVER_URL`	`gemini/gemini-2.5-flash-lite`
`custom`	`LLM_SERVER_KEY`, `LLM_SERVER_URL`	`Qwen/Qwen3.6-27B-FP8`
`litellm`	`GRAPHITI_LITELLM_API_KEY`, `GRAPHITI_LITELLM_BASE_URL`	`openrouter/openai/gpt-oss-20b`

The Gemini preset uses Graphiti's LiteLLM/OpenAI-compatible client path. Point GEMINI_SERVER_URL at a compatible gateway if the native Gemini endpoint does not provide the required OpenAI-compatible API.

Each preset file must contain a matching provider plus MODEL_NAME and SMALL_MODEL_NAME mappings. The small model is used for reranking and lighter calls. Supported call settings include temperature, token limits, sampling and penalty parameters, JSON mode, reasoning effort, verbosity, pricing metadata, and provider-specific extra_body.

The installer copies examples/graphiti beside the installation as ./graphiti. The compose mount is controlled by:

GRAPHITI_CONFIG_PATH=./graphiti
GRAPHITI_CONFIG_DIR=llm_configs

GRAPHITI_CONFIG_PATH may point directly to ./examples/graphiti for development. GRAPHITI_CONFIG_DIR=llm_configs activates the mounted presets. If an older .env omits that variable, a newer compose file mounts an empty host directory at the unused configs path instead of hiding the presets built into the image.

Note

GRAPHITI_MODEL_NAME is obsolete and ignored. Edit the active YAML preset instead, then restart the Graphiti container.

Graphiti Embedding Configuration

By default, Graphiti uses the active LLM preset's credentials and its default OpenAI embedding model. To use PentAGI's shared embedding endpoint explicitly:

GRAPHITI_SEPARATE_EMBEDDING=true
EMBEDDING_URL=https://embedding.example.com/v1
EMBEDDING_KEY=your_embedding_api_key
EMBEDDING_MODEL=openai/text-embedding-3-large

Graphiti's embedder is OpenAI-compatible. EMBEDDING_PROVIDER is used by PentAGI but is not passed to Graphiti, so a non-OpenAI-compatible embedding provider cannot be shared directly.

Ingestion and Extraction Tuning

The supplied defaults prioritize flow isolation and limit expensive extraction to useful events.

Ingest policy actions:

REJECT: do not store the episode.
SKIP_LLM: store the episode for retrieval but do not extract nodes or edges.
PROCESS: store the episode and run full LLM extraction.

Variable	Default	When to change it
`GRAPHITI_INGEST_POLICY_RULES`	`{"graphiti_search":"REJECT","tool_execution_terminal":"PROCESS","tool_execution_file":"PROCESS"}`	Add narrow, case-insensitive name/source patterns when specific events need different handling
`GRAPHITI_INGEST_POLICY_FIELD`	`both`	Restrict matching to `name` or `source_description` only when event naming is controlled
`GRAPHITI_INGEST_POLICY_DEFAULT_ACTION`	`SKIP_LLM`	Use `PROCESS` only when every unmatched event justifies extraction cost
`GRAPHITI_INGEST_USE_GROUP_ACTORS`	`true`	Keep enabled to preserve FIFO ordering independently for each flow
`GRAPHITI_INGEST_WORKER_COUNT`	`16`	Raise for more concurrent flows when the LLM and database have capacity; lower to control load
`GRAPHITI_INGEST_LOCK_BY_GROUP_ID`	`true`	Used only in shared-pool mode; ignored when group actors are enabled
`GRAPHITI_INGEST_TASK_MAX_RETRIES`	`1` (`0`-`5`)	Increase for transient LLM/network failures
`GRAPHITI_INGEST_TASK_RETRY_DELAY_SEC`	`2.0` (`0.5`-`60`)	Increase when an upstream service needs more recovery time
`GRAPHITI_INGEST_TASK_TIMEOUT_SEC`	`0` (`0`-`3600`)	Set a finite value to prevent one stalled request from blocking a flow; `0` disables the timeout
`GRAPHITI_INGEST_QUEUE_MAX_SIZE`	`0`	Set a bound to return HTTP 429 instead of allowing an unlimited backlog
`GRAPHITI_INGEST_DEAD_LETTER_ENABLED`	`false`	Enable when failed episodes must be retained for operational review

Extraction uses the following fallback order: full combined extraction (nodes, attributes, summaries, and edges in one call), regular combined extraction (nodes and edges), then separate node/edge extraction. Empty or failed combined results automatically fall back; these log messages are expected during normal operation.

Variable	Default	Effect
`GRAPHITI_TAXONOMY_LAYER_PROFILE`	`STRUCTURAL,EVIDENCE,PROGRESS,ATTEMPT`	Controls which edge classes appear in prompts and pass validation; `full`/`all` enables every class and `minimal` selects the core attack graph
`GRAPHITI_USE_COMBINED_FULL_EXTRACTION`	`true`	Enables the most compact single-call extraction path
`GRAPHITI_USE_COMBINED_EXTRACTION`	`true`	Enables the regular combined fallback
`GRAPHITI_COMBINED_FULL_GATING_ENABLED`	`true`	Skips expensive full extraction for low-signal administrative/search events
`GRAPHITI_COMBINED_DIAGNOSTIC_SAMPLES`	`false`	Includes content samples in diagnostics; keep disabled because pentest output can contain credentials
`GRAPHITI_ANCHOR_NODE_MODE`	`smart`	`smart` loads all key entities plus limited high-volume types; `limit` applies one total cap
`GRAPHITI_ANCHOR_NODE_LIMIT`	`25` (`1`-`500`)	Total anchor cap in `limit` mode
`GRAPHITI_ANCHOR_MASS_TYPE_LIMIT`	`10` (`1`-`100`)	Per-type cap in `smart` mode; `0` is invalid
`GRAPHITI_ANCHOR_QUERY_TIMEOUT`	`10` (`1`-`60`)	Bounds anchor lookup; timeout degrades gracefully to no anchors

Anchors connect entities across episodes and are used by the separate extraction path. Combined extraction has already produced its edges and does not perform this anchor lookup.

These flags are passed as process environment variables by the bundled compose file. This is important for combined extraction because Graphiti reads those flags when Python modules are imported.

Runtime, Logging, and Neo4j

The values below are PentAGI's recommended .env.example/compose defaults, not the raw Graphiti image fallbacks. Running a freshly pulled image behind an old compose file can instead enable telemetry and global search, use one shared-pool worker with PROCESS as the unmatched ingest action, enable the full taxonomy, and disable combined extraction. Keep the image, compose file, .env, and presets in sync.

Variable	Default	Guidance
`GRAPHITI_CPUS`, `GRAPHITI_MEMORY`	`2.0`, `2G`	Container limits; raise together with concurrency only after observing CPU and memory pressure
`GRAPHITI_SEMAPHORE_LIMIT`	`20`	Limits parallel Graphiti coroutines; it is separate from ingest worker concurrency
`GRAPHITI_TELEMETRY_ENABLED`	`false`	Enables anonymous Graphiti telemetry when set to `true`
`GRAPHITI_LOG_LEVEL`	`INFO`	Use `DEBUG` temporarily; it can produce sensitive and high-volume output
`GRAPHITI_LOG_STDOUT`	`events`	`off`, `events`, or `full`; `events` is recommended for containers
`GRAPHITI_FLOW_LOGGER_WARN_COUNT`	`256`	Warns about growth of cached per-flow loggers; `0` disables the warning
`GRAPHITI_DEBUG_RUNTIME_RESOURCES`	`false`	Enables `/debug/runtime-resources`; expose only to trusted operators
`GRAPHITI_SEARCH_SCOPE`	`flowid`	Keep for flow/tenant isolation; `all` enables global searches and can expose other engagements
`GRAPHITI_LOG_FORMAT`	`json`	Reserved by the current deployment contract; the Graphiti logger does not yet apply it
`NEO4J_CPUS`, `NEO4J_MEMORY`	`4.0`, `4G`	Neo4j container limits; use `neo4j-admin server memory-recommendation --docker` for production sizing
`NEO4J_SHM_SIZE`	`4g`	`/dev/shm` limit; actual use counts toward the container memory limit
`NEO4J_NOFILE`	`65536`	Open-file soft/hard limit, suitable for many indexes and concurrent connections
`NEO4J_HEAP_INITIAL_SIZE`, `NEO4J_HEAP_MAX_SIZE`, `NEO4J_PAGECACHE_SIZE`	`2G`, `2G`, `1G`	JVM heap/page cache sizing; `NEO4J_CPUS`/`NEO4J_MEMORY` only cap the container, the JVM does not reliably size itself to fit inside that cap on its own. Defaults favor heap over page cache — suited to a low write-throughput deployment with occasional wide reads, since query execution/result materialization lives in heap while a small dataset is already comfortably held by 1G of page cache; re-run `neo4j-admin server memory-recommendation --docker` once real data volume is known
`NEO4J_TRANSACTION_MAX`	`1G`	Caps a single transaction's memory (`db.memory.transaction.max`) so one runaway/unbounded query (e.g. a Cartesian product or an unbounded variable-length path before a `LIMIT`) fails cleanly with an out-of-memory Cypher error instead of exhausting the whole heap and taking down every other query on the server
`NEO4J_BOLT_ADVERTISED_ADDRESS`	empty	Set only when Neo4j Browser and the Bolt connector are reverse-proxied on different public domains (e.g. behind Guarder with CORS/cookie-group support for cross-origin bolt access); format `host:port`. Left empty, Neo4j's discovery endpoint advertises whatever `Host` header the request arrived with, which is correct only when both share one domain
`NEO4J_HTTP_ADVERTISED_ADDRESS`	empty	Set only when a reverse proxy in front of Neo4j Browser strips or rewrites the `Host` header, making the dynamic Host-header-based advertised address incorrect; format `host:port`. Leave empty in the common case (proxy forwards `Host` unchanged)

NEO4J_USER, NEO4J_PASSWORD, NEO4J_URI, and NEO4J_DATABASE configure the bundled connection. Neo4j Community Edition supports only its default database; do not configure a separate database name that requires Enterprise multi-database support.

The installer copies examples/neo4j beside the installation as ./neo4j. It contains static, non-.env-tunable settings that don't have a NEO4J_* variable: conf/neo4j.conf and conf/apoc.conf, plus a version-pinned plugins/apoc-*-core.jar. The compose mount is controlled by:

NEO4J_DIR=./neo4j

NEO4J_DIR may point directly to ./examples/neo4j for development. Both conf/ and plugins/ are mounted read-only; the stack still starts on Neo4j's built-in defaults (without APOC) if the directory is absent, since Docker creates an empty one automatically. Do not duplicate any NEO4J_* variable from the table above inside conf/neo4j.conf — the Neo4j Docker entrypoint always strips a matching line from the mounted file and re-appends the environment variable's value, so a duplicated setting in the file would be silently ignored.

The bundled stack currently wires Neo4j only. The Graphiti image contains FalkorDB support, but using it requires a separately configured deployment because the stock compose file does not expose GRAPHITI_GRAPH_BACKEND or FALKORDB_*.

Verification and Troubleshooting

Check service health, queue state, and logs:

docker compose -f docker-compose.yml -f docker-compose-graphiti.yml ps graphiti neo4j
docker compose -f docker-compose.yml -f docker-compose-graphiti.yml logs -f graphiti
curl -fsS http://localhost:8000/healthcheck
curl -fsS http://localhost:8000/queue-size

Neo4j Browser is available at http://localhost:7474; the Graphiti OpenAPI UI is at http://localhost:8000/docs. Both are bound to localhost by the stock compose file.

Common failures:

A missing API key or base URL for the selected preset, a missing YAML file, or a YAML provider mismatch causes the Graphiti container to fail startup validation.
LLM_CLIENT_TYPE=openai rejects local/custom model prefixes; use the custom preset for an OpenAI-compatible local server.
In flowid search mode, requests without a group ID are rejected. PentAGI supplies the flow-derived group ID automatically.
A bounded full queue returns HTTP 429. /queue-size reports waiting, processing, active-group, and dropped counters.
Invalid retry, timeout, or anchor ranges fail startup rather than being silently normalized.

Update .env, docker-compose-graphiti.yml, the Graphiti image, and the graphiti preset directory together. Pulling only a new image can retain older compose defaults and silently change extraction behavior.

Limitations and Security

Graphiti is beta and has no in-app graph explorer.
One provider preset is active for the entire Graphiti deployment; it is not selected per PentAGI agent or flow.
Graphiti extraction, reranking, and embeddings incur billing independently of the model used by the main PentAGI flow.
Search is flow-scoped by default. Cross-flow reuse requires an explicit global-search design and must not be enabled on shared or multi-tenant deployments without additional isolation.
The Graphiti HTTP API has no authentication layer in the bundled service. The stock compose binds it and Neo4j to 127.0.0.1; secure external deployments with network controls and authentication at a trusted reverse proxy.
Agent and tool output may contain credentials and exploitation evidence. Protect Neo4j data, logs, dead letters, diagnostics, and backups accordingly.
If Graphiti is unavailable, PentAGI continues with its primary memory and vector store after logging the failed startup health check. Set GRAPHITI_ENABLED=false to disable the integration explicitly.

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:

${PUBLIC_URL}/api/v1/auth/login-callback

For GitHub OAuth:

Create a new OAuth App in your GitHub account.
Set Homepage URL to your PUBLIC_URL.
Set Authorization callback URL to ${PUBLIC_URL}/api/v1/auth/login-callback.
Add the client credentials to your .env file:

PUBLIC_URL=https://pentagi.example.com
OAUTH_GITHUB_CLIENT_ID=your_github_client_id
OAUTH_GITHUB_CLIENT_SECRET=your_github_client_secret

For Google OAuth:

Create OAuth credentials in your Google Cloud project.
Use the same callback endpoint: ${PUBLIC_URL}/api/v1/auth/login-callback.
Add the client credentials to your .env file:

PUBLIC_URL=https://pentagi.example.com
OAUTH_GOOGLE_CLIENT_ID=your_google_client_id
OAUTH_GOOGLE_CLIENT_SECRET=your_google_client_secret

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:

Variable	Default	Description
`PENTAGI_IMAGE`	`vxcontrol/pentagi:latest`	Docker image used for the main PentAGI application service
`DOCKER_DEFAULT_IMAGE`	`debian:latest`	Default Docker image for general tasks and ambiguous cases
`DOCKER_DEFAULT_IMAGE_FOR_PENTEST`	`vxcontrol/kali-linux`	Default Docker image for security/penetration testing tasks

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:

# Using a custom PentAGI application image
PENTAGI_IMAGE=registry.example.com/security/pentagi:latest

# Using a custom image for general tasks
DOCKER_DEFAULT_IMAGE=mycompany/custom-debian:latest

# Using a specialized image for penetration testing
DOCKER_DEFAULT_IMAGE_FOR_PENTEST=mycompany/pentest-tools:v2.0

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:

Confirm that the host can resolve and reach docker.io.
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.
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.
Restart Docker after changing the daemon configuration, then rerun the installer checks or Compose startup.

Example Docker daemon mirror configuration:

{
  "registry-mirrors": ["https://mirror.example.com"]
}

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.

Troubleshooting: "failed to select primary docker image via llm call"

A flow that fails immediately with failed to select primary docker image via llm call usually indicates a problem with the configured LLM backend, not with Docker or the image registry. Older PentAGI versions reported the same failure as failed to get primary docker image, which led users to debug Docker even though the registry was healthy.

When a flow starts, PentAGI makes its first LLM call to choose the primary Docker image for the task. This image-selection call runs through the simple agent type, so a failure here points at the model assigned to that agent type rather than at Docker. A message such as API returned unexpected status code: 502 or 404 in this context is returned by the LLM backend, not by Docker Hub.

This is distinct from the registry reachability problems described above: if Docker pulls succeed and the Compose stack starts, but flow creation still fails at image selection, investigate the LLM backend rather than Docker.

To diagnose:

Check PentAGI logs first: docker logs pentagi.
Check the logs of your configured LLM backend (the server behind your provider or LLM_SERVER_URL).
Verify that the base URL, API key, and model name in Custom LLM Provider Configuration are correct and reachable from the container. If you assign different models per agent type, check the model used by the simple agent type, since image selection runs through it.
For custom, OpenAI-compatible, vLLM, or SGLang backends, confirm that the model supports tool calling (function calling) and that the matching tool-call parser is enabled. A missing or mismatched tool-call parser is a known cause of this failure.

Development

Development Requirements

golang
nodejs
docker
postgres

Environment Setup

Backend Setup

Run once cd backend && go mod download to install needed packages.

For generating swagger files have to run

swag init -g ../../pkg/server/router.go -o pkg/server/docs/ --parseDependency --parseInternal --parseDepth 2 -d cmd/pentagi

before installing swag package via

go install github.com/swaggo/swag/cmd/swag@v1.8.7

For generating graphql resolver files have to run

go run github.com/99designs/gqlgen --config ./gqlgen/gqlgen.yml

after that you can see the generated files in pkg/graph folder.

For generating ORM methods (database package) from sqlc configuration

docker run --rm -v $(pwd):/src -w /src --network pentagi-network -e DATABASE_URL="{URL}" sqlc/sqlc:1.27.0 generate -f sqlc/sqlc.yml

For generating Langfuse SDK from OpenAPI specification

fern generate --local

and to install fern-cli

pnpm add -g fern-api

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:

pnpm add -g graphql-codegen

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/<my-user>/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:

Pool	Env var	Default	Used by
Shared `sql.DB`	`DATABASE_MAX_OPEN_CONNS`	`25`	All sqlc queries and GORM handlers share a single `*sql.DB`
Shared `pgxpool`	`DATABASE_VECTOR_MAX_CONNS`	`10`	All pgvector stores (agent memory + knowledge API) share a single pool

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):

Available for client connections  = 97
  pentagi sql.DB  (DATABASE_MAX_OPEN_CONNS)   = 25
  pentagi pgxpool (DATABASE_VECTOR_MAX_CONNS) = 10
  pgexporter                                  =  3
  autovacuum workers                          =  3
  ─────────────────────────────────────────
  Total consumed                              = 41
  Free buffer                                 = 56  (≈ 58 %)

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:

pgvector:
  image: vxcontrol/pgvector:latest
  command: postgres -c max_connections=200

To inspect the live connection budget on a running deployment:

# Postgres limits
docker exec pgvector sh -c 'psql -U "$POSTGRES_USER" -d "$POSTGRES_DB" -c \
  "SELECT name, setting FROM pg_settings
   WHERE name IN ('"'"'max_connections'"'"', '"'"'superuser_reserved_connections'"'"');"'

# Current usage vs. available
docker exec pgvector sh -c 'psql -U "$POSTGRES_USER" -d "$POSTGRES_DB" -c \
  "SELECT max_conn, used, max_conn - used AS available
   FROM (SELECT current_setting('"'"'max_connections'"'"')::int AS max_conn,
                count(*) AS used FROM pg_stat_activity) t;"'

# Breakdown by client
docker exec pgvector sh -c 'psql -U "$POSTGRES_USER" -d "$POSTGRES_DB" -c \
  "SELECT application_name, client_addr, state, count(*)
   FROM pg_stat_activity
   WHERE pid <> pg_backend_pid()
   GROUP BY 1, 2, 3 ORDER BY count DESC;"'

External PostgreSQL and schema handling

DATABASE_URL may point at any PostgreSQL instance, not only the bundled pgvector container. Two extra knobs apply when — and only when — TENANT_ID is set, because that is when PentAGI creates its own schema and rewrites the connection's search_path:

Env var	Default	Purpose
`DATABASE_EXTENSIONS_SCHEMA`	`public`	Schema holding the shared `vector` and `pg_trgm` extensions that every tenant's `search_path` must reach
`DATABASE_SEARCH_PATH_VIA_OPTIONS`	`false`	Send the tenant `search_path` inside the `options` startup parameter instead of as a bare connection parameter

Supabase (cloud or self-hosted) needs both of them considered, and is the reason they exist:

Supabase installs its bundled extensions into an extensions schema instead of public, so set DATABASE_EXTENSIONS_SCHEMA=extensions. Without it, startup aborts with an error naming the schema where vector was actually found — no need to move a provider-managed extension with ALTER EXTENSION.
Supabase's pooler (Supavisor) does not reliably forward a bare search_path connection parameter. Prefer a direct PostgreSQL connection: self-hosted, expose the db service port and bypass the supavisor service; cloud, use the "Direct connection" string (or the IPv4 add-on on IPv4-only networks). If the pooler cannot be bypassed, use its session mode and try DATABASE_SEARCH_PATH_VIA_OPTIONS=true — PentAGI verifies the effective schema on boot and refuses to start if it did not take effect, so a silent cross-tenant data mix-up is not possible.

Both settings are managed by the installer under Server Settings, next to TENANT_ID — see Running Several Instances for that scenario, and Multi-Instance Deployment for the full matrix, including the PgBouncer recipe (pool_mode = session, ignore_startup_parameters, per-tenant connect_query).

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 http://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:

# Default configuration with .env file
cd backend
go run cmd/ctester/*.go -verbose

# Custom provider configuration
go run cmd/ctester/*.go -config ../examples/configs/openrouter.provider.yml -verbose

# Generate a report file
go run cmd/ctester/*.go -config ../examples/configs/deepinfra.provider.yml -report ../test-report.md

# Test specific agent types only
go run cmd/ctester/*.go -agents simple,simple_json,primary_agent -verbose

# Test specific test groups only
go run cmd/ctester/*.go -groups basic,advanced -verbose

For Users (using Docker image)

If you prefer to use the pre-built Docker image without setting up a development environment:

# Using Docker to test with default environment
docker run --rm -v $(pwd)/.env:/opt/pentagi/.env vxcontrol/pentagi /opt/pentagi/bin/ctester -verbose

# Test with your custom provider configuration
docker run --rm \
  -v $(pwd)/.env:/opt/pentagi/.env \
  -v $(pwd)/my-config.yml:/opt/pentagi/config.yml \
  vxcontrol/pentagi /opt/pentagi/bin/ctester -config /opt/pentagi/config.yml -agents simple,primary_agent,coder -verbose

# Generate a detailed report
docker run --rm \
  -v $(pwd)/.env:/opt/pentagi/.env \
  -v $(pwd):/opt/pentagi/output \
  vxcontrol/pentagi /opt/pentagi/bin/ctester -report /opt/pentagi/output/report.md

Using Pre-configured Providers

The Docker image comes with built-in support for major providers (OpenAI, Anthropic, Gemini, Ollama) and pre-configured provider files for additional services (OpenRouter, OpenCode, Atlas, OrcaRouter, DeepInfra, DeepSeek, Moonshot, Novita, xAI):

# Test with OpenRouter configuration
docker exec -it pentagi /opt/pentagi/bin/ctester -config /opt/pentagi/conf/openrouter.provider.yml

# Test with OpenCode Go plan configuration
docker exec -it pentagi /opt/pentagi/bin/ctester -config /opt/pentagi/conf/opencode.provider.yml

# Test with DeepInfra configuration
docker exec -it pentagi /opt/pentagi/bin/ctester -config /opt/pentagi/conf/deepinfra.provider.yml

# Test with DeepSeek configuration
docker exec -it pentagi /opt/pentagi/bin/ctester -provider deepseek

# Test with GLM configuration
docker exec -it pentagi /opt/pentagi/bin/ctester -provider glm

# Test with Kimi configuration
docker exec -it pentagi /opt/pentagi/bin/ctester -provider kimi

# Test with Qwen configuration
docker exec -it pentagi /opt/pentagi/bin/ctester -provider qwen

# Test with DeepSeek configuration file for custom provider
docker exec -it pentagi /opt/pentagi/bin/ctester -config /opt/pentagi/conf/deepseek.provider.yml

# Test with Moonshot configuration file for custom provider
docker exec -it pentagi /opt/pentagi/bin/ctester -config /opt/pentagi/conf/moonshot.provider.yml

# Test with Novita configuration
docker exec -it pentagi /opt/pentagi/bin/ctester -config /opt/pentagi/conf/novita.provider.yml

# Test with xAI configuration
docker exec -it pentagi /opt/pentagi/bin/ctester -config /opt/pentagi/conf/xai.provider.yml

# Test with OpenAI configuration
docker exec -it pentagi /opt/pentagi/bin/ctester -type openai

# Test with Anthropic configuration
docker exec -it pentagi /opt/pentagi/bin/ctester -type anthropic

# Test with Gemini configuration
docker exec -it pentagi /opt/pentagi/bin/ctester -type gemini

# Test with AWS Bedrock configuration
docker exec -it pentagi /opt/pentagi/bin/ctester -type bedrock

# Test with Custom OpenAI configuration
docker exec -it pentagi /opt/pentagi/bin/ctester -config /opt/pentagi/conf/custom-openai.provider.yml

# Test with Ollama configuration (local inference)
docker exec -it pentagi /opt/pentagi/bin/ctester -config /opt/pentagi/conf/ollama-llama318b.provider.yml

# Test with Ollama Qwen3 32B configuration (requires custom model creation)
docker exec -it pentagi /opt/pentagi/bin/ctester -config /opt/pentagi/conf/ollama-qwen332b-fp16-tc.provider.yml

# Test with Ollama QwQ 32B configuration (requires custom model creation and 71.3GB VRAM)
docker exec -it pentagi /opt/pentagi/bin/ctester -config /opt/pentagi/conf/ollama-qwq32b-fp16-tc.provider.yml

To use these configurations, your .env file only needs to contain:

LLM_SERVER_URL=https://openrouter.ai/api/v1      # or https://api.deepinfra.com/v1/openai or https://api.openai.com/v1 or https://opencode.ai/zen/go/v1 or https://api.novita.ai/openai or https://api.atlascloud.ai/v1 or https://api.orcarouter.ai/v1 or https://api.x.ai/v1
LLM_SERVER_KEY=your_api_key
LLM_SERVER_MODEL=                                # Leave empty, as models are specified in the config
LLM_SERVER_CONFIG_PATH=/opt/pentagi/conf/openrouter.provider.yml  # or deepinfra.provider.ymll or opencode.provider.ymll or custom-openai.provider.yml or novita.provider.yml or atlas.provider.yml or orcarouter.provider.yml or xai.provider.yml
LLM_SERVER_PROVIDER=                             # Provider name for LiteLLM proxy (e.g., openrouter, deepseek, moonshot, novita, opencode, orcarouter, xai)
LLM_SERVER_LEGACY_REASONING=false                # Controls reasoning format, for OpenAI must be true (default: false)
LLM_SERVER_PRESERVE_REASONING=false              # Preserve reasoning content in multi-turn conversations (required by Moonshot, default: false)

# For OpenAI (official API)
OPEN_AI_KEY=your_openai_api_key                  # Your OpenAI API key
OPEN_AI_SERVER_URL=https://api.openai.com/v1     # OpenAI API endpoint

# For Anthropic (Claude models)
ANTHROPIC_API_KEY=your_anthropic_api_key         # Your Anthropic API key
ANTHROPIC_SERVER_URL=https://api.anthropic.com/v1  # Anthropic API endpoint

# For Gemini (Google AI)
GEMINI_API_KEY=your_gemini_api_key               # Your Google AI API key
GEMINI_SERVER_URL=https://generativelanguage.googleapis.com  # Google AI API endpoint

# For AWS Bedrock (enterprise foundation models)
BEDROCK_REGION=us-east-1                         # AWS region for Bedrock service
# Authentication (choose one method, priority: DefaultAuth > BearerToken > AccessKey):
BEDROCK_DEFAULT_AUTH=false                       # Use AWS SDK credential chain (env vars, EC2 role, ~/.aws/credentials)
BEDROCK_BEARER_TOKEN=                            # Bearer token authentication (takes priority over static credentials)
BEDROCK_ACCESS_KEY_ID=your_aws_access_key        # AWS access key ID (static credentials)
BEDROCK_SECRET_ACCESS_KEY=your_aws_secret_key    # AWS secret access key (static credentials)
BEDROCK_SESSION_TOKEN=                           # AWS session token (optional, for temporary credentials with static auth)
BEDROCK_SERVER_URL=                              # Optional custom Bedrock endpoint (VPC endpoints, local testing)
BEDROCK_CONFIG_PATH=                             # Optional path to a custom YAML provider config (overrides built-in model/pricing definitions)

# For Ollama (local server or cloud)
OLLAMA_SERVER_URL=                               # Local: http://ollama-server:11434, Cloud: https://ollama.com
OLLAMA_SERVER_API_KEY=                           # Required for Ollama Cloud (https://ollama.com/settings/keys), leave empty for local
OLLAMA_SERVER_MODEL=
OLLAMA_SERVER_CONFIG_PATH=
OLLAMA_SERVER_PULL_MODELS_TIMEOUT=
OLLAMA_SERVER_PULL_MODELS_ENABLED=
OLLAMA_SERVER_LOAD_MODELS_ENABLED=

# For DeepSeek (Chinese AI with strong reasoning)
DEEPSEEK_API_KEY=                                # DeepSeek API key
DEEPSEEK_SERVER_URL=https://api.deepseek.com     # DeepSeek API endpoint
DEEPSEEK_PROVIDER=                               # Optional: LiteLLM prefix (e.g., 'deepseek')

# For GLM (Zhipu AI)
GLM_API_KEY=                                     # GLM API key
GLM_SERVER_URL=https://api.z.ai/api/paas/v4      # GLM API endpoint (international)
GLM_PROVIDER=                                    # Optional: LiteLLM prefix (e.g., 'zai')

# For Kimi (Moonshot AI)
KIMI_API_KEY=                                    # Kimi API key
KIMI_SERVER_URL=https://api.moonshot.ai/v1       # Kimi API endpoint (international)
KIMI_PROVIDER=                                   # Optional: LiteLLM prefix (e.g., 'moonshot')

# For Qwen (Alibaba Cloud DashScope)
QWEN_API_KEY=                                    # Qwen API key
QWEN_SERVER_URL=https://dashscope-us.aliyuncs.com/compatible-mode/v1  # Qwen API endpoint (US)
QWEN_PROVIDER=                                   # Optional: LiteLLM prefix (e.g., 'dashscope')

# For Ollama (local inference) use variables above
OLLAMA_SERVER_URL=http://localhost:11434
OLLAMA_SERVER_MODEL=llama3.1:8b-instruct-q8_0
OLLAMA_SERVER_CONFIG_PATH=/opt/pentagi/conf/ollama-llama318b.provider.yml
OLLAMA_SERVER_PULL_MODELS_ENABLED=false
OLLAMA_SERVER_LOAD_MODELS_ENABLED=false

Using OpenAI with Unverified Organizations

For OpenAI accounts with unverified organizations that don't have access to the latest reasoning models (o1, o3, o4-mini), you need to use a custom configuration.

To use OpenAI with unverified organization accounts, configure your .env file as follows:

LLM_SERVER_URL=https://api.openai.com/v1
LLM_SERVER_KEY=your_openai_api_key
LLM_SERVER_MODEL=                                # Leave empty, models are specified in config
LLM_SERVER_CONFIG_PATH=/opt/pentagi/conf/custom-openai.provider.yml
LLM_SERVER_LEGACY_REASONING=true                 # Required for OpenAI reasoning format

This configuration uses the pre-built custom-openai.provider.yml file that maps all agent types to models available for unverified organizations, using o3-mini instead of models like o1, o3, and o4-mini.

You can test this configuration using:

# Test with custom OpenAI configuration for unverified accounts
docker exec -it pentagi /opt/pentagi/bin/ctester -config /opt/pentagi/conf/custom-openai.provider.yml

Note

The LLM_SERVER_LEGACY_REASONING=true setting is crucial for OpenAI compatibility as it ensures reasoning parameters are sent in the format expected by OpenAI's API.

Using LiteLLM Proxy

When using LiteLLM proxy to access various LLM providers, model names are prefixed with the provider name (e.g., moonshot/kimi-2.5 instead of kimi-2.5). To use the same provider configuration files with both direct API access and LiteLLM proxy, set the LLM_SERVER_PROVIDER variable:

# Direct access to Moonshot API
LLM_SERVER_URL=https://api.moonshot.ai/v1
LLM_SERVER_KEY=your_moonshot_api_key
LLM_SERVER_CONFIG_PATH=/opt/pentagi/conf/moonshot.provider.yml
LLM_SERVER_PROVIDER=                             # Empty for direct access

# Access via LiteLLM proxy
LLM_SERVER_URL=http://litellm-proxy:4000
LLM_SERVER_KEY=your_litellm_api_key
LLM_SERVER_CONFIG_PATH=/opt/pentagi/conf/moonshot.provider.yml
LLM_SERVER_PROVIDER=moonshot                     # Provider prefix for LiteLLM

With LLM_SERVER_PROVIDER=moonshot, the system automatically prefixes all model names from the configuration file with moonshot/, making them compatible with LiteLLM's model naming convention.

LiteLLM Provider Name Mapping:

When using LiteLLM proxy, set the corresponding *_PROVIDER variable to enable model prefixing:

deepseek - for DeepSeek models (DEEPSEEK_PROVIDER=deepseek → deepseek/deepseek-v4-flash)
zai - for GLM models (GLM_PROVIDER=zai → zai/glm-4)
moonshot - for Kimi models (KIMI_PROVIDER=moonshot → moonshot/kimi-k2.5)
dashscope - for Qwen models (QWEN_PROVIDER=dashscope → dashscope/qwen-plus)
openai, anthropic, gemini - for major cloud providers
opencode - for OpenCode Go plan
openrouter - for OpenRouter aggregator
orcarouter - for OrcaRouter aggregator
deepinfra - for DeepInfra hosting
novita - for Novita AI
xai - for xAI (grok-* models)
Any other provider name configured in your LiteLLM instance

Example with LiteLLM:

# Use DeepSeek models via LiteLLM proxy with model prefixing
DEEPSEEK_API_KEY=your_litellm_proxy_key
DEEPSEEK_SERVER_URL=http://litellm-proxy:4000
DEEPSEEK_PROVIDER=deepseek  # Models become deepseek/deepseek-v4-flash, deepseek/deepseek-v4-pro for LiteLLM

# Direct DeepSeek API usage (no prefix needed)
DEEPSEEK_API_KEY=your_deepseek_api_key
DEEPSEEK_SERVER_URL=https://api.deepseek.com
# Leave DEEPSEEK_PROVIDER empty

This approach allows you to:

Use the same configuration files for both direct and proxied access
Switch between providers without modifying configuration files
Easily test different routing strategies with LiteLLM

Running Tests in a Production Environment

If you already have a running PentAGI container and want to test the current configuration:

# Run ctester in an existing container using current environment variables
docker exec -it pentagi /opt/pentagi/bin/ctester -verbose

# Test specific agent types with deterministic ordering
docker exec -it pentagi /opt/pentagi/bin/ctester -agents simple,primary_agent,pentester -groups basic,knowledge -verbose

# Generate a report file inside the container
docker exec -it pentagi /opt/pentagi/bin/ctester -report /opt/pentagi/data/agent-test-report.md

# Access the report from the host
docker cp pentagi:/opt/pentagi/data/agent-test-report.md ./

Command-line Options

The utility accepts several options:

-env <path> - Path to environment file (default: .env)
-type <provider> - Provider type: custom, openai, anthropic, ollama, bedrock, gemini (default: custom)
-config <path> - Path to custom provider config (default: from LLM_SERVER_CONFIG_PATH env variable)
-tests <path> - Path to custom tests YAML file (optional)
-report <path> - Path to write the report file (optional)
-agents <list> - Comma-separated list of agent types to test (default: all)
-groups <list> - Comma-separated list of test groups to run (default: all)
-verbose - Enable verbose output with detailed test results for each agent

Available Agent Types

Agents are tested in the following deterministic order:

simple - Basic completion tasks
simple_json - JSON-structured responses
primary_agent - Main reasoning agent
assistant - Interactive assistant mode
generator - Content generation
refiner - Content refinement and improvement
adviser - Expert advice and consultation
reflector - Self-reflection and analysis
searcher - Information gathering and search
enricher - Data enrichment and expansion
coder - Code generation and analysis
installer - Installation and setup tasks
pentester - Penetration testing and security assessment

Available Test Groups

basic - Fundamental completion and prompt response tests
advanced - Complex reasoning and function calling tests
json - JSON format validation and structure tests (specifically designed for simple_json agent)
knowledge - Domain-specific cybersecurity and penetration testing knowledge tests

Note: The json test group is specifically designed for the simple_json agent type, while all other agents are tested with basic, advanced, and knowledge groups. This specialization ensures optimal testing coverage for each agent's intended purpose.

Example Provider Configuration

Provider configuration defines which models to use for different agent types:

simple:
  model: "provider/model-name"
  temperature: 0.7
  top_p: 0.95
  n: 1
  max_tokens: 4000

simple_json:
  model: "provider/model-name"
  temperature: 0.7
  top_p: 1.0
  n: 1
  max_tokens: 4000
  json: true

# ... other agent types ...

Optimization Workflow

Create a baseline: Run tests with default configuration to establish benchmark performance
Analyze agent-specific performance: Review the deterministic agent ordering to identify underperforming agents
Test specialized configurations: Experiment with different models for each agent type using provider-specific configs
Focus on domain knowledge: Pay special attention to knowledge group tests for cybersecurity expertise
Validate function calling: Ensure tool-based tests pass consistently for critical agent types
Compare results: Look for the best success rate and performance across all test groups
Deploy optimal configuration: Use in production with your optimized setup

This tool helps ensure your AI agents are using the most effective models for their specific tasks, improving reliability while optimizing costs.

Embedding Configuration and Testing

PentAGI uses vector embeddings for semantic search, knowledge storage, and memory management. The system supports multiple embedding providers that can be configured according to your needs and preferences.

Supported Embedding Providers

PentAGI supports the following embedding providers:

OpenAI (default): Uses OpenAI's text embedding models
Ollama: Local embedding model through Ollama
Mistral: Mistral AI's embedding models
Jina: Jina AI's embedding service
HuggingFace: Models from HuggingFace
GoogleAI: Google's embedding models
VoyageAI: VoyageAI's embedding models

OpenAI-compatible third parties: any provider exposing OpenAI's /embeddings API can be plugged in via EMBEDDING_PROVIDER=openai with a custom EMBEDDING_URL. For example, Qwen DashScope offers text-embedding-v4 through the /compatible-mode/v1 endpoint (International and Chinese Mainland regions only — the US region does not expose embeddings). See the Qwen Alternative Integrations subsection for the full configuration snippet.

Embedding Provider Configuration (click to expand)

Environment Variables

To configure the embedding provider, set the following environment variables in your .env file:

# Primary embedding configuration
EMBEDDING_PROVIDER=openai       # Provider type (openai, ollama, mistral, jina, huggingface, googleai, voyageai)
EMBEDDING_MODEL=text-embedding-3-small  # Model name to use
EMBEDDING_URL=                  # Optional custom API endpoint
EMBEDDING_KEY=                  # API key for the provider (if required)
EMBEDDING_BATCH_SIZE=100        # Number of documents to process in a batch
EMBEDDING_STRIP_NEW_LINES=true  # Whether to remove new lines from text before embedding
EMBEDDING_MAX_TEXT_BYTES=8192   # Max bytes of text sent to embedding model per document (byte proxy for token limit)

# Advanced settings
PROXY_URL=                      # Optional proxy for all API calls
HTTP_CLIENT_TIMEOUT=600         # Timeout in seconds for external API calls (default: 600, 0 = no timeout)
TERMINAL_TOOL_TIMEOUT=1200      # Default timeout in seconds for terminal tool commands when timeout=0 or negative (range: 1–10800; values <= 0 or above 10800 are clamped to 10800 = 3 hours)

# SSL/TLS Certificate Configuration (for external communication with LLM backends and tool servers)
EXTERNAL_SSL_CA_PATH=           # Path to custom CA certificate file (PEM format) inside the container
                                # Must point to /opt/pentagi/ssl/ directory (e.g., /opt/pentagi/ssl/ca-bundle.pem)
EXTERNAL_SSL_INSECURE=false     # Skip certificate verification (use only for testing)

How to Add Custom CA Certificates (click to expand)

If you see this error: tls: failed to verify certificate: x509: certificate signed by unknown authority

Step 1: Get your CA certificate bundle in PEM format (can contain multiple certificates)

Step 2: Place the file in the SSL directory on your host machine:

# Default location (if PENTAGI_SSL_DIR is not set)
cp ca-bundle.pem ./pentagi-ssl/

# Or custom location (if using PENTAGI_SSL_DIR in docker-compose.yml)
cp ca-bundle.pem /path/to/your/ssl/dir/

Step 3: Set the path in .env file (path must be inside the container):

# The volume pentagi-ssl is mounted to /opt/pentagi/ssl inside the container
EXTERNAL_SSL_CA_PATH=/opt/pentagi/ssl/ca-bundle.pem
EXTERNAL_SSL_INSECURE=false

Step 4: Restart PentAGI:

docker compose restart pentagi

Notes:

The pentagi-ssl volume is mounted to /opt/pentagi/ssl inside the container
You can change host directory using PENTAGI_SSL_DIR variable in docker-compose.yml
File supports multiple certificates and intermediate CAs in one PEM file
Use EXTERNAL_SSL_INSECURE=true only for testing (not recommended for production)

Provider-Specific Limitations

Each provider has specific limitations and supported features:

OpenAI: Supports all configuration options
Ollama: Does not support EMBEDDING_KEY as it uses local models
Mistral: Does not support EMBEDDING_MODEL or custom HTTP client
Jina: Does not support custom HTTP client
HuggingFace: Requires EMBEDDING_KEY and supports all other options
GoogleAI: Does not support EMBEDDING_URL, requires EMBEDDING_KEY
VoyageAI: Supports all configuration options

If EMBEDDING_URL and EMBEDDING_KEY are not specified, the system will attempt to use the corresponding LLM provider settings (e.g., OPEN_AI_KEY when EMBEDDING_PROVIDER=openai).

Why Consistent Embedding Providers Matter

It's crucial to use the same embedding provider consistently because:

Vector Compatibility: Different providers produce vectors with different dimensions and mathematical properties
Semantic Consistency: Changing providers can break semantic similarity between previously embedded documents
Memory Corruption: Mixed embeddings can lead to poor search results and broken knowledge base functionality

If you change your embedding provider, you should flush and reindex your entire knowledge base (see etester utility below).

Embedding Tester Utility (etester)

PentAGI includes a specialized etester utility for testing, managing, and debugging embedding functionality. This tool is essential for diagnosing and resolving issues related to vector embeddings and knowledge storage.

Etester Commands (click to expand)

# Test embedding provider and database connection
cd backend
go run cmd/etester/main.go test -verbose

# Show statistics about the embedding database
go run cmd/etester/main.go info

# Delete all documents from the embedding database (use with caution!)
go run cmd/etester/main.go flush

# Recalculate embeddings for all documents (after changing provider)
go run cmd/etester/main.go reindex

# Search for documents in the embedding database
go run cmd/etester/main.go search -query "How to install PostgreSQL" -limit 5

Using Docker

If you're running PentAGI in Docker, you can use etester from within the container:

# Test embedding provider
docker exec -it pentagi /opt/pentagi/bin/etester test

# Show detailed database information
docker exec -it pentagi /opt/pentagi/bin/etester info -verbose

Advanced Search Options

The search command supports various filters to narrow down results:

# Filter by document type
docker exec -it pentagi /opt/pentagi/bin/etester search -query "Security vulnerability" -doc_type guide -threshold 0.8

# Filter by flow ID
docker exec -it pentagi /opt/pentagi/bin/etester search -query "Code examples" -doc_type code -flow_id 42

# All available search options
docker exec -it pentagi /opt/pentagi/bin/etester search -help

Available search parameters:

-query STRING: Search query text (required)
-doc_type STRING: Filter by document type (answer, memory, guide, code)
-flow_id NUMBER: Filter by flow ID (positive number)
-answer_type STRING: Filter by answer type (guide, vulnerability, code, tool, other)
-guide_type STRING: Filter by guide type (install, configure, use, pentest, development, other)
-limit NUMBER: Maximum number of results (default: 3)
-threshold NUMBER: Similarity threshold (0.0-1.0, default: 0.7)

Memory Lifecycle Across Flows

PentAGI stores several kinds of vector documents, and they serve different purposes:

memory captures flow-specific execution history such as tool results and agent observations
guide, answer, and code are intended for reusable knowledge that can help future runs

If you want to inspect what happened in one engagement, search the vector store with the related flow_id. If you want knowledge to survive beyond a single run, store the durable result explicitly as a guide, answer, or code document instead of relying on execution memory alone.

For example, if a target has recurring setup notes, authentication quirks, or target-specific testing methodology, instruct the agent to save that information as a guide and search for it at the beginning of the next engagement. This is the safest current workflow when you want a new flow to start with reusable context.

Flow deletion removes the flow from normal queries through PentAGI's soft-delete mechanism, so reusable knowledge should be treated as a separate concern from per-flow execution history. If you enable the optional Graphiti knowledge graph described earlier in this README, treat its current search context as scoped to the active flow or engagement unless you explicitly build a separate cross-flow reuse workflow.

Common Troubleshooting Scenarios

After changing embedding provider: Always run flush or reindex to ensure consistency
Poor search results: Try adjusting the similarity threshold or check if embeddings are correctly generated
Database connection issues: Verify PostgreSQL is running with pgvector extension installed
Missing API keys: Check environment variables for your chosen embedding provider

Troubleshooting: Flow Stalls or Hangs Without Progress

If a flow starts but then appears to wait indefinitely with no subtasks progressing, a common cause is an embedding provider that is misconfigured or unreachable. PentAGI uses the embedding provider to store and search vector memory while a flow runs, so embedding calls that fail or hang can leave a flow waiting instead of advancing.

1. Check the container logs first. Embedding errors surface in the PentAGI logs:

docker logs pentagi

Look for embedding-related failures such as authentication errors (401/403), wrong-model or not-found errors (404), connection timeouts, or TLS certificate errors. These point at the embedding provider configuration rather than at the flow itself.

2. Validate the provider with etester. The Embedding Tester Utility (etester) checks both the embedding provider and the database connection without starting a flow:

docker exec -it pentagi /opt/pentagi/bin/etester test -verbose

A failing test confirms the problem is in the embedding configuration rather than in the flow.

3. Verify the configuration. Check the following in your .env file against the Supported Embedding Providers list and each provider's documented limitations:

EMBEDDING_PROVIDER is one of the supported providers (default openai).
EMBEDDING_MODEL is a valid model name for that provider.
EMBEDDING_URL and EMBEDDING_KEY are correct for the provider. If both are left empty, PentAGI falls back to the matching LLM provider settings (for example OPEN_AI_KEY and OPEN_AI_SERVER_URL when EMBEDDING_PROVIDER=openai), so a missing or wrong key there can break embeddings too.
The endpoint is reachable from inside the container. If outbound calls go through a proxy, confirm PROXY_URL is set; if calls hang rather than fail quickly, HTTP_CLIENT_TIMEOUT controls how long PentAGI waits on the provider before giving up.

Changing provider? If you switch embedding providers after data has already been indexed, run flush or reindex with etester so old and new vectors are not mixed. See Why Consistent Embedding Providers Matter above.

Function Testing with ftester

PentAGI includes a versatile utility called ftester for debugging, testing, and developing specific functions and AI agent behaviors. While ctester focuses on testing LLM model capabilities, ftester allows you to directly invoke individual system functions and AI agent components with precise control over execution context.

Key Features

Direct Function Access: Test individual functions without running the entire system
Mock Mode: Test functions without a live PentAGI deployment using built-in mocks
Interactive Input: Fill function arguments interactively for exploratory testing
Detailed Output: Color-coded terminal output with formatted responses and errors
Context-Aware Testing: Debug AI agents within the context of specific flows, tasks, and subtasks
Observability Integration: All function calls are logged to Langfuse and Observability stack

Usage Modes

Command Line Arguments

Run ftester with specific function and arguments directly from the command line:

# Basic usage with mock mode
cd backend
go run cmd/ftester/main.go [function_name] -[arg1] [value1] -[arg2] [value2]

# Example: Test terminal command in mock mode
go run cmd/ftester/main.go terminal -command "ls -la" -message "List files"

# Using a real flow context
go run cmd/ftester/main.go -flow 123 terminal -command "whoami" -message "Check user"

# Testing AI agent in specific task/subtask context
go run cmd/ftester/main.go -flow 123 -task 456 -subtask 789 pentester -message "Find vulnerabilities"

Interactive Mode

Run ftester without arguments for a guided interactive experience:

# Start interactive mode
go run cmd/ftester/main.go [function_name]

# For example, to interactively fill browser tool arguments
go run cmd/ftester/main.go browser

Available Functions (click to expand)

Environment Functions

terminal: Execute commands in a container and return the output
file: Perform file operations (read, write, list) in a container

Search Functions

browser: Access websites and capture screenshots
web_search: Unified search orchestrator that agents actually call — pass a query and a mode (links, answer, research, exploit) and it auto-selects, retries, and falls back across the engines below, so you never name an engine explicitly
google: Search the web using Google Custom Search
duckduckgo: Search the web using DuckDuckGo
tavily: Search using Tavily AI search engine
firecrawl: Search using Firecrawl with main-content markdown scraping
traversaal: Search using Traversaal AI search engine
perplexity: Search using Perplexity AI
sploitus: Search for security exploits, vulnerabilities (CVEs), and pentesting tools
searxng: Search using Searxng meta search engine (aggregates results from multiple engines)
internal (ftester-only debug function, not an agent tool): Opt-in browser-analytics fallback engine that discovers links, scrapes each page, and summarizes the result; requires WEB_SEARCH_INTERNAL_ENABLED=true, a configured scraper, and at least one available link engine

Vector Database Functions

search_in_memory: Search for information in vector database
search_guide: Find guidance documents in vector database
search_answer: Find answers to questions in vector database
search_code: Find code examples in vector database

AI Agent Functions

advice: Get expert advice from an AI agent
coder: Request code generation or modification
maintenance: Run system maintenance tasks
memorist: Store and organize information in vector database
pentester: Perform security tests and vulnerability analysis
search: Complex search across multiple sources

Utility Functions

describe: Show information about flows, tasks, and subtasks

Debugging Flow Context (click to expand)

The describe function provides detailed information about tasks and subtasks within a flow. This is particularly useful for diagnosing issues when PentAGI encounters problems or gets stuck.

# List all flows in the system
go run cmd/ftester/main.go describe

# Show all tasks and subtasks for a specific flow
go run cmd/ftester/main.go -flow 123 describe

# Show detailed information for a specific task
go run cmd/ftester/main.go -flow 123 -task 456 describe

# Show detailed information for a specific subtask
go run cmd/ftester/main.go -flow 123 -task 456 -subtask 789 describe

# Show verbose output with full descriptions and results
go run cmd/ftester/main.go -flow 123 describe -verbose

This function allows you to identify the exact point where a flow might be stuck and resume processing by directly invoking the appropriate agent function.

Function Help and Discovery (click to expand)

Each function has a help mode that shows available parameters:

# Get help for a specific function
go run cmd/ftester/main.go [function_name] -help

# Examples:
go run cmd/ftester/main.go terminal -help
go run cmd/ftester/main.go browser -help
go run cmd/ftester/main.go describe -help

You can also run ftester without arguments to see a list of all available functions:

go run cmd/ftester/main.go

Output Format (click to expand)

The ftester utility uses color-coded output to make interpretation easier:

Blue headers: Section titles and key names
Cyan [INFO]: General information messages
Green [SUCCESS]: Successful operations
Red [ERROR]: Error messages
Yellow [WARNING]: Warning messages
Yellow [MOCK]: Indicates mock mode operation
Magenta values: Function arguments and results

JSON and Markdown responses are automatically formatted for readability.

Advanced Usage Scenarios (click to expand)

Debugging Stuck AI Flows

When PentAGI gets stuck in a flow:

Pause the flow through the UI
Use describe to identify the current task and subtask
Directly invoke the agent function with the same task/subtask IDs
Examine the detailed output to identify the issue
Resume the flow or manually intervene as needed

Testing Environment Variables

Verify that API keys and external services are configured correctly:

# Test Google search API configuration
go run cmd/ftester/main.go google -query "pentesting tools"

# Test browser access to external websites
go run cmd/ftester/main.go browser -url "https://example.com"

Developing New AI Agent Behaviors

When developing new prompt templates or agent behaviors:

Create a test flow in the UI
Use ftester to directly invoke the agent with different prompts
Observe responses and adjust prompts accordingly
Check Langfuse for detailed traces of all function calls

Verifying Docker Container Setup

Ensure containers are properly configured:

go run cmd/ftester/main.go -flow 123 terminal -command "env | grep -i proxy" -message "Check proxy settings"

Docker Container Usage (click to expand)

If you have PentAGI running in Docker, you can use ftester from within the container:

# Run ftester inside the running PentAGI container
docker exec -it pentagi /opt/pentagi/bin/ftester [arguments]

# Examples:
docker exec -it pentagi /opt/pentagi/bin/ftester -flow 123 describe
docker exec -it pentagi /opt/pentagi/bin/ftester -flow 123 terminal -command "ps aux" -message "List processes"

This is particularly useful for production deployments where you don't have a local development environment.

Integration with Observability Tools (click to expand)

All function calls made through ftester are logged to:

Langfuse: Captures the entire AI agent interaction chain, including prompts, responses, and function calls
OpenTelemetry: Records metrics, traces, and logs for system performance analysis
Terminal Output: Provides immediate feedback on function execution

To access detailed logs:

Check Langfuse UI for AI agent traces (typically at http://localhost:4000)
Use Grafana dashboards for system metrics (typically at http://localhost:3000)
Examine terminal output for immediate function results and errors

Command-line Options

The main utility accepts several options:

-env <path> - Path to environment file (optional, default: .env)
-provider <type> - Provider type to use (default: custom, options: openai, anthropic, gemini, bedrock, ollama, deepseek, glm, kimi, qwen, minimax, custom)
-flow <id> - Flow ID for testing functions that require it (0 means using mocks, default: 0)
-user <id> - User ID for testing functions that require it (default: 0; 1 is the default admin user)
-task <id> - Task ID for agent context (optional)
-subtask <id> - Subtask ID for agent context (optional)

Function-specific arguments are passed after the function name using -name value format.

Pentesting Prompt Methodology

When refining prompts for offensive security work, give the agent a clear methodology instead of a flat list of payloads:

Start with explicit scope, authorization, and success criteria
Map the application first: roles, routes, parameters, uploads, integrations, and trust boundaries
Prioritize attack surfaces systematically instead of testing everything at once
Validate findings with reproducible evidence before escalating to deeper exploitation
Finish with report-ready notes that capture impact, prerequisites, and next steps

For PentAGI-specific prompt guidance, see backend/docs/prompt_engineering_pentagi.md. For a practical starting point, reuse and adapt examples/prompts/base_web_pentest.md to match the target application, technology stack, and engagement scope.

Building

Building Docker Image

The Docker build process automatically embeds version information from git tags. To properly version your build, use the provided scripts:

Linux/macOS

# Load version variables
source ./scripts/version.sh

# Standard build
docker build \
  --build-arg PACKAGE_VER=$PACKAGE_VER \
  --build-arg PACKAGE_REV=$PACKAGE_REV \
  -t pentagi:$PACKAGE_VER .

# Multi-platform build
docker buildx build \
  --platform linux/amd64,linux/arm64 \
  --build-arg PACKAGE_VER=$PACKAGE_VER \
  --build-arg PACKAGE_REV=$PACKAGE_REV \
  -t pentagi:$PACKAGE_VER .

# Build and push
docker buildx build \
  --platform linux/amd64,linux/arm64 \
  --build-arg PACKAGE_VER=$PACKAGE_VER \
  --build-arg PACKAGE_REV=$PACKAGE_REV \
  -t myregistry/pentagi:$PACKAGE_VER \
  --push .

Windows (PowerShell)

# Load version variables
. .\scripts\version.ps1

# Standard build
docker build `
  --build-arg PACKAGE_VER=$env:PACKAGE_VER `
  --build-arg PACKAGE_REV=$env:PACKAGE_REV `
  -t pentagi:$env:PACKAGE_VER .

# Multi-platform build
docker buildx build `
  --platform linux/amd64,linux/arm64 `
  --build-arg PACKAGE_VER=$env:PACKAGE_VER `
  --build-arg PACKAGE_REV=$env:PACKAGE_REV `
  -t pentagi:$env:PACKAGE_VER .

Quick build without version

For development builds without version tracking:

docker build -t pentagi:dev .

Note

The build scripts automatically determine version from git tags
Release builds (on tag commit) have no revision suffix
Development builds (after tag) include commit hash as revision (e.g., 1.1.0-bc6e800)
To use the built image locally, update the image name in docker-compose.yml or use the build option

Credits

This project is made possible thanks to the following research and developments:

Emerging Architectures for LLM Applications
A Survey of Autonomous LLM Agents
Codel by Andriy Semenets - initial architectural inspiration for agent-based automation

License

PentAGI is licensed under the MIT License.

Third-Party Dependencies

All third-party dependencies use MIT-compatible licenses. See licenses/ directory for detailed license reports.

VXControl Cloud Services

⚠️ Note: While the VXControl Cloud SDK code is MIT licensed, accessing VXControl Cloud Services (threat intelligence, AI support, premium features) requires a separate License Key and compliance with Terms of Service.

The SDK code itself is free to use - service access requires registration.

For questions contact: info@pentagi.com or info@vxcontrol.com

dstotijn/hetty

An HTTP toolkit for security research.

https://hetty.xyz

Hetty is an HTTP toolkit for security research. It aims to become an open source alternative to commercial software like Burp Suite Pro, with powerful features tailored to the needs of the infosec and bug bounty community.

Features

Machine-in-the-middle (MITM) HTTP proxy, with logs and advanced search
HTTP client for manually creating/editing requests, and replay proxied requests
Intercept requests and responses for manual review (edit, send/receive, cancel)
Scope support, to help keep work organized
Easy-to-use web based admin interface
Project based database storage, to help keep work organized

👷‍♂️ Hetty is under active development. Check the backlog for the current status.

📣 Are you pen testing professionally in a team? I would love to hear your thoughts on tooling via this 5 minute survey. Thank you!

Getting started

💡 The Getting started doc has more detailed install and usage instructions.

Installation

The quickest way to install and update Hetty is via a package manager:

macOS

brew install hettysoft/tap/hetty

Linux

sudo snap install hetty

Windows

scoop bucket add hettysoft https://github.com/hettysoft/scoop-bucket.git
scoop install hettysoft/hetty

Other

Alternatively, you can download the latest release from GitHub for your OS and architecture, and move the binary to a directory in your $PATH. If your OS is not available for one of the package managers or not listed in the GitHub releases, you can compile from source (link coming soon).

Docker

Docker images are distributed via GitHub's Container registry and Docker Hub. To run Hetty via with a volume for database and certificate storage, and port 8080 forwarded:

docker run -v $HOME/.hetty:/root/.hetty -p 8080:8080 \
  ghcr.io/dstotijn/hetty:latest

Usage

Once installed, start Hetty via:

hetty

💡 Read the Getting started doc for more details.

To list all available options, run: hetty --help:

$ hetty --help

Usage:
    hetty [flags] [subcommand] [flags]

Runs an HTTP server with (MITM) proxy, GraphQL service, and a web based admin interface.

Options:
    --cert         Path to root CA certificate. Creates file if it doesn't exist. (Default: "~/.hetty/hetty_cert.pem")
    --key          Path to root CA private key. Creates file if it doesn't exist. (Default: "~/.hetty/hetty_key.pem")
    --db           Database file path. Creates file if it doesn't exist. (Default: "~/.hetty/hetty.db")
    --addr         TCP address for HTTP server to listen on, in the form \"host:port\". (Default: ":8080")
    --chrome       Launch Chrome with proxy settings applied and certificate errors ignored. (Default: false)
    --verbose      Enable verbose logging.
    --json         Encode logs as JSON, instead of pretty/human readable output.
    --version, -v  Output version.
    --help, -h     Output this usage text.

Subcommands:
    - cert  Certificate management

Run `hetty <subcommand> --help` for subcommand specific usage instructions.

Visit https://hetty.xyz to learn more about Hetty.

Documentation

📖 Read the docs

Support

Use issues for bug reports and feature requests, and discussions for questions and troubleshooting.

Community

💬 Join the Hetty Discord server

Contributing

Want to contribute? Great! Please check the Contribution Guidelines for details.

Acknowledgements

Thanks to the Hacker101 community on Discord for the encouragement and early feedback.
The font used in the logo and admin interface is JetBrains Mono.

License

MIT

rorkai/App-Store-Connect-CLI

Fast, scriptable CLI for the App Store Connect API. Automate TestFlight, builds, submissions, signing, analytics, screenshots, subscriptions, and more

https://asccli.sh

App Store Connect CLI

A fast, lightweight, and scriptable CLI for the App Store Connect API. Automate iOS, macOS, tvOS, and visionOS release workflows from your terminal, IDE, or CI/CD pipeline.

asc skills

Agent Skills for automating asc workflows including builds, TestFlight, metadata sync, submissions, and signing: https://github.com/rorkai/app-store-connect-cli-skills

Install them globally so they are available across projects:

asc install-skills

asc install-skills checks out reviewed commit f52c4f04323bb2dfb21ca8be82e6494e9cd0b4d8 and copies its 25 skills directly into the standard global agent-skills directory. It verifies the complete pack and every installed file before succeeding, preserves unrelated skills and unrelated lock entries, and pins the 25 ASC lock entries to the same reviewed commit so external checks cannot update them from a mutable branch. It rolls back the pack if any replacement fails. Only git is required; the command does not execute Node.js, npx, an npm package, or repository scripts.

git --version
asc install-skills

Quick Start

If you want to confirm the binary works before configuring authentication:

asc version
asc --help

1. Install

# Homebrew (recommended)
brew install asc

# Install script (macOS/Linux)
curl -fsSL https://asccli.sh/install | bash

# Windows (WinGet, once the package is accepted)
winget install asc

# Exact fallback when scripting
winget install --id Rorkai.ASC --exact

The WinGet package is tracked in GitHub Discussion #1552. Until it appears in winget search asc, Windows users can download the signed release binaries directly from the GitHub releases page.

For source builds and contributor setup, see CONTRIBUTING.md. Released binaries are self-contained and do not require a Go installation; source builds use the toolchain version declared by go.mod.

2. Authenticate

asc auth login \
  --name "MyApp" \
  --key-id "ABC123" \
  --issuer-id "DEF456" \
  --private-key /path/to/AuthKey.p8 \
  --network

Individual API keys have no issuer ID. Omit --issuer-id and pass --key-type individual:

asc auth login \
  --name "MyIndividualKey" \
  --key-id "ABC123" \
  --key-type individual \
  --private-key /path/to/AuthKey.p8

Generate API keys at: https://appstoreconnect.apple.com/access/integrations/api

If you are running in CI, a headless shell, or a machine where keychain access is not available, use config-backed auth instead:

asc auth login \
  --bypass-keychain \
  --name "MyCIKey" \
  --key-id "ABC123" \
  --issuer-id "DEF456" \
  --private-key /path/to/AuthKey.p8

3. Validate auth

asc auth status --validate
asc auth doctor

4. First command

asc apps list --output table
asc apps list --output json --pretty

Output defaults (TTY-aware)

asc chooses a default --output based on where stdout is connected:

Interactive terminal (TTY): table
Non-interactive output (pipes/files/CI): json

You can still set a global preference:

export ASC_DEFAULT_OUTPUT=markdown

And explicit flags always win:

asc apps list --output json

Compatibility

Commands are supported as documented. Deprecation warnings identify the available migration path and the command's long-term replacement.

Troubleshooting

Homebrew

Refresh Homebrew first: brew update && brew upgrade asc
Check which binary you are running: which asc
Confirm the installed version: asc version
If Homebrew is behind the latest GitHub release, use the install script from https://asccli.sh/install

WinGet

Refresh WinGet sources first: winget source update
Prefer the short install once available: winget install asc
If the short name ever becomes ambiguous, use the package identifier: winget install --id Rorkai.ASC --exact
Confirm the installed command resolves: Get-Command asc and asc version

Authentication

Validate the active profile: asc auth status --validate
Run the auth health check: asc auth doctor
If keychain access is blocked, retry with ASC_BYPASS_KEYCHAIN=1 or re-run asc auth login --bypass-keychain
Use asc auth login --local --bypass-keychain ... when you want repo-local credentials in ./.asc/config.json

Apple service health

Check Apple's developer services without credentials: asc system-status
Narrow unexpected API or upload failures: asc system-status --service "App Store Connect"
Poll only when requested: asc system-status --watch --poll-interval 30s
Use --issues-only for a concise incident view; summary counts still cover all matched services

Output

asc defaults to table in an interactive terminal and json in pipes, files, and CI
Use an explicit format when scripting or sharing repro steps: --output json, --output table, or --output markdown
Use --pretty with JSON when you want readable output in terminals or bug reports
Set a personal default with ASC_DEFAULT_OUTPUT, but remember --output always wins

Privacy and telemetry

asc sends pseudonymous command-level usage telemetry by default to help maintainers understand which commands are used and where reliability work is needed. Local events include a random installation ID, which lets events from one installation be grouped over time; it is not derived from an Apple account or machine identifier.

Telemetry includes the CLI version, operating system and architecture, registered command path, duration, runtime context, invocation source, a bounded outcome class, and the HTTP status when an API request fails. It may include a sanitized public flag name. It does not include raw arguments, stderr, error messages, flag values, response bodies, credentials, private keys, Apple account, team, or issuer IDs, app or bundle IDs, usernames, hostnames, repository names, or file paths.

Review or change telemetry at any time:

asc telemetry status
asc telemetry disable
asc telemetry reset-id

ASC_TELEMETRY_DISABLED=1 and DO_NOT_TRACK=1 also disable telemetry. See the telemetry reference for the exact event payload, runtime handling, collector endpoint, and all controls.

Support

Use GitHub Discussions for install help, authentication setup, workflow advice, and "how do I...?" questions
Use GitHub Issues for reproducible bugs and concrete feature requests
See SUPPORT.md for the support policy and bug-report checklist
Before filing an auth or API bug, retry with ASC_BYPASS_KEYCHAIN=1; if it is safe to do so, include redacted output from ASC_DEBUG=api asc ... or asc --api-debug ...

Wall of Apps

See the Wall of Apps →

Want to add yours? asc apps wall submit --app "1234567890" --confirm

The command uses your authenticated gh session to fork the repo and open a pull request that updates docs/wall-of-apps.json. It resolves the public App Store name, URL, and icon from the app ID automatically. For manual entries that are not on the public App Store yet, use --link with --name. Use asc apps wall submit --dry-run to preview the fork, branch, and PR plan before creating anything.

Common Workflows

TestFlight feedback and crashes

asc testflight feedback list --app "123456789" --paginate
asc testflight crashes list --app "123456789" --sort -createdDate --limit 10
asc testflight crashes log --submission-id "SUBMISSION_ID"

Builds and distribution

asc builds upload --app "123456789" --ipa "/path/to/MyApp.ipa"
asc builds list --app "123456789" --output table
asc testflight groups list --app "123456789" --output table

For macOS TestFlight distribution, upload the exported .pkg first, then add the processed build to a beta group:

asc builds upload --app "123456789" --pkg "./build/MyMacApp.pkg" --version "1.2.3" --build-number "42" --wait --output json
asc builds add-groups --app "123456789" --build-number "42" --version "1.2.3" --platform MAC_OS --group "Internal Testers"

--app is the App Store Connect app ID. If you use local Xcode build flags such as --archive-path, also pass exactly one of --workspace or --project plus --scheme; otherwise use a pre-exported .ipa or .pkg upload. Add --submit --confirm to asc builds add-groups when distributing to an external TestFlight group that needs beta app review submission.

Release (high-level App Store publish flow)

# Optional: preview the staging plan before submission
asc release stage --app "123456789" --version "1.2.3" --build-id "BUILD_ID" --copy-metadata-from "1.2.2" --dry-run

# Canonical upload + attach + submit command
asc publish appstore --app "123456789" --ipa "/path/to/MyApp.ipa" --version "1.2.3" --submit --confirm

# Monitor status after submission
asc status --app "123456789" --watch

Lower-level submission lifecycle commands (for debugging or partial workflows):

# Canonical readiness check
asc validate --app "123456789" --version "1.2.3"
asc submit status --version-id "VERSION_ID"
asc submit cancel --version-id "VERSION_ID" --confirm

Readiness validation also warns when localized app names, subtitles, descriptions, keywords, promotional text, or What's New copy still contains an unmistakable template marker such as Lorem ipsum, TODO, TBD, or FIXME. Lorem ipsum matches in any letter case. TODO, TBD, and FIXME match only in uppercase because their lowercase spellings can be ordinary product wording. The warning includes the locale, field, matched text, resource ID, and a remediation step. It is advisory by default and becomes blocking only with --strict:

asc validate --app "123456789" --version "1.2.3" --output json
asc validate --app "123456789" --version "1.2.3" --strict

Add the --deep mode when a release needs checks that Apple exposes only through its signed-in web app:

asc web auth login --apple-id "user@example.com"
asc validate --app "123456789" --version "1.2.3" --deep

Deep validation reuses the file-backed cache without opening a login, Keychain, password, or 2FA prompt. It checks App Privacy publication, relevant agreements, and the first auto-renewable subscription attachment; availability and required App Review fields still come from the public API. Paid-agreement relevance also uses the app's current public price so an upfront-paid app isn't mistaken for a free one. The private Apple endpoints can change without notice, so an unavailable or changed response is unverified, not a false blocker. Add --strict if CI must fail when a requested deep check can't be verified.

This lint intentionally does not judge platform names, roadmap language, or beta/demo wording because those phrases can be legitimate product copy and cannot be classified reliably offline. It also leaves shorter Lorem Ipsum product wording and ordinary localized TODO copy without marker punctuation unflagged; only template-like residue is reported.

Review status and blockers

asc review status --app "123456789"
asc review doctor --app "123456789"

Metadata and localization

asc localizations list --app "123456789" --type app-info
asc metadata init --dir "./metadata" --version "1.2.3" --locale "en-US"
asc metadata apply --app "123456789" --version "1.2.3" --dir "./metadata" --dry-run
asc metadata keywords audit --app "123456789" --version "1.2.3" --blocked-terms-file "./blocked-terms.txt"
asc apps info view --app "123456789" --output json --pretty

Use asc metadata keywords audit before sync or apply when you want an ASO-focused review of live keyword metadata across locales. It reports duplicate phrases, repeated terms across locales, overlap with localized app name or subtitle, byte-budget usage, and optional blocked terms from repeated --blocked-term flags or a text file.

Screenshots and media

asc screenshots plan --app "123456789" --version "1.2.3" --review-output-dir "./screenshots/review"
asc screenshots apply --app "123456789" --version "1.2.3" --review-output-dir "./screenshots/review" --confirm
asc screenshots list --version-localization "VERSION_LOCALIZATION_ID"
asc video-previews list --app "123456789"

Uploading screenshots for a single locale:

asc apps list
asc versions list --app "APP_ID"
asc localizations list --version "VERSION_ID" --output json --locale "en-US" | jsonpp
asc screenshots upload --version-localization "VERSION_LOCALIZATION_ID" --path "./screenshots/en-US" --device-type "IPHONE_65" --replace --max-screenshots 10

VERSION_LOCALIZATION_ID is the App Store version localization resource ID from data[].id, not the locale code from attributes.locale.

For local capture coverage across multiple devices, locales, appearances, and content fixtures, use a matrix plan. Targets must already be booted simulators; the command writes raw artifacts and an offline review report, without uploading to App Store Connect:

asc screenshots matrix --plan .asc/screenshots-matrix.json --max-concurrency 2 --output json --pretty

See docs/design/screenshots-matrix.md for the JSONC schema, isolated output layout, retry behavior, and review contract.

Signing and bundle IDs

asc bundle-ids capabilities list --bundle "BUNDLE_ID"
asc signing fetch --bundle-id com.example.app --profile-type IOS_APP_STORE --output .asc/signing
asc signing sync pull --repo git@github.com:team/signing.git --password-file ~/.config/asc/signing-sync-password --output-dir .asc/signing/pulled

signing fetch downloads public certificates and provisioning profiles. A usable signing identity also needs the matching private key; signing sync can verify that local identity and share it through an encrypted Git repository. For multi-target release testing, signing reconcile plans exact device/profile changes. signing run provides a temporary macOS keychain only for single-target archives. Multi-target exports must import the identity into a job-scoped keychain and install every reconciled profile for the job-exclusive macOS user. See the signing guide for setup, CI, rotation, security boundaries, and troubleshooting.

Workflow automation

asc workflow validate --output json
asc workflow run --dry-run testflight_beta VERSION:1.2.3

Verified local Xcode -> TestFlight workflow

See docs/WORKFLOWS.md for local compile validation with asc xcode build and a copyable .asc/deployment.json, .asc/workflow.json, and ExportOptions.plist that use asc builds next-build-number, asc xcode inject, asc xcode archive, asc xcode export --timeout 10m, and asc publish testflight --group ... --wait. Add --submit --confirm when distributing to an external TestFlight group that needs beta app review submission.

The asc xcode test command provides local unit/UI test execution with structured results and preserved .xcresult bundles; see the same workflow guide for an invocation.

asc workflow validate --output json
asc xcode inject --manifest .asc/deployment.json --set version=1.2.3 --set build_number=42 --dry-run --output json
asc xcode build --project App.xcodeproj --scheme App --destination 'platform=iOS Simulator,name=iPhone 17 Pro Max,OS=27.0' --no-code-signing --output json
asc workflow run --dry-run testflight_beta VERSION:1.2.3
asc workflow run testflight_beta VERSION:1.2.3

Replace the example Xcode destination with a simulator installed on the host.

Xcode Cloud workflows and build runs

# Trigger from a pull request
asc xcode-cloud run --workflow-id "WORKFLOW_ID" --pull-request-id "PR_ID"

# Rerun from an existing build run with a clean build
asc xcode-cloud run --source-run-id "BUILD_RUN_ID" --clean

# Fetch a single build run by ID
asc xcode-cloud build-runs get --id "BUILD_RUN_ID"

Apple Ads campaign management

Apple Ads uses separate OAuth credentials from App Store Connect:

asc ads auth login --name "Marketing" --client-id "SEARCHADS_CLIENT_ID" --team-id "SEARCHADS_TEAM_ID" --key-id "KEY_ID" --private-key ./ads-key.pem --ad-account "987654"
asc ads auth discover --output json
asc ads campaigns find --ad-account "987654" --file query.json --output json
asc ads reports apps campaigns --ad-account "987654" --file report.json --output json

See guides/apple-ads-playbooks.mdx for operator playbooks covering credential safety, org inspection, read-only smoke tests, reporting, raw API usage, and guarded mutations.

StoreKit Retention Messaging

Retention Messaging uses a dedicated In-App Purchase API key, separate from App Store Connect API credentials:

asc storekit auth login --name Production --key-id "KEY_ID" --issuer-id "ISSUER_ID" --private-key ./SubscriptionKey.p8 --bundle-id com.example.app
asc storekit auth doctor --environment sandbox --network
asc storekit retention-messaging messages list --environment sandbox --output json
asc storekit retention-messaging endpoint view --environment production

See docs/architecture/storekit-retention-messaging.md for the endpoint map, message and image requirements, environment variables, and the full sandbox verification sequence.

Commands and Reference

Use built-in help as the source of truth:

asc --help
asc <command> --help
asc <command> <subcommand> --help

Reference hierarchy:

asc --help: authoritative command and flag surface
docs/COMMANDS.md: generated top-level taxonomy map
asc docs show workflows: curated workflow recipes
asc docs show reference: repo-local quick reference template used by asc init

For full command families, flags, and discovery patterns, see:

docs/COMMANDS.md

Documentation

docs/CI_CD.md - CI/CD integration guides (GitHub Actions, GitLab, Bitrise, CircleCI)
commands/signing.mdx - signing identities, encrypted sync, CI, and release-testing profiles
docs/COMMANDS.md - Command families and reference navigation
docs/PARITY.md - Remaining parity areas and intentional non-goals
docs/WORKFLOWS.md - Reusable workflow patterns, including local Xcode to TestFlight
guides/apple-ads-playbooks.mdx - Apple Ads operator playbooks
docs/architecture/storekit-retention-messaging.md - Retention Messaging setup and sandbox verification
docs/API_NOTES.md - API quirks and behaviors
docs/CONTRIBUTING.md - CLI development and testing notes
docs/TESTING.md - Testing patterns and conventions
docs/openapi/README.md - Offline OpenAPI snapshot + update flow
CONTRIBUTING.md - Contribution guide

Acknowledgements

Local screenshot framing uses Koubou (pinned to 0.18.1) for deterministic device-frame rendering. GitHub: https://github.com/bitomule/koubou

Simulator UI automation for screenshot capture and interactions uses AXe CLI. GitHub: https://github.com/cameroncooke/AXe

The keyword difficulty methodology used by asc optimize keywords score is adapted from semihcihan's App Store Optimization CLI (MIT licensed). GitHub: https://github.com/semihcihan/App-Store-Optimization-CLI

Contributing

Contributions are welcome. See CONTRIBUTING.md for details.

License

MIT License - see LICENSE for details.

_{This project is an independent, unofficial tool and is not affiliated with, endorsed by, or sponsored by Apple Inc. App Store Connect, TestFlight, Xcode Cloud, and Apple are trademarks of Apple Inc., registered in the U.S. and other countries.}

gtsteffaniak/filebrowser

📂 Web File Browser

https://filebrowserquantum.com

FileBrowser Quantum

The best free self-hosted web-based file manager.

Pinned

📌 Read The Official Docs (currently english-only)

📌 v2.0.0 is now in beta!

About

FileBrowser Quantum provides an easy way to access and manage your files from the web. It has a modern responsive interface that has many advanced features to manage users, access, sharing, and file preview and editing.

This version is called "Quantum" because it packs tons of advanced features into a tiny and easy-to-run file. Unlike the majority of alternative options, FileBrowser Quantum is simple to install and easy to configure.

The goal for this repo is to become the best open-source self-hosted file browsing application that exists -- all for free. This repo will always be free and open-source.

Ready to try it out? See Getting Started Docs.

How its different

FileBrowser Quantum is a massive fork of the file browser open-source project with the following changes:

✅ Better source configuration - multiple sources, include/exclude rules, and more
✅ Login support for OIDC, LDAP, JWT, password + 2FA, and proxy.
✅ Beautiful, Responsive, and Customizable user interface.
✅ Streamlined configuration via config.yaml config file.
✅ Efficient search
- Real-time search results as you type.
- Real-time monitoring and updates in the UI.
- Search supports file and folder sizes, along with various filters.
✅ Better listing browsing
- Thumbnails support includes office, video, and album artwork, and 3D models.
- Faster and more responsive views with animations.
- Folder sizes are displayed and support thumbnails
- Navigating remembers the last scroll position.
- WebDAV support
- Granular permissions
✅ Highly configurable and customizable sharing options
- share expiration time
- users who can access share (including anonymous)
- styling and themes
- file viewing, editing, and uploading permissions
✅ Access control that can be scoped to user or group and source path.
✅ Developer API support
- Ability to create long-lived API Tokens.
- A helpful Swagger page is available at /swagger endpoint for API enabled users.

Notable features that this fork does not have (removed):

❌ shell commands are completely removed and will not be returned.

FileBrowser Quantum differs significantly from the original version. Many of these changes required a significant overhaul. Creating a fork was a necessary process to make the program better. There have been many growing pains, but a stable release is planned and coming soon.

The UI

The UI has a simple three-component navigation system:

(Left) Multi-action button with slide-out panel.
(Middle) The powerful search bar / title
(Right) The view change toggle / overflow menu

All other functions are moved either into the action menu or pop-up menus. If the action does not depend on context, it will exist in the slide-out action panel. If the action is available based on context, it will show up as a pop-up menu.

Official Docs

See the Official Docs. Contributions are welcome and encouraged! See FilebrowserDocs Github.

Comparison Chart

Application Name	Quantum	Filebrowser	Filestash	Nextcloud	Google_Drive	FileRun
Filesystem support	✅	✅	✅	❌	❌	✅
Linux	✅	✅	✅	✅	❌	✅
Windows	✅	✅	✅	❌	❌	✅
Mac	✅	✅	✅	❌	❌	✅
Self hostable	✅	✅	✅	✅	❌	✅
Has Stable Release?	✅	✅	✅	✅	✅	✅
S3 support	❌	❌	✅	✅	❌	❌
webdav support	✅	❌	✅	✅	❌	✅
FTP support	❌	❌	✅	✅	❌	✅
Dedicated docs site?	✅	✅	✅	✅	❌	✅
Multiple sources at once	✅	❌	✅	✅	❌	✅
Docker image size	180 MB (with ffmpeg)	31 MB	240 MB (main image)	250 MB	❌	> 2 GB
Min. Memory Requirements	512 MB	128 MB	128 MB (main image)	512 MB	❌	512 MB
has standalone binary	✅	✅	✅	❌	❌	❌
price	free	free	free	free tier	free tier	$99+
rich media preview	✅	✅	✅	✅	✅	✅
Upload files from the web?	✅	✅	✅	✅	✅	✅
Advanced Search?	✅	❌	✅	configurable	✅	✅
Indexed Search?	✅	❌	✅	configurable	✅	✅
Content-aware search?	❌	❌	✅	configurable	✅	✅
Custom job support	🚧	✅	✅	✅	❌	✅
Multiple users	✅	✅	✅	✅	✅	✅
Single sign-on support	✅	❌	✅	✅	✅	✅
LDAP sign-on support	✅	❌	✅	✅	❌	✅
Long-live API key support	✅	❌	✅	✅	✅	✅
API documentation page	✅	❌	✅	✅	❌	✅
Mobile App	❌	❌	✅	✅	✅	❌
open source?	✅	✅	✅	✅	❌	❌
tags support	🚧	❌	✅	✅	❌	✅
shareable web links?	✅	✅	✅	✅	✅	✅
Event-based notifications	🚧	❌	✅	❌	❌	✅
Metrics	🚧	❌	✅	❌	❌	❌
file space quotas	🚧	❌	✅	❌	✅	✅
text-based files editor	✅	✅	✅	✅	✅	✅
Office file support	✅	❌	✅	✅	✅	✅
Office file previews	✅	❌	❌	✅	✅	✅
Themes	✅	✅	✅	❌	❌	✅
Branding support	✅	✅	✅	❌	❌	✅
activity log	✅	❌	✅	✅	✅	✅
Comments support	❌	❌	✅	✅	✅	✅
trash support	🚧	❌	✅	✅	✅	✅
Starred/pinned files	✅	❌	✅	❌	✅	✅
Chromecast support	❌	❌	✅	❌	❌	❌
Share collections of files	🚧	❌	❌	❌	❌	✅
Can archive selected files	✅	❌	❌	❌	❌	✅
Can browse archive files	🚧	❌	✅	❌	❌	✅
Can convert documents	🚧	❌	✅	❌	❌	✅
Can convert videos	🚧	❌	✅	❌	❌	❌
Can convert photos	🚧	❌	✅	❌	❌	❌

maximhq/bifrost

Fastest enterprise AI gateway (50x faster than LiteLLM) with adaptive load balancer, cluster mode, guardrails, 1000+ models support & <100 µs overhead at 5k RPS.

https://www.getmaxim.ai/bifrost

Bifrost AI Gateway

The fastest way to build AI applications that never go down

Bifrost is a high-performance AI gateway that unifies access to 23+ providers (OpenAI, Anthropic, AWS Bedrock, Google Vertex, and more) through a single OpenAI-compatible API. Deploy in seconds with zero configuration and get automatic failover, load balancing, semantic caching, and enterprise-grade features.

Quick Start

Go from zero to production-ready AI gateway in under a minute.

Step 1: Start Bifrost Gateway

# Install and run locally
npx -y @maximhq/bifrost

# Or use Docker
docker run -p 8080:8080 maximhq/bifrost

Step 2: Configure via Web UI

# Open the built-in web interface
open http://localhost:8080

Step 3: Make your first API call

curl -X POST http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-4o-mini",
    "messages": [{"role": "user", "content": "Hello, Bifrost!"}]
  }'

That's it! Your AI gateway is running with a web interface for visual configuration, real-time monitoring, and analytics.

Complete Setup Guides:

Gateway Setup - HTTP API deployment
Go SDK Setup - Direct integration

Enterprise Deployments

Bifrost supports enterprise-grade, private deployments for teams running production AI systems at scale. In addition to private networking, custom security controls, and governance, enterprise deployments unlock advanced capabilities including adaptive load balancing, clustering, guardrails, MCP gateway, and other features designed for enterprise-grade scale and reliability.

Explore enterprise capabilities

Key Features

Core Infrastructure

Unified Interface - Single OpenAI-compatible API for all providers
Multi-Provider Support - OpenAI, Anthropic, AWS Bedrock, Google Vertex, Azure, Cerebras, Cohere, Mistral, Ollama, Groq, and more
Automatic Fallbacks - Seamless failover between providers and models with zero downtime
Load Balancing - Intelligent request distribution across multiple API keys and providers

Advanced Features

Model Context Protocol (MCP) - Enable AI models to use external tools (filesystem, web search, databases)
Semantic Caching - Intelligent response caching based on semantic similarity to reduce costs and latency
Multimodal Support - Support for text, images, audio, and streaming, all behind a common interface.
Custom Plugins - Extensible middleware architecture for analytics, monitoring, and custom logic
Governance - Usage tracking, rate limiting, and fine-grained access control

Enterprise & Security

Budget Management - Hierarchical cost control with virtual keys, teams, and customer budgets
User Provisioning (OIDC) - OAuth 2.0 / OIDC login with background directory sync for teams, roles, and business units
Observability - Native Prometheus metrics, distributed tracing, and comprehensive logging
Secrets Management - Secure API key management with environment variables and deployment secrets

Developer Experience

Zero-Config Startup - Start immediately with dynamic provider configuration
Drop-in Replacement - Replace OpenAI/Anthropic/GenAI APIs with one line of code
SDK Integrations - Native support for popular AI SDKs with zero code changes
Configuration Flexibility - Web UI, API-driven, or file-based configuration options

Repository Structure

Bifrost uses a modular architecture for maximum flexibility:

bifrost/
├── npx/                 # NPX script for easy installation
├── core/                # Core functionality and shared components
│   ├── providers/       # Provider-specific implementations (OpenAI, Anthropic, etc.)
│   ├── schemas/         # Interfaces and structs used throughout Bifrost
│   └── bifrost.go       # Main Bifrost implementation
├── framework/           # Framework components for data persistence
│   ├── configstore/     # Configuration storage backends
│   ├── logstore/        # Request logging storage backends
│   └── vectorstore/     # Vector storages
├── transports/          # HTTP gateway and other interface layers
│   └── bifrost-http/    # HTTP transport implementation
├── ui/                  # Web interface for HTTP gateway
├── plugins/             # Extensible plugin system
│   ├── governance/      # Budget management and access control
│   ├── jsonparser/      # JSON parsing and manipulation utilities
│   ├── logging/         # Request logging and analytics
│   ├── maxim/           # Maxim's observability integration
│   ├── mocker/          # Mock responses for testing and development
│   ├── semanticcache/   # Intelligent response caching
│   └── telemetry/       # Monitoring and observability
├── docs/                # Documentation and guides
└── tests/               # Comprehensive test suites

Getting Started Options

Choose the deployment method that fits your needs:

1. Gateway (HTTP API)

Best for: Language-agnostic integration, microservices, and production deployments

# NPX - Get started in 30 seconds
npx -y @maximhq/bifrost

# Docker - Production ready
docker run -p 8080:8080 -v $(pwd)/data:/app/data maximhq/bifrost

Features: Web UI, real-time monitoring, multi-provider management, zero-config startup

Learn More: Gateway Setup Guide

2. Go SDK

Best for: Direct Go integration with maximum performance and control

go get github.com/maximhq/bifrost/core

Features: Native Go APIs, embedded deployment, custom middleware integration

Learn More: Go SDK Guide

3. Drop-in Replacement

Best for: Migrating existing applications with zero code changes

# OpenAI SDK
- base_url = "https://api.openai.com"
+ base_url = "http://localhost:8080/openai"

# Anthropic SDK
- base_url = "https://api.anthropic.com"
+ base_url = "http://localhost:8080/anthropic"

# Google GenAI SDK
- api_endpoint = "https://generativelanguage.googleapis.com"
+ api_endpoint = "http://localhost:8080/genai"

Learn More: Integration Guides

Performance

Bifrost adds virtually zero overhead to your AI requests. In sustained 5,000 RPS benchmarks, the gateway added only 11 µs of overhead per request.

Metric	t3.medium	t3.xlarge	Improvement
Added latency (Bifrost overhead)	59 µs	11 µs	-81%
Success rate @ 5k RPS	100%	100%	No failed requests
Avg. queue wait time	47 µs	1.67 µs	-96%
Avg. request latency (incl. provider)	2.12 s	1.61 s	-24%

Key Performance Highlights:

Perfect Success Rate - 100% request success rate even at 5k RPS
Minimal Overhead - Less than 15 µs additional latency per request
Efficient Queuing - Sub-microsecond average wait times
Fast Key Selection - ~10 ns to pick weighted API keys

Complete Benchmarks: Performance Analysis

Documentation

Complete Documentation: https://docs.getbifrost.ai

Quick Start

Gateway Setup - HTTP API deployment in 30 seconds
Go SDK Setup - Direct Go integration
Provider Configuration - Multi-provider setup

Features

Multi-Provider Support - Single API for all providers
MCP Integration - External tool calling
Semantic Caching - Intelligent response caching
Fallbacks & Load Balancing - Reliability features
Budget Management - Cost control and governance

Integrations

OpenAI SDK - Drop-in OpenAI replacement
Anthropic SDK - Drop-in Anthropic replacement
AWS Bedrock SDK - AWS Bedrock integration
Google GenAI SDK - Drop-in GenAI replacement
LiteLLM SDK - LiteLLM integration
LangChain SDK - LangChain integration

Enterprise

Custom Plugins - Extend functionality
Clustering - Multi-node deployment
Secrets Management - Secure key management
Production Deployment - Scaling and monitoring

Need Help?

Join our Discord for community support and discussions.

Get help with:

Quick setup assistance and troubleshooting
Best practices and configuration tips
Community discussions and support
Real-time help with integrations

Contributing

We welcome contributions of all kinds! See our Contributing Guide for:

Setting up the development environment
Code conventions and best practices
How to submit pull requests
Building and testing locally

For development requirements and build instructions, see our Development Setup Guide.

License

This project is licensed under the Apache 2.0 License - see the LICENSE file for details.

Built with ❤️ by Maxim

amir20/dozzle

Realtime log viewer for containers. Supports Docker, Swarm and K8s.

https://dozzle.dev/

Dozzle - dozzle.dev

Dozzle is a lightweight, web-based application for monitoring Docker logs in real time. It doesn't store any log files—it's designed purely for live log viewing.

https://github.com/user-attachments/assets/66a7b4b2-d6c9-4fca-ab04-aef6cd7c0c31

Note

If you like Dozzle, check out dtop, a top-like application for monitoring Docker containers. It integrates with Dozzle to link directly to container logs.

Features

Intelligent fuzzy search for container names
Search logs using regex
Search logs using SQL queries
Small memory footprint
Split screen for viewing multiple logs
Live stats with memory and CPU usage
Multi-user authentication with support for forward proxy authorization
Swarm mode support
Agent mode for monitoring multiple Docker hosts
Dark mode

Dozzle has been tested with hundreds of containers. However, it doesn't support offline searching. Products like Loggly, Papertrail, or Kibana are better suited for full search capabilities.

Getting Started

Dozzle is a small container (7 MB compressed). Pull the latest release with:

$ docker pull amir20/dozzle:latest

Running Dozzle

The simplest way to use Dozzle is to run the Docker container. Mount the Docker Unix socket with --volume to /var/run/docker.sock:

$ docker run --name dozzle -d --volume=/var/run/docker.sock:/var/run/docker.sock -v dozzle_data:/data -p 8080:8080 amir20/dozzle:latest

Dozzle will be available at http://localhost:8080/.

Here is a Docker Compose example:

services:
  dozzle:
    container_name: dozzle
    image: amir20/dozzle:latest
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - dozzle_data:/data
    ports:
      - 8080:8080
volumes:
  dozzle_data:

For advanced options like authentication, remote hosts, or common questions, see the documentation at dozzle.dev.

Image Tags

Images are published to both Docker Hub and ghcr.io with identical tags.

Tag	Description
`latest`	Most recent release. Recommended for most users.
`v10.6.15`	An exact release. Pin this for reproducible deployments.
`v10.6`	Latest patch within that minor version. Picks up bug fixes only.
`v10`	Latest release within that major version. Picks up new features too.
`alpine`	Same as `latest`, but on an Alpine base instead of `scratch`.
`v10.6.15-alpine`, `v10.6-alpine`, `v10-alpine`	Alpine variants of the version tags above.
`master`	Built from the `master` branch on every push. Unreleased and unstable.
`pr-1234`, `pr-1234-alpine`	Built from pull request #1234, for testing a fix before it ships.

The default images are built FROM scratch and contain only the Dozzle binary, which is why they are around 7 MB compressed. That also means there is no shell inside them. Use the alpine variants only if something in your setup needs one, most commonly platforms that bind-mount a #!/bin/sh wrapper over the container entrypoint such as Unraid's per-container Tailscale toggle. See the FAQ for details.

Avoid latest and master in production. latest moves on every release and master is unreleased code.

Swarm Mode

Dozzle works with Docker Swarm. You can run Dozzle as a global service:

$ docker service create --name dozzle --env DOZZLE_MODE=swarm --mode global --mount type=bind,source=/var/run/docker.sock,target=/var/run/docker.sock -p 8080:8080 amir20/dozzle:latest

See the Swarm Mode documentation for more details.

Agent Mode

Dozzle can monitor multiple Docker hosts. Run Dozzle in agent mode with:

$ docker run -v /var/run/docker.sock:/var/run/docker.sock -p 7007:7007 amir20/dozzle:latest agent

See the Agent Mode documentation for more details.

Technical Details

Dozzle uses automatic API negotiation, which works with most Docker configurations. Dozzle also works with Colima and Podman.

Dozzle requires Docker Engine 19.03 or newer (API version 1.40+). Older daemons are not supported by the underlying Docker SDK.

Installation on Podman

By default, Podman doesn't have a background process, but you can enable the remote socket for Dozzle to work.

First, verify if your Podman installation has the remote socket enabled:

podman info

If you see output like this under the remote socket key, it's already enabled:

  remoteSocket:
    exists: true
    path: /run/user/1000/podman/podman.sock

If it's not enabled, follow this tutorial to enable it.

Once the Podman remote socket is enabled, you can run Dozzle:

podman run --volume=/run/user/1000/podman/podman.sock:/var/run/docker.sock -d -p 8080:8080 docker.io/amir20/dozzle:latest

Nothing else is needed. Dozzle works out a stable host id for Podman on its own, since Podman is daemonless and has no engine identity to report.

Note

Older versions of this page told you to create a /var/lib/docker/engine-id file to prevent host not found errors. That never worked. Podman's Docker-compatible /info endpoint does not read any file, it returns a new random UUID on every call, so Dozzle now derives the id instead. You can delete the file.

For more details, see Podman Info or the FAQ.

Security

Dozzle supports file-based authentication and forward proxy authentication with tools like Authelia. See the documentation at https://dozzle.dev/guide/authentication.

Analytics

Dozzle collects anonymous user configurations using Google Analytics. Why? Dozzle is an open source project with no funding, so there's no time for formal user studies. Analytics help prioritize features and fixes based on how people use Dozzle. This data is completely public and can be viewed live on the Data Studio dashboard.

To disable analytics, use the --no-analytics flag.

Environment Variables and Configuration

Dozzle follows the 12-factor model. Configuration can be done via CLI flags or environment variables. See the documentation at dozzle.dev/guide/supported-env-vars for more details.

Support

There are many ways to support Dozzle:

Use it! Write about it! Star it! If you love Dozzle, drop me a line and tell me what you love.
Blog about Dozzle to spread the word. If you're good at writing, send PRs to improve the documentation at dozzle.dev.
Sponsor my work at https://www.buymeacoffee.com/amirraminfar

License

MIT

Building

Want to contribute? Great! Dozzle has two parts: a Go backend that talks to Docker, and a Vue frontend that runs in the browser. You don't need to know both — pick the side that matches what you want to change. For documentation fixes, no setup is needed at all; just edit the file on GitHub.

1. Install the prerequisites

You'll need Go (1.25+), Node.js (with pnpm), and protoc.

On macOS, you can install everything in one go:

brew install go node pnpm protobuf

On Linux (Debian/Ubuntu):

sudo apt install golang nodejs protobuf-compiler
npm install -g pnpm

On Windows, we recommend using WSL2 and following the Linux instructions.

2. Clone and set up

git clone https://github.com/amir20/dozzle.git
cd dozzle
pnpm install                # installs frontend dependencies
go install tool             # installs Go build tools listed in go.mod (air, protoc-gen-go, etc.)
make generate               # generates TLS certificates and protobuf code (only needed once)

3. Start the dev server

make dev

Open http://localhost:3100 — you should see the Dozzle UI connected to your local Docker. Both the frontend and backend reload automatically when you save a file.

Making your first change

Try editing assets/pages/index.vue and saving — the browser updates instantly. For backend changes, edit any .go file and the server will restart on its own.

Troubleshooting

Nothing shows up at localhost:3100 — make sure Docker is running and the socket is accessible at /var/run/docker.sock.
make generate fails — confirm protoc is on your PATH (protoc --version).
Still stuck? Open a question in GitHub Discussions — we're happy to help.

Adding App Icons

Dozzle shows a logo next to containers whose image it recognizes. Icons are vendored from homarr-labs/dashboard-icons into assets/icons/apps/, and matching happens in assets/utils/appIcons.ts.

The repo ships an add-app-icon skill in .claude/skills/. To add icons with an AI coding agent, paste this prompt and fill in the images:

Use the add-app-icon skill in .claude/skills/add-app-icon/SKILL.md to add app icons
for these container images: <image1>, <image2>

Gentleman-Programming/gentle-ai

Gentle-AI configures the AI coding agents you already use: Claude Code, Cursor, OpenCode, Codex, Pi, and more. Choose persistent memory, Spec-Driven Development, curated skills, MCP servers, personas, and optional bounded review. Open source, no agent lock-in.

https://gentle-ai.gentlemanprogramming.com/

Gentle-AI™

The deterministic engineering environment for the AI agent you already use.

Website • Quickstart • Docs • Wiki

Your agent writes code, then forgets everything. It has no opinion about your project, and no way to prove what it did beyond asking you to read every line. Gentle-AI gives it memory, a workflow, and evidence.

_{If Gentle-AI made your agent worth trusting, a star helps other people find it.}

_{WORKS WITH THE AGENT YOU ALREADY HAVE}

Pi · OpenCode · Claude Code · Codex · Cursor · VS Code Copilot · Gemini CLI · Kilo Code
Kimi Code · Kiro IDE · Qwen Code · Hermes · Antigravity · Windsurf · OpenClaw · Trae

_{16 integrations · native configuration · compare capabilities →}

Features

Engram™ — Keep your project context

The cost of a fresh session is not the tokens — it is you, re-explaining the same decisions every morning. Engram removes that: your agent writes down what it learns as it goes and reaches for it before it reaches for you, so context accumulates instead of resetting.

Docs →

SDD — Give each change a clear path

Every phase leaves a file on disk you can open, argue with, and correct — so the plan is reviewable before a single line of code exists. TDD (test-driven development) belongs in Apply when it fits, because that is the first point where there is a spec to test against. Verify then runs as its own step against that spec, not as a self-report from whatever wrote the code, so you can see what was actually checked.

Docs →

RDD — Check finished work at the right depth

Receipt-Driven Development (RDD) is opt-in and stays off until you enable it. Its point is that a review cannot drift: the candidate is frozen before anything reads it, so the evidence belongs to the exact version you are about to rely on — not to whatever the worktree looked like a moment later. The depth comes from that frozen candidate rather than from the model's judgment, and the result is informational. Commit, push and release stay your call.

Docs →

Deterministic by design — Know the next valid step

A model that guesses the next step guesses differently tomorrow, and differently again for your teammate. That is the gap between a workflow and a suggestion. The gentle-ai binary owns native SDD status and RDD review transitions, and because it reads state from files rather than from a context window, two people on two machines get the same answer — and so does the same person a month later.

Docs →

Gentle Shell — A complete workspace for Pi

The way Gentle-AI was intended. Gentle-AI brings our native Pi extensions together in one focused development environment: orchestrate specialized agents, monitor usage for supported provider accounts, and review code changes in a built-in diff.

Docs →

16 agents — Keep the agent you already use

Gentle-AI brings its shared workflow to Pi, OpenCode, Claude Code, Codex, and twelve more agents. Each integration uses that agent's native capabilities, so available features such as delegation and RDD review can differ.

Docs →

Also in the box

Component	What it does
Skills library	Loaded automatically when the task matches
Context7 MCP	Optional, selectable live framework and library documentation
CodeGraph	Read-only symbol graph of your codebase
Security deny-list	Blocks `~/.ssh`, `.env` and credential files
Config backups	Snapshotted before every single write
Doctor	`gentle-ai doctor` — read-only health report
Personas	Optional personas; Gentleman is a caring but rigorous mentor who guides you toward your goal
Themes	Gentleman and Gentleman-Cute
Per-phase model assignment	Assign a model to each phase in Pi and OpenCode

Every component, skill and preset: Full breakdown →

Get started

# macOS (Homebrew)
brew install gentleman-programming/tap/gentle-ai

# macOS / Linux (curl)
curl -fsSL https://raw.githubusercontent.com/Gentleman-Programming/gentle-ai/main/scripts/install.sh | bash

# Windows (PowerShell) — source install, needs Go 1.25.10+
go install github.com/gentleman-programming/gentle-ai/v2/cmd/gentle-ai@latest

gentle-ai          # pick your agents, components and persona
gentle-ai doctor   # verify — read-only, changes nothing

Then use your agent normally. Your configs are snapshotted before every write, and Gentle-AI never installs an AI agent for you — it configures what you already have.

Beta channel, signature verification and per-distro prerequisites: Quickstart →

Documentation

Where to go	What you'll find
Intended Usage	The mental model. If you read one page, read this one.
Quickstart · Usage	Install, prerequisites, every CLI command and flag
Agents	Feature matrix and per-agent notes for all 16
Routing	How the agent picks direct, delegated or SDD
Review · Architecture	The RDD contract, lifecycle and threat model
Engram · Components	Memory commands, skills, presets and personas
Contributing · Codebase Guide	Extend or contribute
Telemetry	What we count, and how to turn it off

Community

Everything labelled up-for-grabs is scoped, approved and unclaimed — pick one and it's yours.

_{This project exists because of these people.}

About the author

Built by Alan Buscaglia (Gentleman Programming): 15 years of enterprise architecture, a community of thousands of developers testing these tools daily, and one rule for AI-assisted work — verifying beats generating.

Teams adopting AI and finding it isn't working — resistance, everyone prompting their own way, no shared quality bar — can reach out about engagements built on these same open-source tools →.

Gentle-AI is crafted with Gentle-AI

Trademark notice: The Gentle AI™ and Engram™ names and logos are trademarks of Alan Buscaglia. Both marks are used throughout this document; the symbol appears on the first prominent mention of each, and this notice covers the rest. The MIT License applies to the code; it does not permit implying endorsement or official affiliation. See TRADEMARKS.md.

argoproj/argo-cd

Declarative Continuous Deployment for Kubernetes

https://argo-cd.readthedocs.io

Releases:

Code:

Social:

Argo CD - Declarative Continuous Delivery for Kubernetes

What is Argo CD?

Argo CD is a declarative GitOps continuous delivery tool for Kubernetes.

Why Argo CD?

Application definitions, configurations, and environments should be declarative and version controlled.
Application deployment and lifecycle management should be automated, auditable, and easy to understand.

Who uses Argo CD?

Official Argo CD user list

Documentation

To learn more about Argo CD go to the complete documentation. Check live demo at https://cd.apps.argoproj.io/.

Community

Contribution, Discussion and Support

You can reach the Argo CD community and developers via the following channels:

Q & A : GitHub Discussions
Chat : The #argo-cd Slack channel
Contributors Office Hours: Every Thursday | Agenda
User Community meeting: First Wednesday of the month | Agenda

Participation in the Argo CD project is governed by the CNCF Code of Conduct

Blogs and Presentations

QuantumNous/new-api

A unified AI model hub for aggregation & distribution. It supports cross-converting various LLMs into OpenAI-compatible, Claude-compatible, or Gemini-compatible formats. A centralized gateway for personal and enterprise model management.

https://www.newapi.ai

New API

🍥 Next-Generation LLM Gateway and AI Asset Management System

简体中文 | 繁體中文 | English | Français | 日本語

Quick Start • Key Features • Deployment • Documentation • Help

📝 Project Description

Important

This project is intended solely for lawful and authorized AI API gateway, organization-level authentication, multi-model management, usage analytics, cost accounting, and private deployment scenarios.
Users must lawfully obtain upstream API keys, accounts, model services, and interface permissions, and must comply with upstream terms of service and applicable laws and regulations.
Users should ensure their use complies with upstream terms of service and applicable laws and regulations.
When providing generative AI services to the public, users should comply with applicable regulatory requirements and fulfill all filing, licensing, content safety, real-name verification, log retention, tax, and upstream authorization obligations required by their jurisdiction.

🤝 Trusted Partners

No particular order

🙏 Special Thanks

Thanks to JetBrains for providing free open-source development license for this project

🚀 Quick Start

Using Docker Compose (Recommended)

# Clone the project
git clone https://github.com/QuantumNous/new-api.git
cd new-api

# Edit docker-compose.yml configuration
nano docker-compose.yml

# Start the service
docker-compose up -d

Using Docker Commands

# Pull the latest image
docker pull calciumion/new-api:latest

# Using SQLite (default)
docker run --name new-api -d --restart always \
  -p 3000:3000 \
  -e TZ=Asia/Shanghai \
  -v ./data:/data \
  calciumion/new-api:latest

# Using MySQL
docker run --name new-api -d --restart always \
  -p 3000:3000 \
  -e SQL_DSN="root:123456@tcp(localhost:3306)/oneapi" \
  -e TZ=Asia/Shanghai \
  -v ./data:/data \
  calciumion/new-api:latest

💡 Tip: -v ./data:/data will save data in the data folder of the current directory, you can also change it to an absolute path like -v /your/custom/path:/data

🎉 After deployment is complete, visit http://localhost:3000 to start using!

Warning

When operating this project as a public generative AI service or API resale service, users should first complete all required filing, licensing, content safety, real-name verification, log retention, tax, payment, and upstream authorization obligations.

📖 For more deployment methods, please refer to Deployment Guide

📚 Documentation

📖 Official Documentation |

Quick Navigation:

Category	Link
🚀 Deployment Guide	Installation Documentation
⚙️ Environment Configuration	Environment Variables
📡 API Documentation	API Documentation
❓ FAQ	FAQ
💬 Community Interaction	Communication Channels

✨ Key Features

For detailed features, please refer to Features Introduction

🎨 Core Functions

Feature	Description
🎨 New UI	Modern user interface design
🌍 Multi-language	Supports Simplified Chinese, Traditional Chinese, English, French, Japanese
🔄 Data Compatibility	Fully compatible with the original One API database
📈 Data Dashboard	Visual console and statistical analysis
🔒 Permission Management	Token grouping, model restrictions, user management

💰 Authorized Usage Accounting and Billing

✅ Internal top-up and quota allocation for lawful authorized scenarios (EPay, Stripe)
✅ Organization-level per-request, usage-based, and cache-hit cost accounting
✅ Cache billing statistics for OpenAI, Azure, DeepSeek, Claude, Qwen, and supported models
✅ Flexible billing policies for internal management or authorized enterprise customers

🔐 Authorization and Security

😈 Discord authorization login
🤖 LinuxDO authorization login
📱 Telegram authorization login
🔑 OIDC unified authentication
🔍 Key quota query usage (with new-api-key-tool)

🚀 Advanced Features

API Format Support:

⚡ OpenAI Responses
⚡ OpenAI Realtime API (including Azure)
⚡ Claude Messages
⚡ Google Gemini
🔄 Rerank Models (Cohere, Jina)

Intelligent Routing:

⚖️ Channel weighted random
🔄 Automatic retry on failure
🚦 User-level model rate limiting

Format Conversion:

🔄 OpenAI Compatible ⇄ Claude Messages
🔄 OpenAI Compatible → Google Gemini
🔄 Google Gemini → OpenAI Compatible - Text only, function calling not supported yet
🚧 OpenAI Compatible ⇄ OpenAI Responses - In development
🔄 Thinking-to-content functionality

Reasoning Effort Support:

View detailed configuration

OpenAI series models:

o3-mini-high - High reasoning effort
o3-mini-medium - Medium reasoning effort
o3-mini-low - Low reasoning effort
gpt-5-high - High reasoning effort
gpt-5-medium - Medium reasoning effort
gpt-5-low - Low reasoning effort

Claude thinking models:

claude-3-7-sonnet-20250219-thinking - Enable thinking mode

Google Gemini series models:

gemini-2.5-flash-thinking - Enable thinking mode
gemini-2.5-flash-nothinking - Disable thinking mode
gemini-2.5-pro-thinking - Enable thinking mode
gemini-2.5-pro-thinking-128 - Enable thinking mode with thinking budget of 128 tokens
You can also append -low, -medium, or -high to any Gemini model name to request the corresponding reasoning effort (no extra thinking-budget suffix needed).

🤖 Model Support

For details, please refer to API Documentation - Gateway Interface

Model Type	Description	Documentation
🤖 OpenAI-Compatible	OpenAI compatible models	Documentation
🤖 OpenAI Responses	OpenAI Responses format	Documentation
🎨 Midjourney-Proxy	Midjourney-Proxy(Plus)	Documentation
🎵 Suno-API	Suno API	Documentation
🔄 Rerank	Cohere, Jina	Documentation
💬 Claude	Messages format	Documentation
🌐 Gemini	Google Gemini format	Documentation
🔧 Dify	ChatFlow mode	-
🎯 Custom upstream	Supports configuring legally authorized upstream endpoints	-

📡 Supported Interfaces

View complete interface list

🚢 Deployment

Tip

Latest Docker image: calciumion/new-api:latest

📋 Deployment Requirements

Component	Requirement
Local database	SQLite (Docker must mount `/data` directory)
Remote database	MySQL ≥ 5.7.8 or PostgreSQL ≥ 9.6
Container engine	Docker / Docker Compose
System architecture	64-bit only (amd64 / arm64); 32-bit systems are not supported

⚙️ Environment Variable Configuration

Common environment variable configuration

Variable Name	Description	Default Value
`SESSION_SECRET`	Authentication signing secret; must be identical on every node	-
`SESSION_COOKIE_SECURE`	`false`/unset disables the refresh/logout OriginGuard for local HTTP dev proxies; `true` enables the Secure cookie and strict Origin checks	`false`
`SESSION_COOKIE_TRUSTED_URL`	Required with Secure mode: comma-separated exact HTTPS Origins allowed to call refresh/logout; not a relay CORS allowlist	-
`TRUSTED_PROXIES`	Unset/blank trusts loopback, RFC 1918 and IPv6 ULA with a startup warning; `none` trusts no proxies; an explicit proxy IP/CIDR list replaces the defaults	`127.0.0.0/8, ::1, 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, fc00::/7`
`USER_SESSION_ACTIVE_LIMIT`	Maximum active login Sessions per user	`50`
`USER_SESSION_ISSUANCE_LIMIT`	Maximum Sessions created per user within the issuance window, including revoked Sessions	`100`
`USER_SESSION_ISSUANCE_WINDOW_SECONDS`	Per-user Session issuance window; clamped to the revoked retention period when configured higher	`86400`
`USER_SESSION_REVOKED_RETENTION_DAYS`	Days to retain revoked Session rows for audit and issuance accounting	`7`
`USER_SESSION_HOURLY_ALERT_THRESHOLD`	Global Sessions created per hour that triggers an alert only; it never blocks login	`5000`
`CRYPTO_SECRET`	HMAC secret for cache keys; nodes sharing Redis must use the same effective value	Defaults to `SESSION_SECRET`
`SQL_DSN`	Database connection string	-
`REDIS_CONN_STRING`	Redis connection string	-
`RELAY_IDLE_CONN_TIMEOUT`	Idle keep-alive timeout for relay HTTP clients, seconds. Defaults to Go standard library behavior; set `0` to disable	`90`
`RELAY_RESPONSE_HEADER_TIMEOUT`	How long the relay waits for upstream response headers, seconds; set `0` to disable. Only bounds the header wait -- streaming after the headers arrive is unaffected. Note that non-streaming upstreams usually send headers only once generation finishes, so leave headroom	`1800`
`STREAMING_TIMEOUT`	Streaming timeout (seconds)	`300`
`STREAM_SCANNER_MAX_BUFFER_MB`	Max per-line buffer (MB) for the stream scanner; increase when upstream sends huge image/base64 payloads	`64`
`MAX_REQUEST_BODY_MB`	Max request body size (MB, counted after decompression; prevents huge requests/zip bombs from exhausting memory). Exceeding it returns `413`	`32`
`AZURE_DEFAULT_API_VERSION`	Azure API version	`2025-04-01-preview`
`ERROR_LOG_ENABLED`	Error log switch	`false`
`PYROSCOPE_URL`	Pyroscope server address	-
`PYROSCOPE_APP_NAME`	Pyroscope application name	`new-api`
`PYROSCOPE_BASIC_AUTH_USER`	Pyroscope basic auth user	-
`PYROSCOPE_BASIC_AUTH_PASSWORD`	Pyroscope basic auth password	-
`PYROSCOPE_MUTEX_RATE`	Pyroscope mutex sampling rate	`5`
`PYROSCOPE_BLOCK_RATE`	Pyroscope block sampling rate	`5`
`HOSTNAME`	Hostname tag for Pyroscope	`new-api`

📖 Complete configuration: Environment Variables Documentation

🔧 Deployment Methods

Method 1: Docker Compose (Recommended)

# Clone the project
git clone https://github.com/QuantumNous/new-api.git
cd new-api

# Edit configuration
nano docker-compose.yml

# Start service
docker-compose up -d

Method 2: Docker Commands

Using SQLite:

docker run --name new-api -d --restart always \
  -p 3000:3000 \
  -e TZ=Asia/Shanghai \
  -v ./data:/data \
  calciumion/new-api:latest

Using MySQL:

docker run --name new-api -d --restart always \
  -p 3000:3000 \
  -e SQL_DSN="root:123456@tcp(localhost:3306)/oneapi" \
  -e TZ=Asia/Shanghai \
  -v ./data:/data \
  calciumion/new-api:latest

💡 Path explanation:

./data:/data - Relative path, data saved in the data folder of the current directory

You can also use absolute path, e.g.: /your/custom/path:/data

Method 3: BaoTa Panel

Install BaoTa Panel (≥ 9.2.0 version)
Search for New-API in the application store
One-click installation

📖 Tutorial with images

⚠️ Multi-machine Deployment Considerations

Warning

All nodes must use the same primary database and the same SESSION_SECRET; otherwise Access Tokens, refresh sessions, and temporary authentication flows cannot be verified consistently.
Nodes connected to the same Redis must also use the same CRYPTO_SECRET, or their cache-key digests will differ and shared entries cannot be reused consistently.

The database is authoritative for login Sessions and for the per-user active/issuance limits. Redis Session entries are short-lived caches whose TTL follows SYNC_FREQUENCY (60 seconds by default) and never exceeds the Session's remaining lifetime.

Redis topology	Session propagation	Rate limiting
Shared Redis	Revocations and version publications normally propagate immediately	Redis limits are shared across nodes
Independent Redis per node	Nodes converge from the database within the effective `SYNC_FREQUENCY`; a newly rotated token may receive a temporary 401 on a node with stale cache	Each node has its own allowance, so aggregate capacity can reach roughly the configured limit multiplied by the node count
No Redis	Every Session validation reads the database	In-memory limits are independent per node

A shorter SYNC_FREQUENCY reduces the independent-Redis staleness window but causes one additional primary-key Session lookup per active SID, per node, per TTL. These guarantees make Session authentication bounded-stale across the supported topologies; rate limits and other Redis-backed control-plane caches remain topology-dependent.

See User authentication and login sessions for the token, Origin-check and PAT contracts.

🔄 Channel Retry and Cache

Retry configuration: Settings → Operation Settings → General Settings → Failure Retry Count

Cache configuration:

REDIS_CONN_STRING: Redis cache (recommended)
MEMORY_CACHE_ENABLED: Memory cache

🔗 Related Projects

Upstream Projects

Project	Description
One API	Original project base
Midjourney-Proxy	Midjourney interface support

Supporting Tools

Project	Description
new-api-key-tool	Key quota query tool
new-api-horizon	New API high-performance optimized version

💬 Help Support

📖 Documentation Resources

Resource	Link
📘 FAQ	FAQ
💬 Community Interaction	Communication Channels
🐛 Issue Feedback	Issue Feedback
📚 Complete Documentation	Official Documentation

🤝 Contribution Guide

Welcome all forms of contribution!

🐛 Report Bugs
💡 Propose New Features
📝 Improve Documentation
🔧 Submit Code

📜 License

This project is licensed under the GNU Affero General Public License v3.0 (AGPLv3).

Additional terms under AGPLv3 Section 7 apply. Modified versions must preserve the author attribution notice Frontend design and development by New API contributors. in the appropriate legal notices and in any prominent about, legal, footer, or attribution location presented by the user interface.

Modified versions that present a user interface must also preserve a visible link to the original project: https://github.com/QuantumNous/new-api.

This is an open-source project developed based on One API (MIT License).

If your organization's policies do not permit the use of AGPLv3-licensed software, or if you wish to avoid the open-source obligations of AGPLv3, please contact us at: support@quantumnous.com

🌟 Star History

💖 Thank you for using New API

If this project is helpful to you, welcome to give us a ⭐️ Star！

Official Documentation • Issue Feedback • Latest Release

_{Built with ❤️ by QuantumNous}

DataDog/datadog-agent

Main repository for Datadog Agent

https://docs.datadoghq.com/

Datadog Agent

This repository contains the source code of the Datadog Agent version 7 and version 6. Please refer to the Agent user documentation for information about differences between Agent v5, Agent v6 and Agent v7. Additionally, we provide a list of prepackaged binaries for an easy install process here.

Documentation

The developer docs site contains information about how to develop the Datadog Agent itself.

The source of the content is located under the docs directory and may contain pages that are not yet published.

Contributing code

You'll find information and help on how to contribute code to this project under the docs/dev directory of the present repo.

License

The Datadog Agent user space components are licensed under the Apache License, Version 2.0. The BPF code is licensed under the General Public License, Version 2.0.

projectdiscovery/katana

A next-generation crawling and spidering framework.

A next-generation crawling and spidering framework

Features • Installation • Usage • Scope • Config • Filters • Join Discord

Features

Fast And fully configurable web crawling
Standard and Headless mode
JavaScript parsing / crawling
Customizable automatic form filling
Scope control - Preconfigured field / Regex
Knowledge base - ML page-type / form classification (auto-downloaded model)
Customizable output - Preconfigured fields
INPUT - STDIN, URL and LIST
OUTPUT - STDOUT, FILE and JSON

Installation

katana requires Go 1.26+ to install successfully. If you encounter any installation issues, we recommend trying with the latest available version of Go, as the minimum required version may have changed. Run the command below or download a pre-compiled binary from the release page.

CGO_ENABLED=1 go install github.com/projectdiscovery/katana/cmd/katana@latest

More options to install / run katana-

Docker

To install / update docker to latest tag -

docker pull projectdiscovery/katana:latest

To run katana in standard mode using docker -

docker run projectdiscovery/katana:latest -u https://tesla.com

To run katana in headless mode using docker -

docker run projectdiscovery/katana:latest -u https://tesla.com -system-chrome -headless

Ubuntu

It's recommended to install the following prerequisites -

sudo apt update
sudo apt install zip curl wget git snapd
sudo snap refresh
sudo snap install golang --classic

sudo install -d -m 0755 /etc/apt/keyrings
curl -fsSL https://dl.google.com/linux/linux_signing_key.pub \
  | sudo gpg --dearmor -o /etc/apt/keyrings/google-chrome.gpg

echo "deb [arch=amd64 signed-by=/etc/apt/keyrings/google-chrome.gpg] \
  http://dl.google.com/linux/chrome/deb/ stable main" \
  | sudo tee /etc/apt/sources.list.d/google-chrome.list > /dev/null

sudo apt update
sudo apt install google-chrome-stable

install katana -

go install github.com/projectdiscovery/katana/cmd/katana@latest

Usage

katana -h

This will display help for the tool. Here are all the switches it supports.

Katana is a fast crawler focused on execution in automation
pipelines offering both headless and non-headless crawling.

Usage:
  ./katana [flags]

Flags:
INPUT:
   -u, -list string[]     target url / list to crawl
   -resume string         resume scan using resume.cfg
   -e, -exclude string[]  exclude host matching specified filter ('cdn', 'private-ips', cidr, ip, regex)

CONFIGURATION:
   -r, -resolvers string[]       list of custom resolver (file or comma separated)
   -d, -depth int                maximum depth to crawl (default 3)
   -jc, -js-crawl                enable endpoint parsing / crawling in javascript file
   -jsl, -jsluice                enable jsluice parsing in javascript file (memory intensive)
   -ct, -crawl-duration value    maximum duration to crawl the target for (s, m, h, d) (default s)
   -kf, -known-files string      enable crawling of known files (all,robotstxt,sitemapxml), a minimum depth of 3 is required to ensure all known files are properly crawled.
   -mrs, -max-response-size int  maximum response size to read (default 4194304)
   -timeout int                  time to wait for request in seconds (default 10)
   -aff, -automatic-form-fill    enable automatic form filling (experimental)
   -fx, -form-extraction         extract form, input, textarea & select elements in jsonl output
   -retry int                    number of times to retry the request (default 1)
   -proxy string                 http/socks5 proxy to use
   -td, -tech-detect             enable technology detection
   -H, -headers string[]         custom header/cookie to include in all http request in header:value format (file)
   -config string                path to the katana configuration file
   -fc, -form-config string      path to custom form configuration file
   -flc, -field-config string    path to custom field configuration file
   -s, -strategy string          Visit strategy (depth-first, breadth-first) (default "depth-first")
   -iqp, -ignore-query-params    Ignore crawling same path with different query-param values
   -fsu, -filter-similar         filter crawling of similar looking URLs (e.g., /users/123 and /users/456)
   -fst, -filter-similar-threshold int  number of distinct values before a path position is treated as parameter (default 10)
   -tlsi, -tls-impersonate       enable experimental client hello (ja3) tls randomization
   -dr, -disable-redirects       disable following redirects (default false)
   -pcs, -page-content-similar   enable page content similarity filtering (simhash|tfidf|bm25)
   -pcsm, -page-content-similar-mode string  similarity mode: simhash, tfidf, or bm25 (default simhash)
   -pcsd, -page-content-similar-distance int  simhash max hamming distance (default 3)
   -pcst, -page-content-similar-threshold float  tfidf/bm25 min score 0-1 (default 0.85)
   -pcsn, -page-content-similar-budget int  pages to fully process per similarity cluster (default 1)
   -sdd, -similarity-deduplication  alias for -pcs
   -kb, -knowledge-base          enable knowledge base classification
   -kb-secrets                   enable secrets extractor in the knowledge base
   -kb-validate-secrets          validate detected secrets against their provider (sends live API calls)
   -kb-endpoints                 enable endpoints extractor (classifies REST/GraphQL/SOAP/XHR requests)
   -mdp, -max-domain-pages int   maximum number of pages to crawl per domain (default unlimited)

DEBUG:
   -health-check, -hc        run diagnostic check up
   -elog, -error-log string  file to write sent requests error log
   -pprof-server             enable pprof server

HEADLESS:
   -hl, -headless                    enable headless hybrid crawling (experimental)
   -sc, -system-chrome               use local installed chrome browser instead of katana installed
   -sb, -show-browser                show the browser on the screen with headless mode
   -ho, -headless-options string[]   start headless chrome with additional options
   -nos, -no-sandbox                 start headless chrome in --no-sandbox mode
   -cdd, -chrome-data-dir string     path to store chrome browser data
   -scp, -system-chrome-path string  use specified chrome browser for headless crawling
   -noi, -no-incognito               start headless chrome without incognito mode
   -cwu, -chrome-ws-url string       use chrome browser instance launched elsewhere with the debugger listening at this URL
   -xhr, -xhr-extraction             extract xhr request url,method in jsonl output
   -pls, -page-load-strategy string  page load strategy (heuristic, load, domcontentloaded, networkidle, none) (default "heuristic")
   -dwt, -dom-wait-time int          time in seconds to wait after page load when using domcontentloaded strategy (default 5)
   -csp, -captcha-solver-provider string  captcha solver provider (e.g. capsolver)
   -csk, -captcha-solver-key string       captcha solver provider api key

SCOPE:
   -cs, -crawl-scope string[]       in scope url regex to be followed by crawler
   -cos, -crawl-out-scope string[]  out of scope url regex to be excluded by crawler
   -fs, -field-scope string         pre-defined scope field (dn,rdn,fqdn) or custom regex (e.g., '(company-staging.io|company.com)') (default "rdn")
   -ns, -no-scope                   disables host based default scope
   -do, -display-out-scope          display external endpoint from scoped crawling

FILTER:
   -mr, -match-regex string[]             regex or list of regex to match on output url (cli, file)
   -fr, -filter-regex string[]            regex or list of regex to filter on output url (cli, file)
   -f, -field string                      field to display in output (url,path,fqdn,rdn,rurl,qurl,qpath,file,ufile,key,value,kv,dir,udir) (Deprecated: use -output-template instead)
   -sf, -store-field string               field to store in per-host output (url,path,fqdn,rdn,rurl,qurl,qpath,file,ufile,key,value,kv,dir,udir)
   -em, -extension-match string[]         match output for given extension (eg, -em php,html,js,none)
   -ef, -extension-filter string[]        filter output for given extension (eg, -ef png,css)
   -ndef, -no-default-ext-filter bool     remove default extensions from the filter list
   -mdc, -match-condition string          match response with dsl based condition
   -fdc, -filter-condition string         filter response with dsl based condition
   -duf, -disable-unique-filter           disable duplicate content filtering
   -filter-page-type string[]      filter response with page type (e.g. error,captcha,parked)

RATE-LIMIT:
   -c, -concurrency int          number of concurrent fetchers to use (default 10)
   -p, -parallelism int          number of concurrent inputs to process (default 10)
   -rd, -delay int               request delay between each request in seconds
   -rl, -rate-limit int          maximum requests to send per second (default 150)
   -rlm, -rate-limit-minute int  maximum number of requests to send per minute
   -hrl, -host-rate-limit int    maximum requests to send per second per host
   -hrlm, -host-rate-limit-minute int  maximum number of requests to send per minute per host

UPDATE:
   -up, -update                 update katana to latest version
   -duc, -disable-update-check  disable automatic katana update check

OUTPUT:
   -o, -output string                file to write output to
   -output-template string      custom output template
   -sr, -store-response              store http requests/responses
   -srd, -store-response-dir string  store http requests/responses to custom directory
   -ncb, -no-clobber                 do not overwrite output file
   -sfd, -store-field-dir string     store per-host field to custom directory
   -or, -omit-raw                    omit raw requests/responses from jsonl output
   -ob, -omit-body                   omit response body from jsonl output
   -lof, -list-output-fields         list available fields for jsonl output format
   -eof, -exclude-output-fields      exclude fields from jsonl output
   -j, -jsonl                        write output in jsonl format
   -nc, -no-color                    disable output content coloring (ANSI escape codes)
   -silent                           display output only
   -v, -verbose                      display verbose output
   -debug                            display debug output
   -version                          display project version

Running Katana

Input for katana

katana requires url or endpoint to crawl and accepts single or multiple inputs.

Input URL can be provided using -u option, and multiple values can be provided using comma-separated input, similarly file input is supported using -list option and additionally piped input (stdin) is also supported.

URL Input

katana -u https://tesla.com

Multiple URL Input (comma-separated)

katana -u https://tesla.com,https://google.com

List Input

$ cat url_list.txt

https://tesla.com
https://google.com

katana -list url_list.txt

STDIN (piped) Input

echo https://tesla.com | katana

cat domains | httpx | katana

Page Content Similarity

Optional Layer-2 filtering after exact MD5 content dedup. Shared HTML normalization strips chrome (nav/header/footer/scripts), then one of three modes decides whether a page is similar enough to skip further parse/enqueue (cluster budget). URL-shape dedup (-fsu) remains independent.

Mode	Flag	Best for
`simhash` (default)	`-pcsm simhash`	Near-duplicate / template clones (Hamming via `-pcsd`)
`tfidf`	`-pcsm tfidf`	Topical cosine similarity (`-pcst`)
`bm25`	`-pcsm bm25`	Topical similarity with length normalization (`-pcst`)

# Near-duplicate detection (default mode)
katana -u https://example.com -pcs

# TF-IDF topical filtering with higher budget
katana -u https://shop.example.com -pcs -pcsm tfidf -pcst 0.85 -pcsn 2

# BM25 mode
katana -u https://example.com -pcs -pcsm bm25

# Alias from older flag name
katana -u https://example.com -sdd -pcsm simhash

Example completion stats:

[INF] Content similarity (simhash): 103 processed, 30 accepted, 73 filtered - 70.9% filter rate
[INF] Crawl completed in 14s. 21 endpoints found.

Example running katana -

katana -u https://youtube.com

   __        __                
  / /_____ _/ /____ ____  ___ _
 /  '_/ _  / __/ _  / _ \/ _  /
/_/\_\\_,_/\__/\_,_/_//_/\_,_/ v0.0.1                     

      projectdiscovery.io

[WRN] Use with caution. You are responsible for your actions.
[WRN] Developers assume no liability and are not responsible for any misuse or damage.
https://www.youtube.com/
https://www.youtube.com/about/
https://www.youtube.com/about/press/
https://www.youtube.com/about/copyright/
https://www.youtube.com/t/contact_us/
https://www.youtube.com/creators/
https://www.youtube.com/ads/
https://www.youtube.com/t/terms
https://www.youtube.com/t/privacy
https://www.youtube.com/about/policies/
https://www.youtube.com/howyoutubeworks?utm_campaign=ytgen&utm_source=ythp&utm_medium=LeftNav&utm_content=txt&u=https%3A%2F%2Fwww.youtube.com%2Fhowyoutubeworks%3Futm_source%3Dythp%26utm_medium%3DLeftNav%26utm_campaign%3Dytgen
https://www.youtube.com/new
https://m.youtube.com/
https://www.youtube.com/s/desktop/4965577f/jsbin/desktop_polymer.vflset/desktop_polymer.js
https://www.youtube.com/s/desktop/4965577f/cssbin/www-main-desktop-home-page-skeleton.css
https://www.youtube.com/s/desktop/4965577f/cssbin/www-onepick.css
https://www.youtube.com/s/_/ytmainappweb/_/ss/k=ytmainappweb.kevlar_base.0Zo5FUcPkCg.L.B1.O/am=gAE/d=0/rs=AGKMywG5nh5Qp-BGPbOaI1evhF5BVGRZGA
https://www.youtube.com/opensearch?locale=en_GB
https://www.youtube.com/manifest.webmanifest
https://www.youtube.com/s/desktop/4965577f/cssbin/www-main-desktop-watch-page-skeleton.css
https://www.youtube.com/s/desktop/4965577f/jsbin/web-animations-next-lite.min.vflset/web-animations-next-lite.min.js
https://www.youtube.com/s/desktop/4965577f/jsbin/custom-elements-es5-adapter.vflset/custom-elements-es5-adapter.js
https://www.youtube.com/s/desktop/4965577f/jsbin/webcomponents-sd.vflset/webcomponents-sd.js
https://www.youtube.com/s/desktop/4965577f/jsbin/intersection-observer.min.vflset/intersection-observer.min.js
https://www.youtube.com/s/desktop/4965577f/jsbin/scheduler.vflset/scheduler.js
https://www.youtube.com/s/desktop/4965577f/jsbin/www-i18n-constants-en_GB.vflset/www-i18n-constants.js
https://www.youtube.com/s/desktop/4965577f/jsbin/www-tampering.vflset/www-tampering.js
https://www.youtube.com/s/desktop/4965577f/jsbin/spf.vflset/spf.js
https://www.youtube.com/s/desktop/4965577f/jsbin/network.vflset/network.js
https://www.youtube.com/howyoutubeworks/
https://www.youtube.com/trends/
https://www.youtube.com/jobs/
https://www.youtube.com/kids/

Crawling Mode

Standard Mode

Standard crawling modality uses the standard go http library under the hood to handle HTTP requests/responses. This modality is much faster as it doesn't have the browser overhead. Still, it analyzes HTTP responses body as is, without any javascript or DOM rendering, potentially missing post-dom-rendered endpoints or asynchronous endpoint calls that might happen in complex web applications depending, for example, on browser-specific events.

Headless Mode

Headless mode hooks internal headless calls to handle HTTP requests/responses directly within the browser context. This offers two advantages:

The HTTP fingerprint (TLS and user agent) fully identify the client as a legitimate browser
Better coverage since the endpoints are discovered analyzing the standard raw response, as in the previous modality, and also the browser-rendered one with javascript enabled.

Headless crawling is optional and can be enabled using -headless option.

Here are other headless CLI options -

katana -h headless

Flags:
HEADLESS:
   -hl, -headless                    enable headless hybrid crawling (experimental)
   -sc, -system-chrome               use local installed chrome browser instead of katana installed
   -sb, -show-browser                show the browser on the screen with headless mode
   -ho, -headless-options string[]   start headless chrome with additional options
   -nos, -no-sandbox                 start headless chrome in --no-sandbox mode
   -cdd, -chrome-data-dir string     path to store chrome browser data
   -scp, -system-chrome-path string  use specified chrome browser for headless crawling
   -noi, -no-incognito               start headless chrome without incognito mode
   -cwu, -chrome-ws-url string       use chrome browser instance launched elsewhere with the debugger listening at this URL
   -xhr, -xhr-extraction             extract xhr requests
   -pls, -page-load-strategy string  page load strategy (heuristic, load, domcontentloaded, networkidle, none) (default "heuristic")
   -dwt, -dom-wait-time int          time in seconds to wait after page load when using domcontentloaded strategy (default 5)
   -csp, -captcha-solver-provider string  captcha solver provider (e.g. capsolver)
   -csk, -captcha-solver-key string       captcha solver provider api key

`-no-sandbox`

Runs headless chrome browser with no-sandbox option, useful when running as root user.

katana -u https://tesla.com -headless -no-sandbox

`-no-incognito`

Runs headless chrome browser without incognito mode, useful when using the local browser.

katana -u https://tesla.com -headless -no-incognito

To preserve cookies and other browser session data across runs, combine -no-incognito with -chrome-data-dir so Katana reuses your chosen Chrome profile directory instead of an isolated temporary one.

katana -u https://tesla.com -headless -no-incognito -chrome-data-dir /tmp/katana-profile

`-headless-options`

When crawling in headless mode, additional chrome options can be specified using -headless-options, for example -

katana -u https://tesla.com -headless -system-chrome -headless-options --disable-gpu,proxy-server=http://127.0.0.1:8080

`-page-load-strategy`

Controls how katana waits for pages to load in headless mode. Different strategies are useful for different types of web applications:

Strategy	Description
`heuristic`	(default) Smart waiting that adapts to page behavior - waits for load event, network idle, and DOM stability
`load`	Waits only for the browser's load event
`domcontentloaded`	Waits for DOMContentLoaded event plus additional time (configurable via `-dwt`) for JavaScript rendering
`networkidle`	Waits for network activity to stop
`none`	No waiting - returns immediately after navigation starts

katana -u https://tesla.com -headless -pls domcontentloaded

The domcontentloaded strategy is particularly useful for Single Page Applications (SPAs) that never fully complete loading due to continuous background requests (websockets, polling, etc.).

`-dom-wait-time`

When using the domcontentloaded page load strategy, this option specifies how many seconds to wait after the DOMContentLoaded event fires. This allows time for JavaScript to render interactive elements. Default is 5 seconds.

katana -u https://tesla.com -headless -pls domcontentloaded -dwt 10

Captcha Solving

Katana supports automatic captcha detection and solving during headless crawling. When a captcha page is encountered, katana identifies the captcha provider, solves it via an external service, and continues crawling.

Supported captcha types: reCAPTCHA v2, reCAPTCHA v3, reCAPTCHA Enterprise, Cloudflare Turnstile, hCaptcha

`-captcha-solver-provider`

Option to specify the captcha solver provider. Currently supported: capsolver.

`-captcha-solver-key`

API key for the captcha solver provider.

katana -u https://example.com -headless -csp capsolver -csk YOUR_API_KEY

The provider and key can also be set via environment variables:

export CAPTCHA_SOLVER_PROVIDER=capsolver
export CAPTCHA_SOLVER_KEY=YOUR_API_KEY
katana -u https://example.com -headless

Scope Control

Crawling can be endless if not scoped, as such katana comes with multiple support to define the crawl scope.

`-field-scope`

Most handy option to define scope with predefined field name, rdn being default option for field scope.

rdn - crawling scoped to root domain name and all subdomains (e.g. *example.com) (default)
fqdn - crawling scoped to given sub(domain) (e.g. www.example.com or api.example.com)
dn - crawling scoped to domain name keyword (e.g. example)

katana -u https://tesla.com -fs dn

`-crawl-scope`

For advanced scope control, -cs option can be used that comes with regex support.

katana -u https://tesla.com -cs login

For multiple in scope rules, file input with multiline string / regex can be passed.

$ cat in_scope.txt

login/
admin/
app/
wordpress/

katana -u https://tesla.com -cs in_scope.txt

`-crawl-out-scope`

For defining what not to crawl, -cos option can be used and also support regex input.

katana -u https://tesla.com -cos logout

For multiple out of scope rules, file input with multiline string / regex can be passed.

$ cat out_of_scope.txt

/logout
/log_out

katana -u https://tesla.com -cos out_of_scope.txt

`-no-scope`

Katana is default to scope *.domain, to disable this -ns option can be used and also to crawl the internet.

katana -u https://tesla.com -ns

`-display-out-scope`

As default, when scope option is used, it also applies for the links to display as output, as such external URLs are default to exclude and to overwrite this behavior, -do option can be used to display all the external URLs that exist in targets scoped URL / Endpoint.

katana -u https://tesla.com -do

Here is all the CLI options for the scope control -

katana -h scope

Flags:
SCOPE:
   -cs, -crawl-scope string[]       in scope url regex to be followed by crawler
   -cos, -crawl-out-scope string[]  out of scope url regex to be excluded by crawler
   -fs, -field-scope string         pre-defined scope field (dn,rdn,fqdn) (default "rdn")
   -ns, -no-scope                   disables host based default scope
   -do, -display-out-scope          display external endpoint from scoped crawling

Crawler Configuration

Katana comes with multiple options to configure and control the crawl as the way we want.

`-depth`

Option to define the depth to follow the urls for crawling, the more depth the more number of endpoint being crawled + time for crawl.

katana -u https://tesla.com -d 5

`-js-crawl`

Option to enable JavaScript file parsing + crawling the endpoints discovered in JavaScript files, disabled as default.

katana -u https://tesla.com -jc

`-crawl-duration`

Option to predefined crawl duration, disabled as default.

katana -u https://tesla.com -ct 2

`-known-files`

Option to enable crawling robots.txt and sitemap.xml file, disabled as default.

katana -u https://tesla.com -kf robotstxt,sitemapxml

`-automatic-form-fill`

Option to enable automatic form filling for known / unknown fields, known field values can be customized as needed by updating form config file at $HOME/.config/katana/form-config.yaml.

Automatic form filling is experimental feature.

katana -u https://tesla.com -aff

Form config values support DSL helper functions for dynamic data generation. All rand_* functions from the projectdiscovery/dsl library are available:

# $HOME/.config/katana/form-config.yaml
email: "rand_email()"
phone: "rand_phone()"
placeholder: "rand_first_name()"
password: 'rand_base(16, "")'
color: "#e66465"

`-filter-similar`

Option to filter crawling of similar looking URLs by normalizing variable path segments. This detects IDs, UUIDs, hashes, dates, and other dynamic values, and also learns repeating patterns at runtime. For example, /users/123 and /users/456 are treated as the same endpoint.

katana -u https://tesla.com -fsu

The promotion threshold (how many distinct values at a path position before it's treated as a parameter) can be tuned with -fst. Lower values are more aggressive (fewer URLs crawled), higher values are more permissive. Default is 10.

katana -u https://tesla.com -fsu -fst 5

`-max-domain-pages`

Option to limit the number of pages crawled per domain. Prevents any single domain from consuming the entire crawl budget, useful for large sites or crawler trap protection.

katana -u https://tesla.com -mdp 100

Knowledge Base Classification

Katana can enrich crawl results with a knowledge base — machine-learning classification of each crawled page powered by dit. When enabled, every response is classified by page type (e.g. login, error, captcha, parked) and any forms on the page are identified, with the result attached to the knowledgebase field of the JSONL output. This works across all engines (standard and headless).

Note: The classification model is downloaded automatically on first use to ~/.dit/model.json (from Hugging Face). This is a one-time, per-machine cost — subsequent runs reuse the cached model. No manual installation of dit is required.

`-knowledge-base`

Enable knowledge base classification. Page-type and form classification is added to the knowledgebase field of each result.

katana -u https://example.com -kb -jsonl

{
  "timestamp": "...",
  "request": { "...": "..." },
  "response": {
    "...": "...",
    "knowledgebase": {
      "PageType": "login",
      "Forms": [{ "type": "login", "fields": { "username": "username or email", "password": "password" } }]
    }
  }
}

`-filter-page-type`

Filter results to only the given page type(s). Enabling this implies -kb (the classifier is initialized automatically).

katana -u https://example.com -fpt login,error

`-kb-secrets`

Enable the secrets extractor in the knowledge base, surfacing detected secrets (API keys, tokens, etc.) under the secrets key. Add -kb-validate-secrets to validate detected secrets against their provider — note this sends live API calls.

katana -u https://example.com -kb-secrets

`-kb-endpoints`

Enable the endpoints extractor, which classifies requests as REST, GraphQL, SOAP, or XHR under the endpoints key.

katana -u https://example.com -kb-endpoints

Authenticated Crawling

Authenticated crawling involves including custom headers or cookies in HTTP requests to access protected resources. These headers provide authentication or authorization information, allowing you to crawl authenticated content / endpoint. You can specify headers directly in the command line or provide them as a file with katana to perform authenticated crawling.

Note: User needs to be manually perform the authentication and export the session cookie / header to file to use with katana.

`-headers`

Option to add a custom header or cookie to the request.

Syntax of headers in the HTTP specification

Here is an example of adding a cookie to the request:

katana -u https://tesla.com -H 'Cookie: usrsess=AmljNrESo'

It is also possible to supply headers or cookies as a file. For example:

$ cat cookie.txt

Cookie: PHPSESSIONID=XXXXXXXXX
X-API-KEY: XXXXX
TOKEN=XX

katana -u https://tesla.com -H cookie.txt

There are more options to configure when needed, here is all the config related CLI options -

katana -h config

Flags:
CONFIGURATION:
   -r, -resolvers string[]       list of custom resolver (file or comma separated)
   -d, -depth int                maximum depth to crawl (default 3)
   -jc, -js-crawl                enable endpoint parsing / crawling in javascript file
   -ct, -crawl-duration int      maximum duration to crawl the target for
   -kf, -known-files string      enable crawling of known files (all,robotstxt,sitemapxml)
   -mrs, -max-response-size int  maximum response size to read (default 9223372036854775807)
   -timeout int                  time to wait for request in seconds (default 10)
   -aff, -automatic-form-fill    enable automatic form filling (experimental)
   -fx, -form-extraction         enable extraction of form, input, textarea & select elements
   -retry int                    number of times to retry the request (default 1)
   -proxy string                 http/socks5 proxy to use
   -H, -headers string[]         custom header/cookie to include in request
   -config string                path to the katana configuration file
   -fc, -form-config string      path to custom form configuration file
   -flc, -field-config string    path to custom field configuration file
   -s, -strategy string          Visit strategy (depth-first, breadth-first) (default "depth-first")
   -iqp, -ignore-query-params    Ignore crawling same path with different query-param values
   -fsu, -filter-similar         filter crawling of similar looking URLs (e.g., /users/123 and /users/456)
   -fst, -filter-similar-threshold int  number of distinct values before a path position is treated as parameter (default 10)
   -mdp, -max-domain-pages int   maximum number of pages to crawl per domain (default unlimited)

Connecting to Active Browser Session

Katana can also connect to active browser session where user is already logged in and authenticated. and use it for crawling. The only requirement for this is to start browser with remote debugging enabled.

Here is an example of starting chrome browser with remote debugging enabled and using it with katana -

step 1) First Locate path of chrome executable

Operating System	Chromium Executable Location	Google Chrome Executable Location
Windows (64-bit)	`C:\Program Files (x86)\Google\Chromium\Application\chrome.exe`	`C:\Program Files (x86)\Google\Chrome\Application\chrome.exe`
Windows (32-bit)	`C:\Program Files\Google\Chromium\Application\chrome.exe`	`C:\Program Files\Google\Chrome\Application\chrome.exe`
macOS	`/Applications/Chromium.app/Contents/MacOS/Chromium`	`/Applications/Google Chrome.app/Contents/MacOS/Google Chrome`
Linux	`/usr/bin/chromium`	`/usr/bin/google-chrome`

step 2) Start chrome with remote debugging enabled and it will return websocker url. For example, on MacOS, you can start chrome with remote debugging enabled using following command -

$ /Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --remote-debugging-port=9222


DevTools listening on ws://127.0.0.1:9222/devtools/browser/c5316c9c-19d6-42dc-847a-41d1aeebf7d6

Now login to the website you want to crawl and keep the browser open.

step 3) Now use the websocket url with katana to connect to the active browser session and crawl the website

katana -headless -u https://tesla.com -cwu ws://127.0.0.1:9222/devtools/browser/c5316c9c-19d6-42dc-847a-41d1aeebf7d6 -no-incognito

Note: you can use -cdd option to specify custom chrome data directory to store browser data and cookies but that does not save session data if cookie is set to Session only or expires after certain time.

Filters

`-field`

Warning

Deprecated: use -output-template instead. The field flag is still supported for backward compatibility.

Katana comes with built in fields that can be used to filter the output for the desired information, -f option can be used to specify any of the available fields.

   -f, -field string  field to display in output (url,path,fqdn,rdn,rurl,qurl,qpath,file,key,value,kv,dir,udir)

Here is a table with examples of each field and expected output when used -

FIELD	DESCRIPTION	EXAMPLE
`url`	URL Endpoint	`https://admin.projectdiscovery.io/admin/login?user=admin&password=admin`
`qurl`	URL including query param	`https://admin.projectdiscovery.io/admin/login.php?user=admin&password=admin`
`qpath`	Path including query param	`/login?user=admin&password=admin`
`path`	URL Path	`https://admin.projectdiscovery.io/admin/login`
`fqdn`	Fully Qualified Domain name	`admin.projectdiscovery.io`
`rdn`	Root Domain name	`projectdiscovery.io`
`rurl`	Root URL	`https://admin.projectdiscovery.io`
`ufile`	URL with File	`https://admin.projectdiscovery.io/login.js`
`file`	Filename in URL	`login.php`
`key`	Parameter keys in URL	`user,password`
`value`	Parameter values in URL	`admin,admin`
`kv`	Keys=Values in URL	`user=admin&password=admin`
`dir`	URL Directory name	`/admin/`
`udir`	URL with Directory	`https://admin.projectdiscovery.io/admin/`

Here is an example of using field option to only display all the urls with query parameter in it -

katana -u https://tesla.com -f qurl -silent

https://shop.tesla.com/en_au?redirect=no
https://shop.tesla.com/en_nz?redirect=no
https://shop.tesla.com/product/men_s-raven-lightweight-zip-up-bomber-jacket?sku=1740250-00-A
https://shop.tesla.com/product/tesla-shop-gift-card?sku=1767247-00-A
https://shop.tesla.com/product/men_s-chill-crew-neck-sweatshirt?sku=1740176-00-A
https://www.tesla.com/about?redirect=no
https://www.tesla.com/about/legal?redirect=no
https://www.tesla.com/findus/list?redirect=no

Custom Fields

You can create custom fields to extract and store specific information from page responses using regex rules. These custom fields are defined using a YAML config file and are loaded from the default location at $HOME/.config/katana/field-config.yaml. Alternatively, you can use the -flc option to load a custom field config file from a different location. Here is example custom field.

- name: email
  type: regex
  regex:
  - '([a-zA-Z0-9._-]+@[a-zA-Z0-9._-]+\.[a-zA-Z0-9_-]+)'
  - '([a-zA-Z0-9+._-]+@[a-zA-Z0-9._-]+\.[a-zA-Z0-9_-]+)'

- name: phone
  type: regex
  regex:
  - '\d{3}-\d{8}|\d{4}-\d{7}'

When defining custom fields, following attributes are supported:

name (required)

The value of name attribute is used as the -field cli option value.

type (required)

The type of custom attribute, currently supported option - regex

part (optional)

The part of the response to extract the information from. The default value is response, which includes both the header and body. Other possible values are header and body.

group (optional)

You can use this attribute to select a specific matched group in regex, for example: group: 1

Running katana using custom field:

katana -u https://tesla.com -f email,phone

`-store-field`

To compliment field option which is useful to filter output at run time, there is -sf, -store-fields option which works exactly like field option except instead of filtering, it stores all the information on the disk under katana_field directory sorted by target url. Use -sfd or -store-field-dir to store data in a different location.

katana -u https://tesla.com -sf key,fqdn,qurl -silent

$ ls katana_field/

https_www.tesla.com_fqdn.txt
https_www.tesla.com_key.txt
https_www.tesla.com_qurl.txt

The -store-field option can be useful for collecting information to build a targeted wordlist for various purposes, including but not limited to:

Identifying the most commonly used parameters
Discovering frequently used paths
Finding commonly used files
Identifying related or unknown subdomains

Katana Filters

`-extension-match`

Crawl output can be easily matched for specific extension using -em option to ensure to display only output containing given extension.

katana -u https://tesla.com -silent -em js,jsp,json

Use the special value none to also include URLs without a file extension in the output:

katana -u https://tesla.com -silent -em js,jsp,json,none

`-extension-filter`

Crawl output can be easily filtered for specific extension using -ef option which ensure to remove all the urls containing given extension.

katana -u https://tesla.com -silent -ef css,txt,md

`-no-default-ext-filter`

Katana filters several extensions by default. This can be disabled with the -ndef option.

katana -u https://tesla.com -silent -ndef

`-match-regex`

The -match-regex or -mr flag allows you to filter output URLs using regular expressions. When using this flag, only URLs that match the specified regular expression will be printed in the output.

katana -u https://tesla.com -mr 'https://shop\.tesla\.com/*' -silent

`-filter-regex`

The -filter-regex or -fr flag allows you to filter output URLs using regular expressions. When using this flag, it will skip the URLs that are match the specified regular expression.

katana -u https://tesla.com -fr 'https://www\.tesla\.com/*' -silent

Advance Filtering

Katana supports DSL-based expressions for advanced matching and filtering capabilities:

To match endpoints with a 200 status code:

katana -u https://www.hackerone.com -mdc 'status_code == 200'

To match endpoints that contain "default" and have a status code other than 403:

katana -u https://www.hackerone.com -mdc 'contains(endpoint, "default") && status_code != 403'

To match endpoints with PHP technologies:

katana -u https://www.hackerone.com -mdc 'contains(to_lower(technologies), "php")'

To filter out endpoints running on Cloudflare:

katana -u https://www.hackerone.com -fdc 'contains(to_lower(technologies), "cloudflare")'

DSL functions can be applied to any keys in the jsonl output. For more information on available DSL functions, please visit the dsl project.

Here are additional filter options -

katana -h filter

Flags:
FILTER:
   -mr, -match-regex string[]             regex or list of regex to match on output url (cli, file)
   -fr, -filter-regex string[]            regex or list of regex to filter on output url (cli, file)
   -f, -field string                      field to display in output (url,path,fqdn,rdn,rurl,qurl,qpath,file,ufile,key,value,kv,dir,udir)
   -sf, -store-field string               field to store in per-host output (url,path,fqdn,rdn,rurl,qurl,qpath,file,ufile,key,value,kv,dir,udir)
   -em, -extension-match string[]         match output for given extension (eg, -em php,html,js,none)
   -ef, -extension-filter string[]        filter output for given extension (eg, -ef png,css)
   -ndef, -no-default-ext-filter bool     remove default extensions from the filter list
   -mdc, -match-condition string          match response with dsl based condition
   -fdc, -filter-condition string         filter response with dsl based condition
   -duf, -disable-unique-filter           disable duplicate content filtering

Rate Limit

It's easy to get blocked / banned while crawling if not following target websites limits, katana comes with multiple option to tune the crawl to go as fast / slow we want.

`-delay`

option to introduce a delay in seconds between each new request katana makes while crawling, disabled as default.

katana -u https://tesla.com -delay 20

`-concurrency`

option to control the number of urls per target to fetch at the same time.

katana -u https://tesla.com -c 20

`-parallelism`

option to define number of target to process at same time from list input.

katana -u https://tesla.com -p 20

`-rate-limit`

Maximum requests per second, applied globally across all hosts.

katana -u https://tesla.com -rl 100

`-rate-limit-minute`

Maximum requests per minute, applied globally across all hosts.

katana -u https://tesla.com -rlm 500

`-host-rate-limit`

Maximum requests per second per host. Each host gets its own rate limit bucket, so a slow host won't throttle fast ones. Replaces the global rate limit when set. Katana also backs off automatically with exponential delay and jitter when a host returns 429 or 503.

katana -u https://tesla.com -hrl 50

`-host-rate-limit-minute`

Maximum requests per minute per host.

katana -u https://tesla.com -hrlm 200

Here is all long / short CLI options for rate limit control -

katana -h rate-limit

Flags:
RATE-LIMIT:
   -c, -concurrency int          number of concurrent fetchers to use (default 10)
   -p, -parallelism int          number of concurrent inputs to process (default 10)
   -rd, -delay int               request delay between each request in seconds
   -rl, -rate-limit int          maximum requests to send per second (default 150)
   -rlm, -rate-limit-minute int  maximum number of requests to send per minute
   -hrl, -host-rate-limit int    maximum requests to send per second per host
   -hrlm, -host-rate-limit-minute int  maximum number of requests to send per minute per host

Output

Katana support both file output in plain text format as well as JSON which includes additional information like, source, tag, and attribute name to co-related the discovered endpoint.

`-output`

By default, katana outputs the crawled endpoints in plain text format. The results can be written to a file by using the -output option.

katana -u https://example.com -no-scope -output example_endpoints.txt

`-output-template`

The -output-template option allows you to customize the output format using template, providing flexibility in defining the output structure. This option replaces the deprecated -field flag for filtering output. Instead of relying on predefined fields, you can specify a custom template directly in the command line to control how the extracted data is presented.

Example of using the -output-template option:

katana -u https://example.com -output-template '{{email}} - {{url}}'

In this example, email represents a custom field that extracts and displays email addresses found within the source url.

Note

If a specified field does not exist or does not contain a value, it will simply be omitted from the output.

This option can effectively structure the output in a way that best suits your use case, making data extraction more intuitive and customizable.

`-jsonl`

katana -u https://example.com -jsonl | jq .

{
  "timestamp": "2023-03-20T16:23:58.027559+05:30",
  "request": {
    "method": "GET",
    "endpoint": "https://example.com",
    "raw": "GET / HTTP/1.1\r\nHost: example.com\r\nUser-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 11_1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/87.0.4280.88 Safari/537.36\r\nAccept-Encoding: gzip\r\n\r\n"
  },
  "response": {
    "status_code": 200,
    "headers": {
      "accept_ranges": "bytes",
      "expires": "Mon, 27 Mar 2023 10:53:58 GMT",
      "last_modified": "Thu, 17 Oct 2019 07:18:26 GMT",
      "content_type": "text/html; charset=UTF-8",
      "server": "ECS (dcb/7EA3)",
      "vary": "Accept-Encoding",
      "etag": "\"3147526947\"",
      "cache_control": "max-age=604800",
      "x_cache": "HIT",
      "date": "Mon, 20 Mar 2023 10:53:58 GMT",
      "age": "331239"
    },
    "body": "<!doctype html>\n<html>\n<head>\n    <title>Example Domain</title>\n\n    <meta charset=\"utf-8\" />\n    <meta http-equiv=\"Content-type\" content=\"text/html; charset=utf-8\" />\n    <meta name=\"viewport\" content=\"width=device-width, initial-scale=1\" />\n    <style type=\"text/css\">\n    body {\n        background-color: #f0f0f2;\n        margin: 0;\n        padding: 0;\n        font-family: -apple-system, system-ui, BlinkMacSystemFont, \"Segoe UI\", \"Open Sans\", \"Helvetica Neue\", Helvetica, Arial, sans-serif;\n        \n    }\n    div {\n        width: 600px;\n        margin: 5em auto;\n        padding: 2em;\n        background-color: #fdfdff;\n        border-radius: 0.5em;\n        box-shadow: 2px 3px 7px 2px rgba(0,0,0,0.02);\n    }\n    a:link, a:visited {\n        color: #38488f;\n        text-decoration: none;\n    }\n    @media (max-width: 700px) {\n        div {\n            margin: 0 auto;\n            width: auto;\n        }\n    }\n    </style>    \n</head>\n\n<body>\n<div>\n    <h1>Example Domain</h1>\n    <p>This domain is for use in illustrative examples in documents. You may use this\n    domain in literature without prior coordination or asking for permission.</p>\n    <p><a href=\"https://www.iana.org/domains/example\">More information...</a></p>\n</div>\n</body>\n</html>\n",
    "technologies": [
      "Azure",
      "Amazon ECS",
      "Amazon Web Services",
      "Docker",
      "Azure CDN"
    ],
    "raw": "HTTP/1.1 200 OK\r\nContent-Length: 1256\r\nAccept-Ranges: bytes\r\nAge: 331239\r\nCache-Control: max-age=604800\r\nContent-Type: text/html; charset=UTF-8\r\nDate: Mon, 20 Mar 2023 10:53:58 GMT\r\nEtag: \"3147526947\"\r\nExpires: Mon, 27 Mar 2023 10:53:58 GMT\r\nLast-Modified: Thu, 17 Oct 2019 07:18:26 GMT\r\nServer: ECS (dcb/7EA3)\r\nVary: Accept-Encoding\r\nX-Cache: HIT\r\n\r\n<!doctype html>\n<html>\n<head>\n    <title>Example Domain</title>\n\n    <meta charset=\"utf-8\" />\n    <meta http-equiv=\"Content-type\" content=\"text/html; charset=utf-8\" />\n    <meta name=\"viewport\" content=\"width=device-width, initial-scale=1\" />\n    <style type=\"text/css\">\n    body {\n        background-color: #f0f0f2;\n        margin: 0;\n        padding: 0;\n        font-family: -apple-system, system-ui, BlinkMacSystemFont, \"Segoe UI\", \"Open Sans\", \"Helvetica Neue\", Helvetica, Arial, sans-serif;\n        \n    }\n    div {\n        width: 600px;\n        margin: 5em auto;\n        padding: 2em;\n        background-color: #fdfdff;\n        border-radius: 0.5em;\n        box-shadow: 2px 3px 7px 2px rgba(0,0,0,0.02);\n    }\n    a:link, a:visited {\n        color: #38488f;\n        text-decoration: none;\n    }\n    @media (max-width: 700px) {\n        div {\n            margin: 0 auto;\n            width: auto;\n        }\n    }\n    </style>    \n</head>\n\n<body>\n<div>\n    <h1>Example Domain</h1>\n    <p>This domain is for use in illustrative examples in documents. You may use this\n    domain in literature without prior coordination or asking for permission.</p>\n    <p><a href=\"https://www.iana.org/domains/example\">More information...</a></p>\n</div>\n</body>\n</html>\n"
  }
}

`-store-response`

The -store-response option allows for writing all crawled endpoint requests and responses to a text file. When this option is used, text files including the request and response will be written to the katana_response directory. If you would like to specify a custom directory, you can use the -store-response-dir option.

katana -u https://example.com -no-scope -store-response

$ cat katana_response/index.txt

katana_response/example.com/327c3fda87ce286848a574982ddd0b7c7487f816.txt https://example.com (200 OK)
katana_response/www.iana.org/bfc096e6dd93b993ca8918bf4c08fdc707a70723.txt http://www.iana.org/domains/reserved (200 OK)

Note:

-store-response option is not supported in -headless mode.

`-list-output-fields`

The -list-output-fields or -lof flag displays all available fields that can be used in JSONL output format. This is useful for understanding what data is available when using custom output templates or when excluding specific fields.

katana -lof

`-exclude-output-fields`

The -exclude-output-fields or -eof flag allows you to exclude specific fields from the JSONL output. This is useful for reducing output size or focusing on specific data by removing unwanted fields.

katana -u https://example.com -jsonl -eof raw,body

Here are additional CLI options related to output -

katana -h output

OUTPUT:
   -o, -output string                file to write output to
   -sr, -store-response              store http requests/responses
   -srd, -store-response-dir string  store http requests/responses to custom directory
   -lof, -list-output-fields         list available fields for jsonl output format
   -eof, -exclude-output-fields      exclude fields from jsonl output
   -j, -json                         write output in JSON Lines format
   -nc, -no-color                    disable output content coloring (ANSI escape codes)
   -silent                           display output only
   -v, -verbose                      display verbose output
   -version                          display project version

Katana as a library

katana can be used as a library by creating an instance of the Option struct and populating it with the same options that would be specified via CLI. Using the options you can create crawlerOptions and so standard or hybrid crawler. crawler.Crawl method should be called to crawl the input.

package main

import (
	"math"

	"github.com/projectdiscovery/gologger"
	"github.com/projectdiscovery/katana/pkg/engine/standard"
	"github.com/projectdiscovery/katana/pkg/output"
	"github.com/projectdiscovery/katana/pkg/types"
)

func main() {
	options := &types.Options{
		MaxDepth:     3,             // Maximum depth to crawl
		FieldScope:   "rdn",         // Crawling Scope Field
		BodyReadSize: math.MaxInt,   // Maximum response size to read
		Timeout:      10,            // Timeout is the time to wait for request in seconds
		Concurrency:  10,            // Concurrency is the number of concurrent crawling goroutines
		Parallelism:  10,            // Parallelism is the number of urls processing goroutines
		Delay:        0,             // Delay is the delay between each crawl requests in seconds
		RateLimit:    150,           // Maximum requests to send per second
		Strategy:     "depth-first", // Visit strategy (depth-first, breadth-first)
		OnResult: func(result output.Result) { // Callback function to execute for result
			gologger.Info().Msg(result.Request.URL)
		},
	}
	crawlerOptions, err := types.NewCrawlerOptions(options)
	if err != nil {
		gologger.Fatal().Msg(err.Error())
	}
	defer crawlerOptions.Close()
	crawler, err := standard.New(crawlerOptions)
	if err != nil {
		gologger.Fatal().Msg(err.Error())
	}
	defer crawler.Close()
	var input = "https://www.hackerone.com"
	err = crawler.Crawl(input)
	if err != nil {
		gologger.Warning().Msgf("Could not crawl %s: %s", input, err.Error())
	}
}

Reporting Issues & Feature Requests

To maintain issue tracking and improve triage efficiency:

All reports start as GitHub Discussions

Bug Reports → Start a Q&A Discussion
Feature Requests → Start an Ideas Discussion
Questions → Start a Q&A Discussion

Why Discussions First?

Community can help with quick questions and troubleshooting
Better triage - confirmed bugs/features become tracked issues
Cleaner issue tracker - focus on actionable items only

Maintainers will convert discussions to issues when appropriate after proper review.

katana is made with ❤️ by the projectdiscovery team and distributed under MIT License.

ollama/ollama

Get up and running with Kimi-K2.6, GLM-5.2, MiniMax, DeepSeek, gpt-oss, Qwen, Gemma and other models.

https://ollama.com

Ollama

Start building with open models.

Download

macOS

curl -fsSL https://ollama.com/install.sh | sh

or download manually

Windows

irm https://ollama.com/install.ps1 | iex

or download manually

Linux

curl -fsSL https://ollama.com/install.sh | sh

Manual install instructions

Docker

The official Ollama Docker image ollama/ollama is available on Docker Hub.

Libraries

Community

Get started

ollama

You'll be prompted to run a model or connect Ollama to your existing agents or applications such as Claude Code, OpenClaw, OpenCode , Codex, Copilot, and more.

Coding

To launch a specific integration:

ollama launch claude

Supported integrations include Claude Code, Codex, Copilot CLI, DeepSeek Harness, Droid, and OpenCode.

AI assistant

Use OpenClaw to turn Ollama into a personal AI assistant across WhatsApp, Telegram, Slack, Discord, and more:

ollama launch openclaw

Chat with a model

Run and chat with Gemma 4:

ollama run gemma4

See ollama.com/library for the full list.

See the quickstart guide for more details.

REST API

Ollama has a REST API for running and managing models.

curl http://localhost:11434/api/chat -d '{
  "model": "gemma4",
  "messages": [{
    "role": "user",
    "content": "Why is the sky blue?"
  }],
  "stream": false
}'

See the API documentation for all endpoints.

Python

pip install ollama

from ollama import chat

response = chat(model='gemma4', messages=[
  {
    'role': 'user',
    'content': 'Why is the sky blue?',
  },
])
print(response.message.content)

JavaScript

npm i ollama

import ollama from "ollama";

const response = await ollama.chat({
  model: "gemma4",
  messages: [{ role: "user", content: "Why is the sky blue?" }],
});
console.log(response.message.content);

Supported backends

llama.cpp project founded by Georgi Gerganov.

Documentation

Community Integrations

Want to add your project? Open a pull request.

Chat Interfaces

Web

Open WebUI - Extensible, self-hosted AI interface
Onyx - Connected AI workspace
LibreChat - Enhanced ChatGPT clone with multi-provider support
Lobe Chat - Modern chat framework with plugin ecosystem (docs)
NextChat - Cross-platform ChatGPT UI (docs)
Perplexica - AI-powered search engine, open-source Perplexity alternative
big-AGI - AI suite for professionals
Lollms WebUI - Multi-model web interface
ChatOllama - Chatbot with knowledge bases
Bionic GPT - On-premise AI platform
Chatbot UI - ChatGPT-style web interface
Hollama - Minimal web interface
Chatbox - Desktop and web AI client
chat - Chat web app for teams
Ollama RAG Chatbot - Chat with multiple PDFs using RAG
Tkinter-based client - Python desktop client

Desktop

Dify.AI - LLM app development platform
AnythingLLM - All-in-one AI app for Mac, Windows, and Linux
Maid - Cross-platform mobile and desktop client
Witsy - AI desktop app for Mac, Windows, and Linux
Cherry Studio - Multi-provider desktop client
Ollama App - Multi-platform client for desktop and mobile
PyGPT - AI desktop assistant for Linux, Windows, and Mac
Alpaca - GTK4 client for Linux and macOS
SwiftChat - Cross-platform including iOS, Android, and Apple Vision Pro
Enchanted - Native macOS and iOS client
RWKV-Runner - Multi-model desktop runner
Ollama Grid Search - Evaluate and compare models
macai - macOS client for Ollama and ChatGPT
AI Studio - Multi-provider desktop IDE
Reins - Parameter tuning and reasoning model support
ConfiChat - Privacy-focused with optional encryption
LLocal.in - Electron desktop client
MindMac - AI chat client for Mac
Msty - Multi-model desktop client
BoltAI for Mac - AI chat client for Mac
IntelliBar - AI-powered assistant for macOS
Kerlig AI - AI writing assistant for macOS
Hillnote - Markdown-first AI workspace
Perfect Memory AI - Productivity AI personalized by screen and meeting history

Mobile

Ollama Android Chat - One-click Ollama on Android

SwiftChat, Enchanted, Maid, Ollama App, Reins, and ConfiChat listed above also support mobile platforms.

Code Editors & Development

Cline - VS Code extension for multi-file/whole-repo coding
Continue - Open-source AI code assistant for any IDE
Void - Open source AI code editor, Cursor alternative
Copilot for Obsidian - AI assistant for Obsidian
twinny - Copilot and Copilot chat alternative
gptel Emacs client - LLM client for Emacs
Ollama Copilot - Use Ollama as GitHub Copilot
Obsidian Local GPT - Local AI for Obsidian
Ellama Emacs client - LLM tool for Emacs
orbiton - Config-free text editor with Ollama tab completion
AI ST Completion - Sublime Text 4 AI assistant
VT Code - Rust-based terminal coding agent with Tree-sitter
QodeAssist - AI coding assistant for Qt Creator
AI Toolkit for VS Code - Microsoft-official VS Code extension
Open Interpreter - Natural language interface for computers

Libraries & SDKs

LiteLLM - Unified API for 100+ LLM providers
Semantic Kernel - Microsoft AI orchestration SDK
LangChain4j - Java LangChain (example)
LangChainGo - Go LangChain (example)
Spring AI - Spring framework AI support (docs)
LangChain and LangChain.js with example
Ollama for Ruby - Ruby LLM library
any-llm - Unified LLM interface by Mozilla
OllamaSharp for .NET - .NET SDK
LangChainRust - Rust LangChain (example)
Agents-Flex for Java - Java agent framework (example)
Elixir LangChain - Elixir LangChain
Ollama-rs for Rust - Rust SDK
LangChain for .NET - .NET LangChain (example)
chromem-go - Go vector database with Ollama embeddings (example)
LangChainDart - Dart LangChain
LlmTornado - Unified C# interface for multiple inference APIs
Ollama4j for Java - Java SDK
Ollama for Laravel - Laravel integration
Ollama for Swift - Swift SDK
LlamaIndex and LlamaIndexTS - Data framework for LLM apps
Haystack - AI pipeline framework
Firebase Genkit - Google AI framework
Ollama-hpp for C++ - C++ SDK
PromptingTools.jl - Julia LLM toolkit (example)
Ollama for R - rollama - R SDK
Portkey - AI gateway
Testcontainers - Container-based testing
LLPhant - PHP AI framework

Frameworks & Agents

AutoGPT - Autonomous AI agent platform
crewAI - Multi-agent orchestration framework
Strands Agents - Model-driven agent building by AWS
Cheshire Cat - AI assistant framework
any-agent - Unified agent framework interface by Mozilla
Stakpak - Open source DevOps agent
Hexabot - Conversational AI builder
Neuro SAN - Multi-agent orchestration (docs)

RAG & Knowledge Bases

RAGFlow - RAG engine based on deep document understanding
R2R - Open-source RAG engine
MaxKB - Ready-to-use RAG chatbot
Minima - On-premises or fully local RAG
Chipper - AI interface with Haystack RAG
ARGO - RAG and deep research on Mac/Windows/Linux
Archyve - RAG-enabling document library
Casibase - AI knowledge base with RAG and SSO
BrainSoup - Native client with RAG and multi-agent automation

Bots & Messaging

LangBot - Multi-platform messaging bots with agents and RAG
AstrBot - Multi-platform chatbot with RAG and plugins
Discord-Ollama Chat Bot - TypeScript Discord bot
Ollama Telegram Bot - Telegram bot
LLM Telegram Bot - Telegram bot for roleplay

Terminal & CLI

aichat - All-in-one LLM CLI with Shell Assistant, RAG, and AI tools
oterm - Terminal client for Ollama
gollama - Go-based model manager for Ollama
tlm - Local shell copilot
tenere - TUI for LLMs
ParLlama - TUI for Ollama
llm-ollama - Plugin for Datasette's LLM CLI
ShellOracle - Shell command suggestions
LLM-X - Progressive web app for LLMs
cmdh - Natural language to shell commands
VT - Minimal multimodal AI chat app

Productivity & Apps

AppFlowy - AI collaborative workspace, self-hostable Notion alternative
Screenpipe - 24/7 screen and mic recording with AI-powered search
Vibe - Transcribe and analyze meetings
Page Assist - Chrome extension for AI-powered browsing
NativeMind - Private, on-device browser AI assistant
Ollama Fortress - Security proxy for Ollama
1Panel - Web-based Linux server management
Writeopia - Text editor with Ollama integration
QA-Pilot - GitHub code repository understanding
Raycast extension - Ollama in Raycast
Painting Droid - Painting app with AI integrations
Serene Pub - AI roleplaying app
Mayan EDMS - Document management with Ollama workflows
TagSpaces - File management with AI tagging

Observability & Monitoring

Opik - Debug, evaluate, and monitor LLM applications
OpenLIT - OpenTelemetry-native monitoring for Ollama and GPUs
Lunary - LLM observability with analytics and PII masking
Langfuse - Open source LLM observability
HoneyHive - AI observability and evaluation for agents
MLflow Tracing - Open source LLM observability

Database & Embeddings

pgai - PostgreSQL as a vector database (guide)
MindsDB - Connect Ollama with 200+ data platforms
chromem-go - Embeddable vector database for Go (example)
Kangaroo - AI-powered SQL client

Infrastructure & Deployment

Cloud

Google Cloud
Fly.io
Koyeb
Harbor - Containerized LLM toolkit with Ollama as default backend

Package Managers

Gentleman-Programming/engram

Persistent memory system for AI coding agents. Agent-agnostic Go binary with SQLite + FTS5, MCP server, HTTP API, CLI, and TUI.

https://engram.gentlemanprogramming.com/

Persistent memory for AI coding agents
One brain. Local or cloud. Agent-agnostic, single binary, zero dependencies.

Website • Gentle-AI • Gentle-AI Wiki

Installation • Release Policy • Engram Cloud • Agent Setup • Codebase Guide • Architecture • Plugins • Team Usage • Contributing • Full Docs

engram /ˈen.ɡræm/ — neuroscience: the physical trace of a memory in the brain.

Your AI coding agent forgets everything when the session ends. Engram gives it a brain.

A Go binary with SQLite + FTS5 full-text search, exposed through CLI, HTTP API, MCP, and an interactive TUI. It works with any MCP-compatible agent, including Claude Code, OpenCode, Gemini CLI, Codex, VS Code (Copilot), Antigravity, Cursor, and Windsurf.

No Node.js, Python, or Docker is required: one binary, one SQLite file.

Agent (Claude Code / OpenCode / Gemini CLI / Codex / VS Code / Antigravity / ...)
    ↓ MCP stdio
Engram (single Go binary)
    ↓
SQLite + FTS5 (~/.engram/engram.db)

For agents

Treat Engram as a curated project memory, not a transcript sink. Use this operating contract throughout the session.

Orient before writing. Start with mem_current_project to confirm the resolved project and its source. At the start of related work, use mem_context and mem_search to recover the relevant history.
Search before repeating. Before revisiting a decision, bug, convention, or request that may already be known, search with focused terms. Search results are previews, not the complete record.
Retrieve progressively. Use mem_search for candidates, mem_timeline when surrounding session context matters, and mem_get_observation before relying on a full observation.
Save significant knowledge deliberately. Save completed bug fixes, decisions, discoveries, configuration changes, patterns, and durable user constraints with mem_save. Do not capture raw tool output or every conversational turn.
Keep evolving knowledge stable. Give an evolving topic a stable topic_key such as architecture/auth-model; reuse it to update that topic rather than creating competing memories. Use mem_suggest_topic_key when the key is unclear.
Leave a handoff. Before ending a session, save a mem_session_summary with the goal, instructions, discoveries, accomplished work, next steps, and relevant files.
Recover after compaction. Persist the compacted handoff with mem_session_summary first. Then call mem_context to recover recent session history before continuing.

A useful memory is structured

**What**: Added retry-safe upload handling.
**Why**: Retries could create duplicate records.
**Where**: internal/upload/handler.go
**Learned**: Reuse the request id as the idempotency key.

Use a short, searchable title and a fitting type with that content. The full Memory Protocol defines the durable-save rules and session-summary shape.

Choose MCP tools by intent

Tool availability can vary by MCP profile. Start with the intent, then use your client's tool discovery mechanism (such as ToolSearch) only when a deferred tool is needed.

Intent	Start with
Confirm the project and recover recent work	`mem_current_project`, `mem_context`
Find prior knowledge without repeating work	`mem_search`
Inspect a result in enough detail	`mem_timeline`, `mem_get_observation`
Save or refine durable knowledge	`mem_save`, `mem_update`, `mem_suggest_topic_key`
Preserve the user's request	`mem_save_prompt`
Hand off or close a session	`mem_session_summary`, `mem_session_start`, `mem_session_end`
Review stale knowledge or memory relationships	`mem_review`, `mem_judge`, `mem_compare`
Diagnose project or store state	`mem_doctor`

For parameters and the complete, current tool reference, see the full documentation.

Quick start

Install

For production use and security support, install the latest stable release from GitHub Releases. Release candidates are prerelease validation and feedback builds; choose one only when you accept prerelease risk. See the Release Policy before upgrading.

Homebrew remains on the stable v1.20.0 line:

brew install gentleman-programming/tap/engram

For Windows, Linux, source builds, and all installation methods, see Installation.

Set up your agent

Run the setup command for the agent you use, then restart that agent. engram setup writes the applicable MCP and integration configuration; it does not require you to start a server for the usual stdio-only setup.

Agent	Setup
Claude Code	`claude plugin marketplace add Gentleman-Programming/engram && claude plugin install engram`
Pi	`engram setup pi`
OpenCode	`engram setup opencode`
Gemini CLI	`engram setup gemini-cli`
Codex	`engram setup codex`
Antigravity CLI	`engram setup antigravity-cli`
Windsurf	`engram setup windsurf`
Qwen Code	`engram setup qwen`
Kiro	`engram setup kiro`
Cursor	`engram setup cursor`
VS Code (Copilot)	`engram setup vscode-copilot`
Kilo Code	`engram setup kilocode`
Another MCP-compatible agent	Manual MCP setup

See Agent Setup for per-agent configuration, plugin behavior, manual MCP setup, compaction resilience, and troubleshooting. Pi users can also find the package at gentle-engram.

Local first, portable when needed

Engram keeps memory local by default. The local SQLite database is authoritative; Git Sync exports portable compressed chunks for sharing across machines, and Engram Cloud is optional, project-scoped replication/shared access with browser visibility.

Need	Start here
Local memory and the runtime model	Architecture
Share memory with Git	Git Sync reference
Use optional Cloud replication	Engram Cloud
Diagnose or recover Cloud operations	Cloud troubleshooting

For an existing local database, use the guided upgrade sequence. If the dry run reports changes, apply them before bootstrap; otherwise continue directly to bootstrap.

engram cloud upgrade doctor --project <project>
engram cloud upgrade repair --project <project> --dry-run
engram cloud upgrade repair --project <project> --apply # only when the dry run reports changes
engram cloud upgrade bootstrap --project <project>
engram cloud upgrade status --project <project>

See the Cloud upgrade reference for apply, rollback, and recovery details.

Project-aware reads

Project-aware reads use the canonical current project when no selector is supplied: an explicit project, then ENGRAM_PROJECT, then cwd detection. Use --all in the CLI or all_projects=true in HTTP for an intentional global read; do not combine either with an explicit project. engram context retains its positional project as an alias for --project. GET /sync/status supports one resolved project and rejects all_projects=true because its provider cannot aggregate status.

Terminal UI

engram tui

Navigate with j/k, use Enter to drill in, c to copy content to the clipboard, / to search, and Esc to go back. The TUI uses the Catppuccin Mocha theme.

Documentation

Doc	Description
Installation	Platform support and all installation methods
Release Policy	Stable, RC, security-support, upgrade, and rollback guidance
Agent Setup	Per-agent configuration and compaction resilience
Intended Usage	The human mental model for using Engram
Architecture	Memory model, tool behavior, and project structure
Codebase Guide	Repository structure, flows, and implementation landmarks
Plugins	OpenCode and Claude Code plugin details
Team Usage	Shared-memory conventions
Engram Cloud	Cloud quickstart, deployment, and technical links
Doctor	Operational diagnosis and repair workflows
Binary self-testing	Isolated reliability and performance checks for released binaries
Beta Testing	Isolated beta testing flows and cleanup guidance
Comparison	Engram compared with claude-mem
Obsidian Brain	Export memories as an Obsidian knowledge graph (beta)
Full Docs	Complete CLI, environment, API, and operational reference

Dashboard contributors: if you modify .templ files in internal/cloud/dashboard/, run make templ to regenerate before committing. See Dashboard templ regeneration.

Contributing

Every change starts with an approved issue. See Contributing for the issue-first workflow, labels, review requirements, and contributor standards.

Trademark notice: The Engram names and logos are trademarks of Alan Buscaglia. The MIT License applies to the code; it does not permit implying endorsement or official affiliation. See TRADEMARKS.md.

License

MIT

Inspired by claude-mem — but agent-agnostic, simpler, and built different.

Contributors

google/go-github

Go library for accessing the GitHub v3 API

https://pkg.go.dev/github.com/google/go-github/v89/github

go-github

go-github is a Go client library for accessing the GitHub API v3.

go-github tracks Go's version support policy supporting any minor version of the latest two major releases of Go and the go directive in go.mod reflects that. We do our best not to break older versions of Go if we don't have to, but we don't explicitly test older versions and as of Go 1.26 the go directive in go.mod declares a hard required minimum version of Go to use with this module and this must be greater than or equal to the go line of all dependencies so go-github will require the N-1 major release of Go by default.

Development

If you're interested in using the GraphQL API v4, the recommended library is shurcooL/githubv4.

Installation

go-github is compatible with modern Go releases in module mode, with Go installed:

go get github.com/google/go-github/v91

will resolve and add the package to the current development module, along with its dependencies.

Alternatively the same can be achieved if you use import in a package:

import "github.com/google/go-github/v91/github"

and run go get without parameters.

Finally, to use the top-of-trunk version of this repo, use the following command:

go get github.com/google/go-github/v91@master

To discover all the changes that have occurred since a prior release, you can first clone the repo, then run (for example):

go run tools/gen-release-notes/main.go --tag v91.0.0

Usage

import "github.com/google/go-github/v91/github"

Construct a new GitHub client, then use the various services on the client to access different parts of the GitHub API. For example:

client, err := github.NewClient()
if err != nil {
	// Handle error.
}

// list all organizations for user "willnorris"
orgs, _, err := client.Organizations.List(context.Background(), "willnorris", nil)

Some API methods have optional parameters that can be passed. For example:

client, err := github.NewClient()
if err != nil {
	// Handle error.
}

// list public repositories for org "github"
opt := &github.RepositoryListByOrgOptions{Type: "public"}
repos, _, err := client.Repositories.ListByOrg(context.Background(), "github", opt)

The services of a client divide the API into logical chunks and correspond to the structure of the GitHub API documentation.

NOTE: Using the context package, one can easily pass cancellation signals and deadlines to various services of the client for handling a request. In case there is no context available, then context.Background() can be used as a starting point.

For more sample code snippets, head over to the example directory.

Authentication

Use the github.WithAuthToken options method to configure your client to authenticate using an OAuth token (for example, a personal access token). This is what is needed for a majority of use cases aside from GitHub Apps.

client, err := github.NewClient(github.WithAuthToken("... your access token ..."))
if err != nil {
	// Handle error.
}

To support more advanced use cases; you can use the github.WithTransport option to provide a custom http.RoundTripper that handles authentication for you, or the github.WithHTTPClient option to provide a custom http.Client. As an example; you can use the oauth2.Transport from the golang.org/x/oauth2 package to handle OAuth token refreshing for you.

Note that when using an authenticated Client, all calls made by the client will include the specified OAuth token. Therefore, authenticated clients should almost never be shared between different users.

For API methods that require HTTP Basic Authentication, use the BasicAuthTransport.

As a GitHub App

GitHub Apps authentication can be provided by different pkgs like bradleyfalzon/ghinstallation or jferrl/go-githubauth.

Note: Most endpoints (ex. GET /rate_limit) require access token authentication while a few others (ex. GET /app/hook/deliveries) require JWT authentication.

ghinstallation provides Transport, which implements http.RoundTripper to provide authentication as an installation for GitHub Apps.

Here is an example of how to authenticate as a GitHub App using the ghinstallation package:

import (
	"net/http"

	"github.com/bradleyfalzon/ghinstallation/v2"
	"github.com/google/go-github/v91/github"
)

func main() {
	// Wrap the shared transport for use with the integration ID 1 authenticating with installation ID 99.
	itr, err := ghinstallation.NewKeyFromFile(http.DefaultTransport, 1, 99, "2016-10-19.private-key.pem")

	// Or for endpoints that require JWT authentication
	// itr, err := ghinstallation.NewAppsTransportKeyFromFile(http.DefaultTransport, 1, "2016-10-19.private-key.pem")

	if err != nil {
		// Handle error.
	}

	// Use installation transport with client.
	client, err := github.NewClient(github.WithTransport(itr))
	if err != nil {
		// Handle error.
	}

	// Use client...
}

go-githubauth implements a set of oauth2.TokenSource to be used with oauth2.Client. An oauth2.Client can be injected into the github.Client to authenticate requests.

Another example using go-githubauth:

package main

import (
	"context"
	"fmt"
	"os"
	"strconv"

	"github.com/google/go-github/v91/github"
	"github.com/jferrl/go-githubauth"
	"golang.org/x/oauth2"
)

func main() {
	privateKey := []byte(os.Getenv("GITHUB_APP_PRIVATE_KEY"))

	appTokenSource, err := githubauth.NewApplicationTokenSource(1112, privateKey)
	if err != nil {
		fmt.Println("Error creating application token source:", err)
		return
	 }

	installationTokenSource := githubauth.NewInstallationTokenSource(1113, appTokenSource)

	// oauth2.NewClient uses oauth2.ReuseTokenSource to reuse the token until it expires.
	// The token will be automatically refreshed when it expires.
	// InstallationTokenSource has the mechanism to refresh the token when it expires.
	httpClient := oauth2.NewClient(context.Background(), installationTokenSource)

	client, err := github.NewClient(github.WithHTTPClient(httpClient))
	if err != nil {
		// Handle error.
	}
}

Note: In order to interact with certain APIs, for example writing a file to a repo, one must generate an installation token using the installation ID of the GitHub app and authenticate with the OAuth method mentioned above. See the examples.

Rate Limiting

GitHub imposes rate limits on all API clients. The primary rate limit is the limit to the number of REST API requests that a client can make within a specific amount of time. This limit helps prevent abuse and denial-of-service attacks, and ensures that the API remains available for all users. Some endpoints, like the search endpoints, have more restrictive limits. Unauthenticated clients may request public data but have a low rate limit, while authenticated clients have rate limits based on the client identity.

In addition to primary rate limits, GitHub enforces secondary rate limits in order to prevent abuse and keep the API available for all users. Secondary rate limits generally limit the number of concurrent requests that a client can make.

The client returned Response.Rate value contains the rate limit information from the most recent API call. If a recent enough response isn't available, you can use the client RateLimits service to fetch the most up-to-date rate limit data for the client.

To detect a primary API rate limit error, you can check if the error is a RateLimitError.

repos, _, err := client.Repositories.List(ctx, "", nil)
var rateErr *github.RateLimitError
if errors.As(err, &rateErr) {
	log.Printf("hit primary rate limit, used %v of %v\n", rateErr.Rate.Used, rateErr.Rate.Limit)
}

To detect an API secondary rate limit error, you can check if the error is an AbuseRateLimitError.

repos, _, err := client.Repositories.List(ctx, "", nil)
var rateErr *github.AbuseRateLimitError
if errors.As(err, &rateErr) {
	log.Printf("hit secondary rate limit, retry after %v\n", rateErr.RetryAfter)
}

If you hit the primary rate limit, you can use the SleepUntilPrimaryRateLimitResetWhenRateLimited method to block until the rate limit is reset.

repos, _, err := client.Repositories.List(context.WithValue(ctx, github.SleepUntilPrimaryRateLimitResetWhenRateLimited, true), "", nil)

If you need to make a request even if the rate limit has been hit you can use the BypassRateLimitCheck method to bypass the rate limit check and make the request anyway.

repos, _, err := client.Repositories.List(context.WithValue(ctx, github.BypassRateLimitCheck, true), "", nil)

For more advanced use cases, you can use gofri/go-github-ratelimit which provides a middleware (http.RoundTripper) that handles both the primary rate limit and secondary rate limit for the GitHub API. In this case you can set the client DisableRateLimitCheck to true so the client doesn't track the rate limit usage.

If the client is an OAuth app you can use the apps higher rate limit to request public data by using the UnauthenticatedRateLimitedTransport to make calls as the app instead of as the user.

Accepted Status

Some endpoints may return a 202 Accepted status code, meaning that the information required is not yet ready and was scheduled to be gathered on the GitHub side. Methods known to behave like this are documented specifying this behavior.

To detect this condition of error, you can check if its type is *github.AcceptedError:

stats, _, err := client.Repositories.ListContributorsStats(ctx, org, repo)
if errors.As(err, new(*github.AcceptedError)) {
	log.Println("scheduled on GitHub side")
}

Conditional Requests

The GitHub REST API has good support for conditional HTTP requests via the ETag header which will help prevent you from burning through your rate limit, as well as help speed up your application. go-github does not handle conditional requests directly, but is instead designed to work with a caching http.Transport.

Typically, an RFC 9111 compliant HTTP cache such as bartventer/httpcache is recommended, ex:

import (
	"github.com/bartventer/httpcache"
	_ "github.com/bartventer/httpcache/store/memcache" // Register the in-memory backend
)

client, err := github.NewClient(github.WithHTTPClient(httpcache.NewClient("memcache://")), github.WithAuthToken(os.Getenv("GITHUB_TOKEN")))
if err != nil {
	// Handle error.
}

Alternatively, the bored-engineer/github-conditional-http-transport package relies on (undocumented) GitHub specific cache logic and is recommended when making requests using short-lived credentials such as a GitHub App installation token.

Creating and Updating Resources

All structs for GitHub resources use pointer values for all non-repeated fields. This allows distinguishing between unset fields and those set to a zero-value. Use the new builtin to easily create these pointers for string, bool, and int values. For example:

// create a new private repository named "foo"
repo := &github.Repository{
	Name:    new("foo"),
	Private: new(true),
}
client.Repositories.Create(ctx, "", repo)

Users who have worked with protocol buffers should find this pattern familiar.

Pagination

All requests for resource collections (repos, pull requests, issues, etc.) support pagination. Pagination options using page numbers are described in the github.ListOptions struct and passed to the list methods directly or as an embedded type of a more specific list options struct (for example github.PullRequestListOptions). Pages information is available via the github.Response struct.

client, err := github.NewClient()
if err != nil {
	// Handle error.
}

opt := &github.RepositoryListByOrgOptions{
	ListOptions: github.ListOptions{PerPage: 10},
}
// get all pages of results
var allRepos []*github.Repository
for {
	repos, resp, err := client.Repositories.ListByOrg(ctx, "github", opt)
	if err != nil {
		return err
	}
	allRepos = append(allRepos, repos...)
	if resp.NextPage == 0 {
		break
	}
	opt.Page = resp.NextPage
}

Pagination options using string cursors are described in the github.ListCursorOptions struct and passed to the list methods directly or as an embedded type of a more specific list cursor options struct (for example github.ListGlobalSecurityAdvisoriesOptions). Similarly, cursor and pages information is available via the github.Response struct.

Iterators

Go v1.23 introduces the new iter package.

The new github/gen-iterators.go file auto-generates "*Iter" methods in github/github-iterators.go for all methods that support page number iteration (using the NextPage field in each response) or string cursor iteration (using the After field in each response). To handle rate limiting issues, make sure to use a rate-limiting transport. (See Rate Limiting above for more details.) To use these methods, simply create an iterator and then range over it, for example:

client, err := github.NewClient()
if err != nil {
	// Handle error.
}
var allRepos []*github.Repository

// create an iterator and start looping through all the results
iter := client.Repositories.ListIter(ctx, "github", nil)
for repo, err := range iter {
	if err != nil {
		log.Fatal(err)
	}
	allRepos = append(allRepos, repo)
}

Alternatively, if you wish to use an external package, there is enrichman/gh-iter. Its iterator will handle pagination for you, looping through all the available results.

client, err := github.NewClient()
if err != nil {
	// Handle error.
}
var allRepos []*github.Repository

// create an iterator and start looping through all the results
repos := ghiter.NewFromFn1(client.Repositories.ListByOrg, "github")
for repo := range repos.All() {
	allRepos = append(allRepos, repo)
}

For complete usage of enrichman/gh-iter, see the full package docs.

Middleware

You can use gofri/go-github-pagination to handle pagination for you. It supports both sync and async modes, as well as customizations. By default, the middleware automatically paginates through all pages, aggregates results, and returns them as an array. See example/ratelimit/main.go for usage.

Webhooks

go-github provides structs for almost all GitHub webhook events as well as functions to validate them and unmarshal JSON payloads from http.Request structs.

func (s *GitHubEventMonitor) ServeHTTP(w http.ResponseWriter, r *http.Request) {
	payload, err := github.ValidatePayload(r, s.webhookSecretKey)
	if err != nil { ... }
	event, err := github.ParseWebHook(github.WebHookType(r), payload)
	if err != nil { ... }
	switch event := event.(type) {
	case *github.CommitCommentEvent:
		processCommitCommentEvent(event)
	case *github.CreateEvent:
		processCreateEvent(event)
	...
	}
}

Furthermore, there are libraries like cbrgm/githubevents that build upon the example above and provide functions to subscribe callbacks to specific events.

For complete usage of go-github, see the full package docs.

Testing code that uses `go-github`

The repo migueleliasweb/go-github-mock provides a way to mock responses. Check the repo for more details.

Integration Tests

You can run integration tests from the test directory. See the integration tests README.

Contributing

I would like to cover the entire GitHub API and contributions are of course always welcome. The calling pattern is pretty well established, so adding new methods is relatively straightforward. See CONTRIBUTING.md for details.

Versioning

In general, go-github follows semver as closely as we can for tagging releases of the package. For self-contained libraries, the application of semantic versioning is relatively straightforward and generally understood. But because go-github is a client library for the GitHub API, which itself changes behavior, and because we are typically pretty aggressive about implementing preview features of the GitHub API, we've adopted the following versioning policy:

We increment the major version with any incompatible change to non-preview functionality, including changes to the exported Go API surface or behavior of the API.
We increment the minor version with any backwards-compatible changes to functionality, as well as any changes to preview functionality in the GitHub API. GitHub makes no guarantee about the stability of preview functionality, so neither do we consider it a stable part of the go-github API.
We increment the patch version with any backwards-compatible bug fixes.

Preview functionality may take the form of entire methods or simply additional data returned from an otherwise non-preview method. Refer to the GitHub API documentation for details on preview functionality.

Calendar Versioning

As of 2022-11-28, GitHub has announced that they are starting to version their v3 API based on "calendar-versioning".

In practice, our goal is to make per-method version overrides (at least in the core library) rare and temporary.

Our understanding of the GitHub docs is that they will be revving the entire API to each new date-based version, even if only a few methods have breaking changes. Other methods will accept the new version with their existing functionality. So when a new date-based version of the GitHub API is released, we (the repo maintainers) plan to:

update each method that had breaking changes, overriding their per-method API version header. This may happen in one or multiple commits and PRs, and is all done in the main branch.
once all of the methods with breaking changes have been updated, have a final commit that bumps the default API version, and remove all of the per-method overrides. That would now get a major version bump when the next go-github release is made.

Version Compatibility Table

The following table identifies which version of the GitHub API is supported by this (and past) versions of this repo (go-github). Versions prior to 48.2.0 are not listed.

go-github Version	GitHub v3 API Version
91.0.0	2022-11-28
...	2022-11-28
48.2.0	2022-11-28

License

This library is distributed under the BSD-style license found in the LICENSE file.

moby/moby

The Moby Project - a collaborative project for the container ecosystem to assemble container-based systems

https://mobyproject.org/

The Moby Project

Moby is an open-source project created by Docker to enable and accelerate software containerization.

It provides a "Lego set" of toolkit components, the framework for assembling them into custom container-based systems, and a place for all container enthusiasts and professionals to experiment and exchange ideas. Components include container build tools, a container registry, orchestration tools, a runtime and more, and these can be used as building blocks in conjunction with other tools and projects.

Principles

Moby is an open project guided by strong principles, aiming to be modular, flexible and without too strong an opinion on user experience. It is open to the community to help set its direction.

Modular: the project includes lots of components that have well-defined functions and APIs that work together.
Batteries included but swappable: Moby includes enough components to build fully featured container systems, but its modular architecture ensures that most of the components can be swapped by different implementations.
Usable security: Moby provides secure defaults without compromising usability.
Developer focused: The APIs are intended to be functional and useful to build powerful tools. They are not necessarily intended as end user tools but as components aimed at developers. Documentation and UX is aimed at developers not end users.

Audience

The Moby Project is intended for engineers, integrators and enthusiasts looking to modify, hack, fix, experiment, invent and build systems based on containers. It is not for people looking for a commercially supported system, but for people who want to work and learn with open source code.

Relationship with Docker

The components and tools in the Moby Project are initially the open source components that Docker and the community have built for the Docker Project. New projects can be added if they fit with the community goals. Docker is committed to using Moby as the upstream for the Docker Product. However, other projects are also encouraged to use Moby as an upstream, and to reuse the components in diverse ways, and all these uses will be treated in the same way. External maintainers and contributors are welcomed.

The Moby project is not intended as a location for support or feature requests for Docker products, but as a place for contributors to work on open source code, fix bugs, and make the code more useful. The releases are supported by the maintainers, community and users, on a best efforts basis only. For customers who want enterprise or commercial support, Docker Desktop and Mirantis Container Runtime are the appropriate products for these use cases.

Go modules

Important

Starting with Docker v29 (released November 2025), the Go module github.com/docker/docker is deprecated and won't be updated.

The supported public Go modules are:

Module	Description
`github.com/moby/moby/client`	Go client for the Docker Engine API
`github.com/moby/moby/api`	API types shared between client and server

The root module github.com/moby/moby/v2 is the codebase for building container engines based on Moby (such as Docker Engine). It produces binaries only - it is not intended to be imported as a Go library and has no API stability guarantees.

Release tags

Docker Engine releases are tagged with a docker- prefix (e.g. docker-v29.0.0 for Docker Engine 29.0.0).

These tags are only used to build the Docker Engine binary from the root module - they must not be consumed via go get.

The client and api modules are versioned independently with their own tags (e.g. client/v1.x.x, api/v1.x.x).

Migrating from `github.com/docker/docker`

Replace the old import paths:

- import "github.com/docker/docker/client"
+ import "github.com/moby/moby/client"

- import "github.com/docker/docker/api/types"
+ import "github.com/moby/moby/api/types"

Note that v29 includes many breaking API changes (option structs, renamed methods, moved types). See the v29.0.0 release notes for the full list of Go SDK changes.

Legal

Brought to you courtesy of our legal counsel. For more context, please see the NOTICE document in this repo.

Use and transfer of Moby may be subject to certain restrictions by the United States and other governments.

It is your responsibility to ensure that your use and/or transfer does not violate applicable laws.

For more information, please see https://www.bis.doc.gov

Licensing

Moby is licensed under the Apache License, Version 2.0. See LICENSE for the full license text.

XTLS/Xray-core

Xray, Penetrates Everything. Also the best v2ray-core. Where the magic happens. An open platform for various uses.

https://t.me/projectXray

Project X

Project X originates from XTLS protocol, providing a set of network tools such as Xray-core and REALITY.

README is open, so feel free to submit your project here.

Donation & NFTs

Collect a Project X NFT to support the development of Project X!

TRX(Tron)/USDT/USDC: TNrDh5VSfwd4RPrwsohr6poyNTfFefNYan
TON: UQApeV-u2gm43aC1uP76xAC1m6vCylstaN1gpfBmre_5IyTH
BTC: 1JpqcziZZuqv3QQJhZGNGBVdCBrGgkL6cT
XMR: 4ABHQZ3yJZkBnLoqiKvb3f8eqUnX4iMPb6wdant5ZLGQELctcerceSGEfJnoCk6nnyRZm73wrwSgvZ2WmjYLng6R7sR67nq
SOL/USDT/USDC: 3x5NuXHzB5APG6vRinPZcsUv5ukWUY1tBGRSJiEJWtZa
ETH/USDT/USDC: 0xDc3Fe44F0f25D13CACb1C4896CD0D321df3146Ee
Project X NFT: https://opensea.io/item/ethereum/0x5ee362866001613093361eb8569d59c4141b76d1/1
VLESS NFT: https://opensea.io/collection/vless
REALITY NFT: https://opensea.io/item/ethereum/0x5ee362866001613093361eb8569d59c4141b76d1/2
Related links: VLESS Post-Quantum Encryption, XHTTP: Beyond REALITY, Announcement of NFTs by Project X

License

Mozilla Public License Version 2.0

Documentation

Project X Official Website

Project X

Project X Channel

Project VLESS (Русский)

Project XHTTP (Persian)

Installation

Linux Script
- XTLS/Xray-install (Official)
- tempest (supports systemd and OpenRC; Linux-only)
Docker
- ghcr.io/xtls/xray-core (Official)
- teddysun/xray
- wulabing/xray_docker
Web Panel
- Remnawave
- 3X-UI
- PasarGuard
- Xray-UI
- X-Panel
- Marzban
- Hiddify
- TX-UI
- CELERITY
One Click
Magisk
- Magic_V2Ray
- Xray_For_Magisk
Homebrew
- brew install xray

Usage

GUI Clients

OpenWrt
Asuswrt-Merlin
- XRAYUI
- fancyss
Windows
Android
- v2rayNG
- X-flutter
- SaeedDev94/Xray
- SimpleXray
- XrayFA
- AnyPortal
- OneXray
- AsteriskNG
iOS & macOS arm64 & tvOS
- Happ | Happ RU | Happ tvOS
- Streisand
- OneXray
- INCY
macOS arm64 & x64
- Happ | Happ RU
- V2rayU
- V2RayXS
- Furious
- OneXray
- GoXRay
- AnyPortal
- v2rayN
- GenyConnect
- INCY
Linux
- v2rayA
- Furious
- GorzRay
- GoXRay
- AnyPortal
- v2rayN
- GenyConnect
- OneXray
HarmonyOS
- Hey

Others that support VLESS, XTLS, REALITY, XUDP, PLUX...

iOS & macOS arm64 & tvOS
- Anywhere
- Shadowrocket
- Loon
- Egern
- Quantumult X
Xray Tools
- xray-knife
- xray-checker
Xray Wrapper
XrayR
- XrayR-release
- XrayR-V2Board
Cores

Contributing

Code of Conduct

Credits

Xray-core v1.0.0 was forked from v2fly-core 9a03cc5, and we have made & accumulated a huge number of enhancements over time, check the release notes for each version.
For third-party projects used in Xray-core, check your local or the latest go.mod.

Bundled Third-Party Components Redistribution

Certain optional features dynamically load third-party components. These optional components are separate works distributed under their own licenses, and are bundled into the ZIP package for ease of use. Users may replace these components under the licenses from these components.

These components include:

Wintun

This distribution contains unmodified official precompiled and pre-signed Wintun binaries.

Project: Wintun
Redistribution License: Prebuilt Binaries License (PBL) bundled with official precompiled and pre-signed binaries from wintun.net
Component(s): wintun.dll
Source: https://www.wintun.net/
Included in:
- Windows x86 (windows-32, win7-32)
- Windows x86-64 (windows-64, win7-64)
- Windows AArch64 (windows-arm64)
Notes: Wintun is an optional runtime-loaded component only used for TUN inbound functionality on supported Windows platforms.

One-line Compilation

Windows (PowerShell)

$env:CGO_ENABLED=0
go build -o xray.exe -trimpath -buildvcs=false -ldflags="-s -w -buildid=" -v ./main

Linux / macOS

CGO_ENABLED=0 go build -o xray -trimpath -buildvcs=false -ldflags="-s -w -buildid=" -v ./main

Reproducible Releases

Make sure that you are using the same Go version, and remember to set the git commit id (7 bytes):

CGO_ENABLED=0 go build -o xray -trimpath -buildvcs=false -gcflags="all=-l=4" -ldflags="-X github.com/xtls/xray-core/core.build=REPLACE -s -w -buildid=" -v ./main

For Android:

GOOS=android GOARCH=arm64 CGO_ENABLED=1 CC=/path/to/aarch64-linux-android24-clang go build -o xray -trimpath -buildvcs=false -gcflags="all=-l=4" -ldflags="-X github.com/xtls/xray-core/core.build=REPLACE -s -w -buildid= -checklinkname=0" -v ./main
GOOS=android GOARCH=amd64 CGO_ENABLED=1 CC=/path/to/x86_64-linux-android24-clang go build -o xray -trimpath -buildvcs=false -gcflags="all=-l=4" -ldflags="-X github.com/xtls/xray-core/core.build=REPLACE -s -w -buildid= -checklinkname=0" -v ./main

If you are compiling a 32-bit MIPS/MIPSLE target, use this command instead:

CGO_ENABLED=0 go build -o xray -trimpath -buildvcs=false -gcflags="-l=4" -ldflags="-X github.com/xtls/xray-core/core.build=REPLACE -s -w -buildid=" -v ./main

Stargazers over time

open-telemetry/opentelemetry-collector

OpenTelemetry Collector

https://opentelemetry.io

Getting Started • Getting Involved • Getting In Touch

Vision • Configuration • Monitoring • Security • Package

OpenTelemetry Collector

The OpenTelemetry Collector offers a vendor-agnostic implementation on how to receive, process and export telemetry data. In addition, it removes the need to run, operate and maintain multiple agents/collectors in order to support open-source telemetry data formats (e.g. Jaeger, Prometheus, etc.) to multiple open-source or commercial back-ends.

Objectives:

Usable: Reasonable default configuration, supports popular protocols, runs and collects out of the box.
Performant: Highly stable and performant under varying loads and configurations.
Observable: An exemplar of an observable service.
Extensible: Customizable without touching the core code.
Unified: Single codebase, deployable as an agent or collector with support for traces, metrics and logs.

Community

The OpenTelemetry Collector SIG is present at the #otel-collector channel on the CNCF Slack and meets once a week via video calls. If you are new to the CNCF Slack community, you can create an account. Everyone is invited to join those calls, which typically serves the following purposes:

meet the humans behind the project
get an opinion about specific proposals
look for a sponsor for a proposed component after trying already via GitHub and Slack
get attention to a specific pull-request that got stuck and is difficult to discuss asynchronously

We rotate our video calls between three time slots, in order to allow everyone to join at least once every three meetings. The rotation order is as follows:

Tuesday:

17:00 PT

Wednesday:

Contributors to the project are also welcome to have ad-hoc meetings for synchronous discussions about specific points. Post a note in #otel-collector-dev on Slack inviting others, specifying the topic to be discussed. Unless there are strong reasons to keep the meeting private, please make it an open invitation for other contributors to join. Try also to identify who would be the other contributors interested on that topic and in which timezones they are.

Remember that our source of truth is GitHub: every decision made via Slack or video calls has to be recorded in the relevant GitHub issue. Ideally, the agenda items from the meeting notes would include a link to the issue or pull request where a discussion is happening already. We acknowledge that not everyone can join Slack or the synchronous calls and don't want them to feel excluded.

Supported OTLP version

This code base is currently built against using OTLP protocol v1.10.0, considered Stable. See the OpenTelemetry Protocol Stability definition here.

Stability levels

See Stability Levels and versioning for more details.

Compatibility

When used as a library, the OpenTelemetry Collector attempts to track the currently supported Go minor versions, as defined by the Go team. Removing support for an unsupported Go version is not considered a breaking change.

Support for Go versions on the OpenTelemetry Collector is updated as follows:

The first release after the release of a new Go minor version N will add build and tests steps for the new Go minor version.
The first release after the release of a new Go minor version N will remove support for Go version N-2.

Within supported Go minor versions, the minimum supported patch version may increase over time, for example to accommodate dependency updates. Increasing the minimum supported patch version within a supported Go minor version is not considered a breaking change.

Official OpenTelemetry Collector distro binaries will be built with a release in the latest Go minor version series.

Verifying the images signatures

Note

To verify a signed artifact or blob, first install Cosign, then follow the instructions below.

We are signing the images otel/opentelemetry-collector and otel/opentelemetry-collector-contrib using sigstore cosign tool and to verify the signatures you can run the following command:

$ cosign verify \
  --certificate-identity=https://github.com/open-telemetry/opentelemetry-collector-releases/.github/workflows/base-release.yaml@refs/tags/<RELEASE_TAG> \
  --certificate-oidc-issuer=https://token.actions.githubusercontent.com \
  <OTEL_COLLECTOR_IMAGE>

where:

<RELEASE_TAG>: is the release that you want to validate
<OTEL_COLLECTOR_IMAGE>: is the image that you want to check

Example:

$ cosign verify --certificate-identity=https://github.com/open-telemetry/opentelemetry-collector-releases/.github/workflows/base-release.yaml@refs/tags/v0.98.0 --certificate-oidc-issuer=https://token.actions.githubusercontent.com ghcr.io/open-telemetry/opentelemetry-collector-releases/opentelemetry-collector-contrib:0.98.0

Verification for ghcr.io/open-telemetry/opentelemetry-collector-releases/opentelemetry-collector-contrib:0.98.0 --
The following checks were performed on each of these signatures:
  - The cosign claims were validated
  - Existence of the claims in the transparency log was verified offline
  - The code-signing certificate was verified using trusted certificate authority certificates

[{"critical":{"identity":{"docker-reference":"ghcr.io/open-telemetry/opentelemetry-collector-releases/opentelemetry-collector-contrib"},"image":{"docker-manifest-digest":"sha256:5cea85bcbc734a3c0a641368e5a4ea9d31b472997e9f2feca57eeb4a147fcf1a"},"type":"cosign container image signature"},"optional":{"1.3.6.1.4.1.57264.1.1":"https://token.actions.githubusercontent.com","1.3.6.1.4.1.57264.1.2":"push","1.3.6.1.4.1.57264.1.3":"9e20bf5c142e53070ccb8320a20315fffb41469e","1.3.6.1.4.1.57264.1.4":"Release Contrib","1.3.6.1.4.1.57264.1.5":"open-telemetry/opentelemetry-collector-releases","1.3.6.1.4.1.57264.1.6":"refs/tags/v0.98.0","Bundle":{"SignedEntryTimestamp":"MEUCIQDdlmNeKXQrHnonwWiHLhLLwFDVDNoOBCn2sv85J9P8mgIgDQFssWJImo1hn38VlojvSCL7Qq5FMmtnGu0oLsNdOm8=","Payload":{"body":"eyJhcGlWZXJzaW9uIjoiMC4wLjEiLCJraW5kIjoiaGFzaGVkcmVrb3JkIiwic3BlYyI6eyJkYXRhIjp7Imhhc2giOnsiYWxnb3JpdGhtIjoic2hhMjU2IiwidmFsdWUiOiIxMzVjY2RlN2YzZTNhYjU2NmFmYzJhYWU3MDljYmJlNmFhMDZlZWMzNDA2MWNkZjMyNmRhYzM2MmY0NWM4Yjg4In19LCJzaWduYXR1cmUiOnsiY29udGVudCI6Ik1FVUNJUURFbDV6N0diMWRVYkM5KzR4c1VvbDhMcWZNV2hiTzhkdEpwdExyMXhUNWZnSWdTdEwwN1I0ZDA5R2x0ZkV0azJVbmlJSlJhQVdrVDJNWDVtRXJNSlplc2pRPSIsInB1YmxpY0tleSI6eyJjb250ZW50IjoiTFMwdExTMUNSVWRKVGlCRFJWSlVTVVpKUTBGVVJTMHRMUzB0Q2sxSlNVaG9ha05EUW5jeVowRjNTVUpCWjBsVlNETkNjRFZTYlVSU1VpOXphMWg0YVdWUFlrcFhSbmRrUjNNNGQwTm5XVWxMYjFwSmVtb3dSVUYzVFhjS1RucEZWazFDVFVkQk1WVkZRMmhOVFdNeWJHNWpNMUoyWTIxVmRWcEhWakpOVWpSM1NFRlpSRlpSVVVSRmVGWjZZVmRrZW1SSE9YbGFVekZ3WW01U2JBcGpiVEZzV2tkc2FHUkhWWGRJYUdOT1RXcFJkMDVFUlhoTlJGRjRUMFJOTlZkb1kwNU5hbEYzVGtSRmVFMUVVWGxQUkUwMVYycEJRVTFHYTNkRmQxbElDa3R2V2tsNmFqQkRRVkZaU1V0dldrbDZhakJFUVZGalJGRm5RVVZyWlRsSE1ubHNjMjkzYVZZMmRFOVZSazlRVVhNd2NXY3hTSEV5WmpsVUx6UTJZbEFLU1ZSNE0ybFRkVXBhV0hGc1dEUldWV2Q1VlZndmNVazJhblZ2WlZSVEswaG5XVUoyYjBseVNERTFUeTltZEd0VmVtRlBRMEpwZDNkbloxbHZUVUUwUndwQk1WVmtSSGRGUWk5M1VVVkJkMGxJWjBSQlZFSm5UbFpJVTFWRlJFUkJTMEpuWjNKQ1owVkdRbEZqUkVGNlFXUkNaMDVXU0ZFMFJVWm5VVlZHTkRrMUNrdDFNRWhqTm5rek1rNUNTVTFFU21ReVpuWkxNMHBCZDBoM1dVUldVakJxUWtKbmQwWnZRVlV6T1ZCd2VqRlphMFZhWWpWeFRtcHdTMFpYYVhocE5Ga0tXa1E0ZDJkWldVZEJNVlZrUlZGRlFpOTNVamhOU0hGSFpVZG9NR1JJUW5wUGFUaDJXakpzTUdGSVZtbE1iVTUyWWxNNWRtTkhWblZNV0ZKc1lrZFdkQXBhV0ZKNVpWTTVkbU5IVm5Wa1IxWnpXbGN4YkdSSVNqVk1WMDUyWWtkNGJGa3pVblpqYVRGNVdsZDRiRmxZVG14amVUaDFXakpzTUdGSVZtbE1NMlIyQ21OdGRHMWlSemt6WTNrNWFWbFlUbXhNV0Vwc1lrZFdhR015VlhWbFYwWjBZa1ZDZVZwWFducE1NMUpvV2pOTmRtUnFRWFZQVkdkMVRVUkJOVUpuYjNJS1FtZEZSVUZaVHk5TlFVVkNRa04wYjJSSVVuZGplbTkyVEROU2RtRXlWblZNYlVacVpFZHNkbUp1VFhWYU1td3dZVWhXYVdSWVRteGpiVTUyWW01U2JBcGlibEYxV1RJNWRFMUNTVWREYVhOSFFWRlJRbWMzT0hkQlVVbEZRa2hDTVdNeVozZE9aMWxMUzNkWlFrSkJSMFIyZWtGQ1FYZFJiMDlYVlhsTlIwcHRDazVYVFhoT1JFcHNUbFJOZDA1NlFtcFpNa2swVFhwSmQxbFVTWGROZWtVeFdtMWFiVmxxVVhoT1JGazFXbFJCWkVKbmIzSkNaMFZGUVZsUEwwMUJSVVVLUWtFNVUxcFhlR3haV0U1c1NVVk9kbUp1VW5saFYwbDNVRkZaUzB0M1dVSkNRVWRFZG5wQlFrSlJVWFppTTBKc1lta3hNRnBYZUd4aVYxWXdZMjVyZGdwaU0wSnNZbTVTYkdKSFZuUmFXRko1WlZNeGFtSXllSE5hVjA0d1lqTkpkR050Vm5OYVYwWjZXbGhOZDBoM1dVdExkMWxDUWtGSFJIWjZRVUpDWjFGU0NtTnRWbTFqZVRrd1dWZGtla3d6V1hkTWFtczBUR3BCZDA5M1dVdExkMWxDUWtGSFJIWjZRVUpEUVZGMFJFTjBiMlJJVW5kamVtOTJURE5TZG1FeVZuVUtURzFHYW1SSGJIWmliazExV2pKc01HRklWbWxrV0U1c1kyMU9kbUp1VW14aWJsRjFXVEk1ZEUxSlIwbENaMjl5UW1kRlJVRlpUeTlOUVVWS1FraHZUUXBsUjJnd1pFaENlazlwT0haYU1td3dZVWhXYVV4dFRuWmlVemwyWTBkV2RVeFlVbXhpUjFaMFdsaFNlV1ZUT1haalIxWjFaRWRXYzFwWE1XeGtTRW8xQ2t4WFRuWmlSM2hzV1ROU2RtTnBNWGxhVjNoc1dWaE9iR041T0hWYU1td3dZVWhXYVV3elpIWmpiWFJ0WWtjNU0yTjVPV2xaV0U1c1RGaEtiR0pIVm1nS1l6SlZkV1ZYUm5SaVJVSjVXbGRhZWt3elVtaGFNMDEyWkdwQmRVOVVaM1ZOUkVFMFFtZHZja0puUlVWQldVOHZUVUZGUzBKRGIwMUxSR3hzVFdwQ2FRcGFhbFpxVFZSUmVWcFVWWHBOUkdOM1dUSk9hVTlFVFhsTlIwVjVUVVJOZUU1WFdtMWFiVWt3VFZSUk1rOVhWWGRJVVZsTFMzZFpRa0pCUjBSMmVrRkNDa04zVVZCRVFURnVZVmhTYjJSWFNYUmhSemw2WkVkV2EwMUdTVWREYVhOSFFWRlJRbWMzT0hkQlVYZEZVa0Y0UTJGSVVqQmpTRTAyVEhrNWJtRllVbThLWkZkSmRWa3lPWFJNTWpsM1dsYzBkR1JIVm5OYVZ6RnNaRWhLTlV3eU9YZGFWelV3V2xkNGJHSlhWakJqYm10MFdUSTVjMkpIVm1wa1J6bDVURmhLYkFwaVIxWm9ZekpXZWsxRVowZERhWE5IUVZGUlFtYzNPSGRCVVRCRlMyZDNiMDlYVlhsTlIwcHRUbGROZUU1RVNteE9WRTEzVG5wQ2Fsa3lTVFJOZWtsM0NsbFVTWGROZWtVeFdtMWFiVmxxVVhoT1JGazFXbFJCYUVKbmIzSkNaMFZGUVZsUEwwMUJSVTlDUWsxTlJWaEtiRnB1VFhaa1IwWnVZM2s1TWsxRE5EVUtUME0wZDAxQ2EwZERhWE5IUVZGUlFtYzNPSGRCVVRoRlEzZDNTazVFUVhkTmFsVjZUbXBqTWsxRVJVZERhWE5IUVZGUlFtYzNPSGRCVWtGRlNYZDNhQXBoU0ZJd1kwaE5Oa3g1T1c1aFdGSnZaRmRKZFZreU9YUk1NamwzV2xjMGRHUkhWbk5hVnpGc1pFaEtOVTFDWjBkRGFYTkhRVkZSUW1jM09IZEJVa1ZGQ2tObmQwbE9SR3MxVDFSbmQwMUVTWGRuV1hOSFEybHpSMEZSVVVKbk56aDNRVkpKUldaUmVEZGhTRkl3WTBoTk5reDVPVzVoV0ZKdlpGZEpkVmt5T1hRS1RESTVkMXBYTkhSa1IxWnpXbGN4YkdSSVNqVk1NamwzV2xjMU1GcFhlR3hpVjFZd1kyNXJkRmt5T1hOaVIxWnFaRWM1ZVV4WVNteGlSMVpvWXpKV2VncE1lVFZ1WVZoU2IyUlhTWFprTWpsNVlUSmFjMkl6WkhwTU0wcHNZa2RXYUdNeVZYUlpNamwxWkVoS2NGbHBOVFZaVnpGelVVaEtiRnB1VFhaa1IwWnVDbU41T1RKTlF6UTFUME0wZDAxRVowZERhWE5IUVZGUlFtYzNPSGRCVWsxRlMyZDNiMDlYVlhsTlIwcHRUbGROZUU1RVNteE9WRTEzVG5wQ2Fsa3lTVFFLVFhwSmQxbFVTWGROZWtVeFdtMWFiVmxxVVhoT1JGazFXbFJCVlVKbmIzSkNaMFZGUVZsUEwwMUJSVlZDUVZsTlFraENNV015WjNka1VWbExTM2RaUWdwQ1FVZEVkbnBCUWtaUlVtNUVSMVp2WkVoU2QyTjZiM1pNTW1Sd1pFZG9NVmxwTldwaU1qQjJZak5DYkdKcE1UQmFWM2hzWWxkV01HTnVhM1ppTTBKc0NtSnVVbXhpUjFaMFdsaFNlV1ZUTVdwaU1uaHpXbGRPTUdJelNYUmpiVlp6V2xkR2VscFlUWFpaVjA0d1lWYzVkV041T1hsa1Z6VjZUSHBuTWs1RVJYZ0tUbnBGTVU1cVkzWlpXRkl3V2xjeGQyUklUWFpOYWtGWFFtZHZja0puUlVWQldVOHZUVUZGVjBKQlowMUNia0l4V1cxNGNGbDZRMEpwWjFsTFMzZFpRZ3BDUVVoWFpWRkpSVUZuVWpoQ1NHOUJaVUZDTWtGT01EbE5SM0pIZUhoRmVWbDRhMlZJU214dVRuZExhVk5zTmpRemFubDBMelJsUzJOdlFYWkxaVFpQQ2tGQlFVSnFjM1JvUlVOUlFVRkJVVVJCUldOM1VsRkpaMWg2Y2xaME0xQjRkU3ROWVZKRkswUkdORzlGUldNMGVucHphSGR1VDJ4bGMwZGlla2xwYnpNS0wxWmpRMGxSUkZNelJ6QmlNemRhYUhRNGFITjJUSEozYkc1UFFXYzJWRXh1U1ZSS09HTjNkMVEzTW5sMVRVdFlUbFJCUzBKblozRm9hMnBQVUZGUlJBcEJkMDV1UVVSQ2EwRnFRWGxFUkZSYVFqQlRPVXBGYkZsSGJuTnZWVmhLYm04MU5Fc3ZUVUZUTlN0RFFVMU9lbWRqUWpWQ2JrRk5OMWhNUjBoV01HRnhDbVpaY21weFkyOXFia3RaUTAxSFRWRnFjalpUVGt0Q2NVaEtZVGwxTDBSTlQySlpNa0pKTVV0ME4yTnhOemhFT0VOcVMzQmFVblJoYnpadFVVMUVZMk1LUms5M2VYWnhWalJPVld0dlpsRTlQUW90TFMwdExVVk9SQ0JEUlZKVVNVWkpRMEZVUlMwdExTMHRDZz09In19fX0=","integratedTime":1712809120,"logIndex":84797936,"logID":"c0d23d6ad406973f9559f3ba2d1ca01f84147d8ffc5b8445c224f98b9591801d"}},"Issuer":"https://token.actions.githubusercontent.com","Subject":"https://github.com/open-telemetry/opentelemetry-collector-releases/.github/workflows/base-release.yaml@refs/tags/v0.98.0","githubWorkflowName":"Release Contrib","githubWorkflowRef":"refs/tags/v0.98.0","githubWorkflowRepository":"open-telemetry/opentelemetry-collector-releases","githubWorkflowSha":"9e20bf5c142e53070ccb8320a20315fffb41469e","githubWorkflowTrigger":"push"}},{"critical":{"identity":{"docker-reference":"ghcr.io/open-telemetry/opentelemetry-collector-releases/opentelemetry-collector-contrib"},"image":{"docker-manifest-digest":"sha256:5cea85bcbc734a3c0a641368e5a4ea9d31b472997e9f2feca57eeb4a147fcf1a"},"type":"cosign container image signature"},"optional":{"1.3.6.1.4.1.57264.1.1":"https://token.actions.githubusercontent.com","1.3.6.1.4.1.57264.1.2":"push","1.3.6.1.4.1.57264.1.3":"9e20bf5c142e53070ccb8320a20315fffb41469e","1.3.6.1.4.1.57264.1.4":"Release Contrib","1.3.6.1.4.1.57264.1.5":"open-telemetry/opentelemetry-collector-releases","1.3.6.1.4.1.57264.1.6":"refs/tags/v0.98.0","Bundle":{"SignedEntryTimestamp":"MEUCIQD1ehDnPO6fzoPIpeQ3KFuYHHBiX7RcEbpo9B2r7JAlzwIgZ1bsuQz7gAXbNU1IEdsTQgfAnRk3xVXO16GnKXM2sAQ=","Payload":{"body":"eyJhcGlWZXJzaW9uIjoiMC4wLjEiLCJraW5kIjoiaGFzaGVkcmVrb3JkIiwic3BlYyI6eyJkYXRhIjp7Imhhc2giOnsiYWxnb3JpdGhtIjoic2hhMjU2IiwidmFsdWUiOiIxMzVjY2RlN2YzZTNhYjU2NmFmYzJhYWU3MDljYmJlNmFhMDZlZWMzNDA2MWNkZjMyNmRhYzM2MmY0NWM4Yjg4In19LCJzaWduYXR1cmUiOnsiY29udGVudCI6Ik1FUUNJRU92QXl0aE5RVGNvNHFMdG9GZUVOV0toNCtEK2I5SUxyYWhoa09WMmVBM0FpQjNEL2FpUGd1T05zUlB5alhaWk1hdnlCam0vMkVxNFNUMkZJWHozTnpyYWc9PSIsInB1YmxpY0tleSI6eyJjb250ZW50IjoiTFMwdExTMUNSVWRKVGlCRFJWSlVTVVpKUTBGVVJTMHRMUzB0Q2sxSlNVaHBSRU5EUW5jMlowRjNTVUpCWjBsVlZuRlRLMnd4WXpoMWVFUktOWEppZDAxMlVuaDBSR3hXVW1nMGQwTm5XVWxMYjFwSmVtb3dSVUYzVFhjS1RucEZWazFDVFVkQk1WVkZRMmhOVFdNeWJHNWpNMUoyWTIxVmRWcEhWakpOVWpSM1NFRlpSRlpSVVVSRmVGWjZZVmRrZW1SSE9YbGFVekZ3WW01U2JBcGpiVEZzV2tkc2FHUkhWWGRJYUdOT1RXcFJkMDVFUlhoTlJGRjRUMFJSZVZkb1kwNU5hbEYzVGtSRmVFMUVVWGxQUkZGNVYycEJRVTFHYTNkRmQxbElDa3R2V2tsNmFqQkRRVkZaU1V0dldrbDZhakJFUVZGalJGRm5RVVYyWlRCdGJrRkdRVzl1TVZoUGRIVlRMMXBNT0djeE5YUlJkVmxPTmtRemVUUlBWM0FLT1ZSTFMwUlVkRkJHU2xST1ZrWlJkVTlKUWs1bVJqWk1ORTlGYkd4dlZuUndaSE5uYjB0NVZGTnlPR3hTV1c1S1JIRlBRMEpwTUhkbloxbHdUVUUwUndwQk1WVmtSSGRGUWk5M1VVVkJkMGxJWjBSQlZFSm5UbFpJVTFWRlJFUkJTMEpuWjNKQ1owVkdRbEZqUkVGNlFXUkNaMDVXU0ZFMFJVWm5VVlZDSzFkSENuVmtlRE5IZUcxS1RWUkpUVVJyYW13clJtdzFXRzkzZDBoM1dVUldVakJxUWtKbmQwWnZRVlV6T1ZCd2VqRlphMFZhWWpWeFRtcHdTMFpYYVhocE5Ga0tXa1E0ZDJkWldVZEJNVlZrUlZGRlFpOTNVamhOU0hGSFpVZG9NR1JJUW5wUGFUaDJXakpzTUdGSVZtbE1iVTUyWWxNNWRtTkhWblZNV0ZKc1lrZFdkQXBhV0ZKNVpWTTVkbU5IVm5Wa1IxWnpXbGN4YkdSSVNqVk1WMDUyWWtkNGJGa3pVblpqYVRGNVdsZDRiRmxZVG14amVUaDFXakpzTUdGSVZtbE1NMlIyQ21OdGRHMWlSemt6WTNrNWFWbFlUbXhNV0Vwc1lrZFdhR015VlhWbFYwWjBZa1ZDZVZwWFducE1NMUpvV2pOTmRtUnFRWFZQVkdkMVRVUkJOVUpuYjNJS1FtZEZSVUZaVHk5TlFVVkNRa04wYjJSSVVuZGplbTkyVEROU2RtRXlWblZNYlVacVpFZHNkbUp1VFhWYU1td3dZVWhXYVdSWVRteGpiVTUyWW01U2JBcGlibEYxV1RJNWRFMUNTVWREYVhOSFFWRlJRbWMzT0hkQlVVbEZRa2hDTVdNeVozZE9aMWxMUzNkWlFrSkJSMFIyZWtGQ1FYZFJiMDlYVlhsTlIwcHRDazVYVFhoT1JFcHNUbFJOZDA1NlFtcFpNa2swVFhwSmQxbFVTWGROZWtVeFdtMWFiVmxxVVhoT1JGazFXbFJCWkVKbmIzSkNaMFZGUVZsUEwwMUJSVVVLUWtFNVUxcFhlR3haV0U1c1NVVk9kbUp1VW5saFYwbDNVRkZaUzB0M1dVSkNRVWRFZG5wQlFrSlJVWFppTTBKc1lta3hNRnBYZUd4aVYxWXdZMjVyZGdwaU0wSnNZbTVTYkdKSFZuUmFXRko1WlZNeGFtSXllSE5hVjA0d1lqTkpkR050Vm5OYVYwWjZXbGhOZDBoM1dVdExkMWxDUWtGSFJIWjZRVUpDWjFGU0NtTnRWbTFqZVRrd1dWZGtla3d6V1hkTWFtczBUR3BCZDA5M1dVdExkMWxDUWtGSFJIWjZRVUpEUVZGMFJFTjBiMlJJVW5kamVtOTJURE5TZG1FeVZuVUtURzFHYW1SSGJIWmliazExV2pKc01HRklWbWxrV0U1c1kyMU9kbUp1VW14aWJsRjFXVEk1ZEUxSlIwbENaMjl5UW1kRlJVRlpUeTlOUVVWS1FraHZUUXBsUjJnd1pFaENlazlwT0haYU1td3dZVWhXYVV4dFRuWmlVemwyWTBkV2RVeFlVbXhpUjFaMFdsaFNlV1ZUT1haalIxWjFaRWRXYzFwWE1XeGtTRW8xQ2t4WFRuWmlSM2hzV1ROU2RtTnBNWGxhVjNoc1dWaE9iR041T0hWYU1td3dZVWhXYVV3elpIWmpiWFJ0WWtjNU0yTjVPV2xaV0U1c1RGaEtiR0pIVm1nS1l6SlZkV1ZYUm5SaVJVSjVXbGRhZWt3elVtaGFNMDEyWkdwQmRVOVVaM1ZOUkVFMFFtZHZja0puUlVWQldVOHZUVUZGUzBKRGIwMUxSR3hzVFdwQ2FRcGFhbFpxVFZSUmVWcFVWWHBOUkdOM1dUSk9hVTlFVFhsTlIwVjVUVVJOZUU1WFdtMWFiVWt3VFZSUk1rOVhWWGRJVVZsTFMzZFpRa0pCUjBSMmVrRkNDa04zVVZCRVFURnVZVmhTYjJSWFNYUmhSemw2WkVkV2EwMUdTVWREYVhOSFFWRlJRbWMzT0hkQlVYZEZVa0Y0UTJGSVVqQmpTRTAyVEhrNWJtRllVbThLWkZkSmRWa3lPWFJNTWpsM1dsYzBkR1JIVm5OYVZ6RnNaRWhLTlV3eU9YZGFWelV3V2xkNGJHSlhWakJqYm10MFdUSTVjMkpIVm1wa1J6bDVURmhLYkFwaVIxWm9ZekpXZWsxRVowZERhWE5IUVZGUlFtYzNPSGRCVVRCRlMyZDNiMDlYVlhsTlIwcHRUbGROZUU1RVNteE9WRTEzVG5wQ2Fsa3lTVFJOZWtsM0NsbFVTWGROZWtVeFdtMWFiVmxxVVhoT1JGazFXbFJCYUVKbmIzSkNaMFZGUVZsUEwwMUJSVTlDUWsxTlJWaEtiRnB1VFhaa1IwWnVZM2s1TWsxRE5EVUtUME0wZDAxQ2EwZERhWE5IUVZGUlFtYzNPSGRCVVRoRlEzZDNTazVFUVhkTmFsVjZUbXBqTWsxRVJVZERhWE5IUVZGUlFtYzNPSGRCVWtGRlNYZDNhQXBoU0ZJd1kwaE5Oa3g1T1c1aFdGSnZaRmRKZFZreU9YUk1NamwzV2xjMGRHUkhWbk5hVnpGc1pFaEtOVTFDWjBkRGFYTkhRVkZSUW1jM09IZEJVa1ZGQ2tObmQwbE9SR3MxVDFSbmQwMUVTWGRuV1hOSFEybHpSMEZSVVVKbk56aDNRVkpKUldaUmVEZGhTRkl3WTBoTk5reDVPVzVoV0ZKdlpGZEpkVmt5T1hRS1RESTVkMXBYTkhSa1IxWnpXbGN4YkdSSVNqVk1NamwzV2xjMU1GcFhlR3hpVjFZd1kyNXJkRmt5T1hOaVIxWnFaRWM1ZVV4WVNteGlSMVpvWXpKV2VncE1lVFZ1WVZoU2IyUlhTWFprTWpsNVlUSmFjMkl6WkhwTU0wcHNZa2RXYUdNeVZYUlpNamwxWkVoS2NGbHBOVFZaVnpGelVVaEtiRnB1VFhaa1IwWnVDbU41T1RKTlF6UTFUME0wZDAxRVowZERhWE5IUVZGUlFtYzNPSGRCVWsxRlMyZDNiMDlYVlhsTlIwcHRUbGROZUU1RVNteE9WRTEzVG5wQ2Fsa3lTVFFLVFhwSmQxbFVTWGROZWtVeFdtMWFiVmxxVVhoT1JGazFXbFJCVlVKbmIzSkNaMFZGUVZsUEwwMUJSVlZDUVZsTlFraENNV015WjNka1VWbExTM2RaUWdwQ1FVZEVkbnBCUWtaUlVtNUVSMVp2WkVoU2QyTjZiM1pNTW1Sd1pFZG9NVmxwTldwaU1qQjJZak5DYkdKcE1UQmFWM2hzWWxkV01HTnVhM1ppTTBKc0NtSnVVbXhpUjFaMFdsaFNlV1ZUTVdwaU1uaHpXbGRPTUdJelNYUmpiVlp6V2xkR2VscFlUWFpaVjA0d1lWYzVkV041T1hsa1Z6VjZUSHBuTWs1RVJYZ0tUbnBGTVU1cVkzWlpXRkl3V2xjeGQyUklUWFpOYWtGWFFtZHZja0puUlVWQldVOHZUVUZGVjBKQlowMUNia0l4V1cxNGNGbDZRMEpwZDFsTFMzZFpRZ3BDUVVoWFpWRkpSVUZuVWpsQ1NITkJaVkZDTTBGT01EbE5SM0pIZUhoRmVWbDRhMlZJU214dVRuZExhVk5zTmpRemFubDBMelJsUzJOdlFYWkxaVFpQQ2tGQlFVSnFjM1JvUjJKSlFVRkJVVVJCUldkM1VtZEphRUZQZUZNM2RteDRjVzVGYTBKVVRtSlZVRUpsUkZSbk0waGtlRlkyY0cxWk9FdGliREV6TjNBS1lWUnViMEZwUlVFelMyMUxVbU5uYWxBeVQzSmxORVpyVm5vNU4xaENNWGRsUzBOeWFXazFTMWx2UTB0bVkxRktSREJSZDBObldVbExiMXBKZW1vd1JRcEJkMDFFWVVGQmQxcFJTWGhCUzNwcVpHMUZTV2gzV21Kb1lVSlNlalk1Y1N0MWVrNVZSMmxhYlRWVk4xcE5aWFJMUTFSM1VFTkljRkZQVldvdlVERkJDa2R0YWt3elJucFFObTVpYkRGblNYZFNUbXN6UkhkNWMwOUJUMHhoUVVoR09IaHhZV0ZzT0U5WGNGRmFhRGh4TTJVMVNVSmFXR0ZWVkhocFlWbGFTM29LUXpWS1RGVlNWbnBMTURsd04wVjBUd290TFMwdExVVk9SQ0JEUlZKVVNVWkpRMEZVUlMwdExTMHRDZz09In19fX0=","integratedTime":1712809122,"logIndex":84797940,"logID":"c0d23d6ad406973f9559f3ba2d1ca01f84147d8ffc5b8445c224f98b9591801d"}},"Issuer":"https://token.actions.githubusercontent.com","Subject":"https://github.com/open-telemetry/opentelemetry-collector-releases/.github/workflows/base-release.yaml@refs/tags/v0.98.0","githubWorkflowName":"Release Contrib","githubWorkflowRef":"refs/tags/v0.98.0","githubWorkflowRepository":"open-telemetry/opentelemetry-collector-releases","githubWorkflowSha":"9e20bf5c142e53070ccb8320a20315fffb41469e","githubWorkflowTrigger":"push"}}]

Note

We started signing the images with release v0.95.0

Contributing

See the Contributing Guide for details.

Here is a list of community roles with current and previous members:

Maintainers

Alex Boten, Grafana Labs
Bogdan Drutu, Snowflake
Dmitrii Anoshin, Splunk
Evan Bradley, Dynatrace
Pablo Baeyens, DataDog

For more information about the maintainer role, see the community repository.

Approvers

Antoine Toulme, Splunk
Damien Mathieu, Elastic
Jade Guiton, Datadog
Joshua MacDonald, Microsoft
Tyler Helmuth, Grafana Labs
Yang Song, Datadog

For more information about the approver role, see the community repository.

In addition to what is described at the organization-level, the SIG Collector requires all core approvers to take part in rotating the role of the release manager.

Triagers

Andrzej Stencel, Elastic
Arthur Silva Sens, Grafana Labs
Vihas Makwana, Elastic
Actively seeking contributors to triage issues

For more information about the triager role, see the community repository.

Emeritus

Alolita Sharma, Triager
Andrew Hsu, Triager
Andrew Wilkins, Approver
Anthony Mirabella, Approver
Chao Weng, Triager
Daniel Jaglowski, Approver
James Bebbington, Approver
Jay Camp, Approver
Juraci Paixão Kröhling, Approver
Nail Islamov, Approver
Owais Lone, Approver
Paulo Janotti, Maintainer
Punya Biswal, Triager
Rahul Patel, Approver
Steve Flanders, Triager
Steven Karis, Approver
Tigran Najaryan, Maintainer

For more information about the emeritus role, see the community repository.

GitHub Go Weekly Trending Repositories

Tencent/WeKnora

Overview • Architecture • Key Features • Getting Started • API Reference • Developer Guide

💡 WeKnora — Turn Documents into Living Knowledge with RAG, Agents and Auto-Wiki

📌 Overview

✨ Latest Updates

📱 Interface Showcase

🏗️ Architecture

🧩 Feature Overview

🧩 Chrome Extension

📱 WeChat Mini Program

🦞 ClawHub Skill

🐋 DeepSeek Harness Plugin

⌨️ Command-Line Interface

🚀 Getting Started

🛠 Prerequisites

📦 Installation & Launch

🔄 Upgrading

🔧 Optional Services (Docker Compose Profiles)

🌐 Service URLs

MCP Server

🔌 Using WeChat Dialog Open Platform

📘 API Reference

🧭 Developer Guide

⚡ Fast Development Mode (Recommended)

🤝 Contributing

Validation

🔒 Security Notice

👥 Contributors

📄 License

vxcontrol/pentagi

PentAGI

Table of Contents

Overview

Features

Current Capability Boundaries

Architecture

System Context

Global Summarizer Configuration Options

Assistant Summarizer Configuration Options

Summarizer Environment Configuration

Execution Monitoring (Beta)

Intelligent Task Planning (Beta)

Tool Call Limits (Always Active)

Reflector Integration (Always Active)

Recommendations for Open Source Models

Quick Start

System Requirements

Using Installer (Recommended)

Current Web Settings Coverage

Still Server-Managed

Giving Agents Docker Without Giving Away the Host

Running Several Instances (TENANT_ID)

Manual Installation

Main Security Settings

Scraper Access

Access Credentials

Web UI Accounts

Accessing PentAGI from External Networks

Configuration Steps

Running PentAGI with Podman

Podman Rootless Configuration

Podman Rootful Mode

Docker Compatibility

Assistant Configuration

How to Use PentAGI After Login

1. Create your first flow

2. Use templates for repeatable workflows

3. Monitor execution and review output

4. Use the Assistant view to steer an active flow

5. Manage flow-scoped files

API Access

Generating API Tokens

Using API Tokens

API Exploration and Testing

GraphQL Playground

Swagger UI

Generating API Clients

GraphQL Clients

REST API Clients

Running Several Instances (`TENANT_ID`)