# Overview

> What PentAGI exposes: autonomous multi-agent pentests in Docker, BYOK LLM providers, web UI, REST and GraphQL under /api/v1, and the shortest path from deploy to first flow.

- Repository: vxcontrol/pentagi
- GitHub: https://github.com/vxcontrol/pentagi
- Human docs: https://grok-wiki.com/public/docs/vxcontrol-pentagi-eca0cf4de5f5
- Complete Markdown: https://grok-wiki.com/public/docs/vxcontrol-pentagi-eca0cf4de5f5/llms-full.txt

## Source Files

- `README.md`
- `docker-compose.yml`
- `backend/cmd/pentagi/main.go`
- `backend/pkg/server/router.go`
- `backend/pkg/graph/schema.graphqls`
- `frontend/src/app.tsx`
- `CLAUDE.md`

---

---
title: "Overview"
description: "What PentAGI exposes: autonomous multi-agent pentests in Docker, BYOK LLM providers, web UI, REST and GraphQL under /api/v1, and the shortest path from deploy to first flow."
---

PentAGI is a self-hosted, BYOK autonomous penetration testing platform. A Go API process (`backend/cmd/pentagi`) loads config from the environment, migrates PostgreSQL + pgvector, attaches to the Docker runtime, restores active flows, and serves HTTPS (default port `8443`) with a React SPA plus REST and GraphQL under the single base path `/api/v1`. Users and automation create **flows**; specialist LLM agents decompose work into **tasks** and **subtasks**, execute tools inside Docker-isolated containers, and persist results, logs, and vector memory.

<Info>
PentAGI is an autonomous and assistant-guided pentest runner, not a CALDERA-style BAS product with predefined adversary campaigns. Provider choice is yours: cloud keys, Ollama, or OpenAI-compatible custom endpoints (`LLM_SERVER_*`).
</Info>

## What you get

| Surface | Default location | Role |
|---|---|---|
| Web UI | `https://localhost:8443` | Flows, dashboard, settings, knowledge, resources, templates |
| REST + GraphQL | `/api/v1/*` | Auth, flows, logs, knowledge, providers, tokens, analytics |
| Swagger UI | `/api/v1/swagger/*` | OpenAPI exploration |
| GraphQL playground | `/api/v1/graphql/playground` | Schema exploration (auth still required for operations) |
| GraphQL endpoint | `Any /api/v1/graphql` | Queries, mutations, WebSocket subscriptions |
| Core compose stack | `docker-compose.yml` | `pentagi`, `pgvector`, `pgexporter`, `scraper` |
| Optional overlays | `docker-compose-observability.yml`, `docker-compose-langfuse.yml`, `docker-compose-graphiti.yml` | OTEL/Grafana stack, LLM analytics, Neo4j knowledge graph |
| TUI installer | `backend/cmd/installer` | Guided `.env`, SSL, deploy, admin password reset |

Default listen bind is `127.0.0.1:8443` via `PENTAGI_LISTEN_IP` / `PENTAGI_LISTEN_PORT`. SSL is on by default (`SERVER_USE_SSL=true`) when certificate paths are present.

## Runtime architecture

```mermaid
flowchart TB
  subgraph clients [Clients]
    UI[React SPA frontend/src]
    REST[REST clients Bearer or session]
    GQL[GraphQL clients + WS]
  end

  subgraph api [API process cmd/pentagi]
    Router[Gin router /api/v1]
    Auth[Session cookie / OAuth / API tokens]
    FC[FlowController]
    PC[ProviderController]
    Subs[SubscriptionsController]
  end

  subgraph workers [Flow workers]
    FW[FlowWorker]
    TW[TaskWorker]
    SW[SubtaskWorker]
    AW[AssistantWorker]
    Agents[Specialist agents]
  end

  subgraph sandbox [Docker sandbox]
    Term[terminal / file tools]
    Img[Default and pentest images]
  end

  subgraph data [Data plane]
    PG[(PostgreSQL + pgvector)]
    Scrap[scraper browser]
    Graphiti[Graphiti + Neo4j optional]
  end

  subgraph external [External BYOK]
    LLM[LLM providers]
    Search[Search engines]
  end

  UI --> Router
  REST --> Router
  GQL --> Router
  Router --> Auth
  Auth --> FC
  Auth --> PC
  FC --> FW
  FW --> TW
  TW --> SW
  FW --> AW
  SW --> Agents
  Agents --> Term
  Agents --> LLM
  Agents --> Search
  Agents --> Scrap
  Agents --> PG
  Agents --> Graphiti
  FC --> Subs
  Subs --> GQL
```

