Fully autonomous AI Agents system capable of performing complex penetration testing tasks
Go ai-agentsai-security-toolanthropicautonomous-agentsgolanggptgraphqlmulti-agent-systemoffensive-securityopen-sourceopenaipenetration-testingpenetration-testing-toolsreactsecurity-automationsecurity-testingsecurity-toolsself-hosted
docs: add installing and configuring guide for first deployment
mason5052ebfd2bd9e9f5
diff --git a/README.md b/README.mdindex 0736ab93..c029f743 100644--- a/README.md+++ b/README.md@@ -569,6 +569,8 @@ The system uses Docker containers for isolation and easy deployment, with separa## 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](examples/guides/installation_configuration.md) guide. The sections below remain the detailed reference for each step.+### System Requirements- Docker and Docker Compose (or Podman - see [Podman configuration](#running-pentagi-with-podman))diff --git a/examples/guides/installation_configuration.md b/examples/guides/installation_configuration.mdnew file mode 100644index 00000000..8257ca91--- /dev/null+++ b/examples/guides/installation_configuration.md@@ -0,0 +1,181 @@+# Installing and Configuring PentAGI++This guide is the bridge between installing PentAGI and using it. It walks you+through a first deployment in order: pick an installation method, set the core+server variables, configure and test at least one LLM provider, configure the+embedding provider, optionally add search and observability, then start the+stack and verify it before your first login.++It is intentionally concise and links to the detailed reference sections in the+main [README](https://github.com/vxcontrol/pentagi#readme) instead of repeating+them. When you finish here, continue with+[How to Use PentAGI After Login](https://github.com/vxcontrol/pentagi#how-to-use-pentagi-after-login).++## Before you start++- Docker and Docker Compose (or Podman), 2+ vCPU, 4+ GB RAM, 20+ GB free disk,+ and outbound internet access for pulling images and reaching LLM providers.+- At least one LLM provider you can authenticate to (OpenAI, Anthropic, Gemini,+ AWS Bedrock, or a local/Ollama/OpenAI-compatible backend). PentAGI will not+ run without one.+- Decide how you want to install: the interactive installer (recommended) or a+ manual Docker Compose deployment.++## Step 1 - Choose an installation method++### Option A: Interactive installer (recommended)++The installer is a terminal UI that runs system checks, writes a sane `.env`,+helps you configure LLM and search providers, hardens credentials, and starts+the stack for you. Download the build for your platform and run it, then follow+the prompts. See+[Using Installer (Recommended)](https://github.com/vxcontrol/pentagi#using-installer-recommended)+for download links and the Docker socket permission notes.++If you use the installer, it can take you through most of Steps 2-6 below+interactively. You can still use this guide as a checklist of what to confirm.++### Option B: Manual Docker Compose++Create a working directory, copy `.env.example` to `.env`, fill in your keys,+and bring up the stack. The full sequence (including the example provider config+files and the `docker compose up -d` command) is in+[Manual Installation](https://github.com/vxcontrol/pentagi#manual-installation).++## Step 2 - Set the core server variables++Whichever method you used, confirm these in your `.env` before exposing the+instance to anything but localhost:++- `PUBLIC_URL` - the URL users and the browser will actually load, for example+ `https://pentagi.example.com` or `https://192.168.1.100:8443`. Use the real+ hostname or IP, never `0.0.0.0`.+- `CORS_ORIGINS` - every origin that will reach the UI, comma-separated. Include+ both `https://localhost:8443` and your external URL if you use both.+- `PENTAGI_LISTEN_IP` / `PENTAGI_LISTEN_PORT` - keep the default `127.0.0.1` for+ localhost-only, or set the IP to `0.0.0.0` to accept external connections.+- `COOKIE_SIGNING_SALT` and the database passwords+ (`PENTAGI_POSTGRES_PASSWORD`, `NEO4J_PASSWORD`) - change these away from the+ defaults before real use.++For external access, firewall rules, and certificate notes, see+[Accessing PentAGI from External Networks](https://github.com/vxcontrol/pentagi#accessing-pentagi-from-external-networks).++## Step 3 - Configure and test an LLM provider++Set the credentials for at least one provider in `.env`. Each provider has its+own reference section with the exact variables and supported models:++- [OpenAI](https://github.com/vxcontrol/pentagi#openai-provider-configuration)+ (`OPEN_AI_KEY`, `OPEN_AI_SERVER_URL`)+- [Anthropic](https://github.com/vxcontrol/pentagi#anthropic-provider-configuration)+ (`ANTHROPIC_API_KEY`, `ANTHROPIC_SERVER_URL`)+- [Google AI (Gemini)](https://github.com/vxcontrol/pentagi#google-ai-gemini-provider-configuration)+ (`GEMINI_API_KEY`, `GEMINI_SERVER_URL`)+- [AWS Bedrock](https://github.com/vxcontrol/pentagi#aws-bedrock-provider-configuration)+ (`BEDROCK_REGION` plus one auth method)+- [Custom OpenAI-compatible / local](https://github.com/vxcontrol/pentagi#custom-llm-provider-configuration)+ (`LLM_SERVER_URL`, `LLM_SERVER_KEY`, `LLM_SERVER_MODEL`) and+ [Ollama](https://github.com/vxcontrol/pentagi#ollama-provider-configuration)++Before starting a full flow, confirm the provider actually answers and supports+the agent behaviors PentAGI needs by running `ctester`:++```bash+# From a local Go environment (run inside the backend directory)+go run cmd/ctester/*.go -verbose++# Or from the running container+docker exec -it pentagi /opt/pentagi/bin/ctester -verbose+```++Full usage, including `-type`, `-config`, and per-agent testing, is in+[Testing LLM Agents](https://github.com/vxcontrol/pentagi#testing-llm-agents).+If `ctester` reports tool-call or function-call problems with a custom,+llama.cpp, vLLM, or SGLang backend, that points at the backend's tool-call+parser rather than PentAGI itself.++## Step 4 - Configure and test the embedding provider++PentAGI uses embeddings for semantic search, knowledge storage, and memory. The+default provider is OpenAI; when `EMBEDDING_URL` and `EMBEDDING_KEY` are empty+and `EMBEDDING_PROVIDER=openai`, it falls back to your `OPEN_AI_SERVER_URL` and+`OPEN_AI_KEY`. Relevant variables: `EMBEDDING_PROVIDER`, `EMBEDDING_MODEL`,+`EMBEDDING_URL`, `EMBEDDING_KEY`, `EMBEDDING_BATCH_SIZE`,+`EMBEDDING_MAX_TEXT_BYTES`, `EMBEDDING_STRIP_NEW_LINES`.++Verify embeddings with `etester`:++```bash+# Local Go environment+go run cmd/etester/main.go test -verbose++# Running container+docker exec -it pentagi /opt/pentagi/bin/etester test+```++If you later change the embedding provider or model, flush and reindex the+knowledge base. Details and the full command set are in+[Embedding Configuration and Testing](https://github.com/vxcontrol/pentagi#embedding-configuration-and-testing).++## Step 5 - (Optional) Configure search providers++Search providers improve research quality but are optional. PentAGI supports+DuckDuckGo (`DUCKDUCKGO_ENABLED`), Sploitus (`SPLOITUS_ENABLED`), Google+(`GOOGLE_API_KEY`, `GOOGLE_CX_KEY`), Tavily (`TAVILY_API_KEY`), Traversaal+(`TRAVERSAAL_API_KEY`), Perplexity (`PERPLEXITY_API_KEY`), and a self-hosted+Searxng instance (`SEARXNG_URL`). Set the keys for the engines you want in+`.env`; the manual installation section shows the full block of search+variables.++## Step 6 - (Optional) Enable Graphiti, Langfuse, and observability++These are separate, optional stacks brought up with additional compose files:++- Graphiti knowledge graph (`GRAPHITI_ENABLED=true`, `GRAPHITI_URL`, plus the+ `NEO4J_*` settings) via `docker-compose-graphiti.yml`.+- Langfuse analytics via `docker-compose-langfuse.yml`.+- Monitoring (Grafana / OpenTelemetry) via `docker-compose-observability.yml`.++Run the base `docker-compose.yml` first so the shared Docker networks exist,+then bring up the optional stacks. The same ordering note appears in the manual+installation section.++## Step 7 - Start and verify++1. Start the stack: `docker compose up -d`.+2. Watch the logs until the backend is ready:+ `docker compose logs -f pentagi`.+3. Re-run `ctester` and `etester` if you changed any provider settings. For+ deeper checks of individual agent functions and tools, use `ftester` (see+ [Function Testing with ftester](https://github.com/vxcontrol/pentagi#function-testing-with-ftester)).+4. Open `https://localhost:8443` (or your `PUBLIC_URL`) and sign in with the+ default `[email protected]` / `admin`, then change the password immediately.++After the server is running, several areas are managed in the web console under+Settings (Providers, Prompts, PentAGI API tokens), while LLM and search+credentials, Langfuse, Graphiti, and MCP remain server-side configuration. See+[Current Web Settings Coverage](https://github.com/vxcontrol/pentagi#current-web-settings-coverage)+for the exact split.++## First-run configuration checklist++- [ ] Docker/Podman, CPU, RAM, and disk meet the minimums+- [ ] Installation method chosen (installer or manual Compose)+- [ ] `PUBLIC_URL` and `CORS_ORIGINS` set to the real hostname/IP (not `0.0.0.0`)+- [ ] `COOKIE_SIGNING_SALT` and database passwords changed from defaults+- [ ] At least one LLM provider configured and passing `ctester`+- [ ] Embedding provider configured and passing `etester`+- [ ] Search providers configured (optional)+- [ ] Graphiti / Langfuse / observability enabled if needed (optional)+- [ ] Stack started, logs healthy, default admin password changed++## Next step++Continue with+[How to Use PentAGI After Login](https://github.com/vxcontrol/pentagi#how-to-use-pentagi-after-login)+to create your first flow, use prompt templates, and review results.++For hardened or fully local deployments, see the+[Worker Node Setup](worker_node.md) and+[vLLM + Qwen3.5-27B-FP8](vllm-qwen35-27b-fp8.md) guides.