Startup sequence in `backend/cmd/pentagi/main.go`:

1. Load `config.Config` from environment.
2. Optionally attach Langfuse and OpenTelemetry clients (fail only if misconfigured, not if absent).
3. Open PostgreSQL (`DATABASE_URL`), share one pool with sqlc + GORM, create a pgxpool for vector ops.
4. Run goose migrations from embedded `backend/migrations/sql/`.
5. Initialize Docker client, LLM provider controller, subscription hub, and flow controller.
6. `LoadFlows` restores in-flight work after restart.
7. Bind `SERVER_HOST`:`SERVER_PORT` with TLS or plain HTTP.

## Execution model

Hierarchy used across REST, GraphQL, and the UI:

| Unit | Meaning |
|---|---|
| **Flow** | Top-level pentest session (persistent) |
| **Task** | User objective inside a flow |
| **Subtask** | System-generated sequential step (Generator / Refiner) |
| **Assistant** | Interactive chat mode on a flow; optional agent delegation |

Lifecycle states (`StatusType`):

| State | Meaning |
|---|---|
| `created` | Record exists, not running |
| `running` | Agents executing |
| `waiting` | Blocked on user input (`ask` barrier or `putUserInput`) |
| `finished` | Completed successfully |
| `failed` | Unrecoverable error |

Primary GraphQL control surface:

| Operation | Behavior |
|---|---|
| `createFlow(modelProvider, input, resourceIds?)` | Start autonomous work |
| `putUserInput(flowId, input, …)` | Answer `waiting` or add follow-up |
| `stopFlow(flowId)` | Stop running work |
| `finishFlow(flowId)` | Mark flow finished |
| `createAssistant` / `callAssistant` / `stopAssistant` | Assistant mode |

### Specialist agents

Per-agent model settings use `AgentConfigType` and embedded prompt templates (`PromptType`):

| Agent | Role |
|---|---|
| `primary_agent` | Orchestrates a subtask |
| `generator` / `refiner` | Plan and revise subtask lists |
| `pentester` | Exploit / vulnerability work |
| `coder` | Write and maintain code |
| `installer` | Environment and tool setup |
| `searcher` / `enricher` | Research and multi-source enrichment |
| `memorist` | Long-term memory store/search |
| `adviser` | Expert guidance |
| `reflector` | Correct non-tool unstructured replies |
| `assistant` | Interactive flow-scoped chat |
| reporter (prompt/report path) | Final task reporting |

Optional supervision env flags include `EXECUTION_MONITOR_ENABLED`, same-tool and total tool-call limits, `MAX_GENERAL_AGENT_TOOL_CALLS`, `MAX_LIMITED_AGENT_TOOL_CALLS`, and `AGENT_PLANNING_STEP_ENABLED` (useful for smaller local models).

### Tools and isolation

Agents do not run host shell commands directly. Terminal and file tools execute inside Docker containers (`DOCKER_HOST`, socket mount, optional `DOCKER_INSIDE` / `DOCKER_NET_ADMIN`). User uploads and resources appear under `/work` paths inside the worker. Network tools (browser via scraper, DuckDuckGo, Google CSE, Tavily, Traversaal, Perplexity, Sploitus, Searxng) activate only when corresponding env keys or URLs are set. Barrier tools `done` and `ask` control subtask completion and human checkpoints (`ASK_USER`).

## API surface under `/api/v1`

Base path is fixed as `const baseURL = "/api/v1"` in the Gin router.

### Auth

| Method | Path | Notes |
|---|---|---|
| `POST` | `/auth/login` | Local session login |
| `GET` | `/auth/logout` | End session |
| `GET` | `/auth/authorize` | OAuth start |
| `GET`/`POST` | `/auth/login-callback` | OAuth callback |
| `GET` | `/info` | Session / auth info (try-auth) |
| `PUT` | `/user/password` | Local user password change |

Session cookies use the `auth` store and `COOKIE_SIGNING_SALT`. Programmatic access uses Bearer API tokens (`Authorization: Bearer …`) with privilege scopes; token CRUD is session-user gated under `/tokens`. OAuth Google and GitHub register only when `PUBLIC_URL` and client credentials are set.

### Resource groups (authenticated)

| Group | Examples |
|---|---|
| Flows | `POST/GET/PUT/DELETE /flows`, `/flows/:id/graph` |
| Tasks / subtasks | `/flows/:id/tasks`, nested subtasks |
| Files / resources | `/flows/:id/files`, `/resources` |
| Containers / toolcalls | `/containers`, `/toolcalls` |
| Assistants | `/flows/:id/assistants` |
| Logs | agent, assistant, msg, term, search, vecstore, screenshots |
| Knowledge | `/knowledge` CRUD + search |
| Providers / settings | `GET /providers`, `GET /settings` |
| Prompts / users / roles | admin and settings management |
| Analytics | `/usage` |
| GraphQL | `Any /graphql` |

Frontend SPA routes (served from static files or reverse proxy): `/dashboard`, `/flows`, `/settings`, `/templates`, `/resources`, `/knowledges`, `/login`, `/oauth`, `/chat`.

## BYOK LLM providers

No hosted model is required. Wire one or more providers via environment variables or UI provider profiles.

| Type (`ProviderType`) | Typical env keys |
|---|---|
| `openai` | `OPEN_AI_KEY`, `OPEN_AI_SERVER_URL` |
| `anthropic` | `ANTHROPIC_API_KEY`, `ANTHROPIC_SERVER_URL` |
| `gemini` | `GEMINI_API_KEY`, `GEMINI_SERVER_URL` |
| `bedrock` | `BEDROCK_*` region and credentials |
| `ollama` | `OLLAMA_SERVER_URL`, optional API key and config path |
| `custom` | `LLM_SERVER_URL`, `LLM_SERVER_KEY`, model, YAML config path |
| `deepseek` / `glm` / `kimi` / `qwen` | respective `*_API_KEY` and server URL |

OpenAI-compatible aggregators (OpenRouter, DeepInfra, vLLM, Azure-style endpoints) map through `custom` / `LLM_SERVER_*` plus YAML under `examples/configs/`. GraphQL exposes `testAgent` and `testProvider` before committing flows. Embeddings (`EMBEDDING_*`) power knowledge and memory search when configured; without an embedder, embedding-dependent knowledge ops error while the server still starts.

## Data and optional integrations

| Component | Required? | Purpose |
|---|---|---|
| PostgreSQL + pgvector (`vxcontrol/pgvector`) | Yes | Flows, users, logs, vector memory |
| Docker socket or remote Docker API | Yes | Sandbox workers |
| Scraper (`vxcontrol/scraper`) | Core compose | Browser tool / screenshots |
| Observability overlay | No | OTEL → VictoriaMetrics, Jaeger, Loki, Grafana (`OTEL_HOST`) |
| Langfuse overlay | No | LLM analytics (`LANGFUSE_*`) |
| Graphiti overlay | No | Neo4j knowledge graph (`GRAPHITI_*`, `graphiti_search`) |

Compose networks: `pentagi-network` (core), plus `observability-network` and `langfuse-network` for overlays. Create core networks first if overlays fail with missing-network errors.

## Deploy to first flow

<Steps>
  <Step title="Prerequisites">
    Docker and Docker Compose. Host access to the Docker API (default socket mount). At least one LLM provider credential or reachable local endpoint.
  </Step>
  <Step title="Configure environment">
    Copy `.env.example` to `.env`. Set at least one provider key (for example `OPEN_AI_KEY` or `OLLAMA_SERVER_URL`). Change security-sensitive values (`COOKIE_SIGNING_SALT`, DB password, SSL materials) before production use.
  </Step>
  <Step title="Start the core stack">
```bash
docker compose up -d
```
    Core services: `pentagi`, `pgvector`, `pgexporter`, `scraper`. Optional:

```bash
docker compose -f docker-compose.yml -f docker-compose-observability.yml up -d
docker compose -f docker-compose.yml -f docker-compose-langfuse.yml up -d
docker compose -f docker-compose.yml -f docker-compose-graphiti.yml up -d
```
  </Step>
  <Step title="Open the UI and secure the admin account">
    Open `https://localhost:8443`. Fresh install seeds:

    - Email: `admin@pentagi.com`
    - Password: `admin`
    - `password_change_required = true`

    Change the password immediately. There is no public self-service signup; admins manage users via `/api/v1/users/`. Lost admin password: installer maintenance reset path.
  </Step>
  <Step title="Create a flow">
    In the UI: **Flows → New**, pick a configured provider, enter an objective (see sample prompts under `examples/prompts/`). Or mutate GraphQL `createFlow` / REST `POST /api/v1/flows` with a Bearer token from **Settings → API tokens**.
  </Step>
  <Step title="Verify health">
    - UI loads dashboard and providers list.
    - Swagger: `https://localhost:8443/api/v1/swagger/index.html`
    - Flow status transitions `created` → `running` (or `waiting` if `ask` fires).
    - Toolcalls and terminal logs appear under the flow; reports support web view, clipboard, Markdown, and PDF download (not JSON export).
  </Step>
</Steps>

<Tip>
For guided setup (system checks, `.env` generation, SSL hardening, compose deploy), use the interactive installer (`backend/cmd/installer`) instead of hand-editing `.env`.
</Tip>

## Repository layout

:::files
pentagi/
├── backend/
│   ├── cmd/pentagi/          # API server entrypoint
│   ├── cmd/installer/        # TUI deployment wizard
│   ├── cmd/{c,e,f}tester/    # Container, embedding, function testers
│   ├── pkg/server/           # Gin router, auth, REST services
│   ├── pkg/graph/            # schema.graphqls + gqlgen resolvers
│   ├── pkg/providers/        # LLM adapters + config.yml baselines
│   ├── pkg/tools/            # Tool registry and executors
│   ├── pkg/controller/       # Flow/task/subtask workers
│   ├── pkg/docker/           # Sandbox Docker client
│   └── migrations/sql/       # goose schema + seed admin
├── frontend/src/             # React + Apollo SPA
├── observability/            # Grafana, OTEL, Jaeger, Loki configs
├── examples/                 # Provider YAML, prompts, guides
├── docker-compose*.yml       # Core + optional stacks
└── .env.example              # Authoritative env catalog
:::

## Capability boundaries

- Not a predefined-campaign BAS or adversary-emulation product.
- JSON flow-report export is not a supported UI output format today.
- `LLM_SERVER_*` custom endpoints work but are marked experimental in project docs and may evolve.
- The `pentagi` compose service runs as `root` when using the Docker socket; TCP Docker endpoints can drop socket root if you reconfigure access.
- Default bind is localhost-only; external access needs `PENTAGI_LISTEN_IP`, `PUBLIC_URL`, and `CORS_ORIGINS` aligned to real hostnames/IPs (never `0.0.0.0` in URL/CORS lists).

## Next

<CardGroup cols={2}>
  <Card title="Installation" href="/installation">
    Core compose, volumes, SSL, and optional observability / Langfuse / Graphiti overlays.
  </Card>
  <Card title="Quickstart" href="/quickstart">
    First successful run: LLM key, compose up, admin password, create a flow.
  </Card>
  <Card title="Interactive installer" href="/installer">
    TUI wizard for system checks, `.env`, deploy, and admin password reset.
  </Card>
  <Card title="Flows, tasks, and subtasks" href="/flows-tasks-subtasks">
    Lifecycle states, Generator/Refiner plans, assistant mode, stop/finish boundaries.
  </Card>
  <Card title="Configure LLM providers" href="/configure-llm-providers">
    Wire OpenAI, Anthropic, Gemini, Bedrock, DeepSeek, GLM, Kimi, Qwen, Ollama.
  </Card>
  <Card title="REST API" href="/rest-api">
    Gin routes under `/api/v1` and Swagger at `/api/v1/swagger`.
  </Card>
  <Card title="GraphQL API" href="/graphql-api">
    Query, Mutation, Subscription surface and WebSocket log streams.
  </Card>
  <Card title="Environment variables" href="/environment-variables">
    Full Config struct and `.env.example` reference with defaults.
  </Card>
</CardGroup>