Deployment Strategies for Pentagi: 3 Production-Ready Architectures Explained

Pentagi supports three primary deployment strategies—single-node Docker Compose for local development, distributed two-node architecture for secure production, and an interactive installer wizard for guided configuration—all containerized and defined in the vxcontrol/pentagi repository.

The vxcontrol/pentagi repository provides flexible deployment strategies for Pentagi to accommodate everything from rapid proof-of-concept testing to hardened, compliance-ready production environments. All approaches use the same Docker-based images but differ in topology, security isolation, and operational complexity. The core definitions reside in docker-compose.yml and supporting configuration files, while advanced scenarios leverage the distributed worker guide and interactive installer source code.

Single-Node Docker Compose Deployment

The canonical single-node deployment runs all core services on one host using docker-compose.yml. This strategy defines three isolated networks (pentagi-network, observability-network, langfuse-network) and bundles the Pentagi API, PostgreSQL with pgvector, and optional observability stacks.

Key services defined in the compose file include:

• pentagi – The Go backend serving GraphQL/REST APIs and UI proxy
• pgvector – PostgreSQL database with vector extension for semantic memory
• scraper – Optional isolated headless browser for web search operations
• grafana, jaeger, loki, victoriametrics – Optional observability stack enabled via docker-compose-observability.yml

Deploying locally requires minimal configuration:

# Download the core compose file

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

# Initialize environment variables

cp .env.example .env

# Edit .env to set OPEN_AI_KEY and other LLM credentials

# Launch the stack

docker compose up -d

The API becomes available at https://localhost:8443 (or the IP specified in PENTAGI_LISTEN_IP). For enhanced capabilities, combine optional stacks:

# Fetch optional configurations

curl -O https://raw.githubusercontent.com/vxcontrol/pentagi/master/docker-compose-observability.yml
curl -O https://raw.githubusercontent.com/vxcontrol/pentagi/master/docker-compose-langfuse.yml
curl -O https://raw.githubusercontent.com/vxcontrol/pentagi/master/docker-compose-graphiti.yml

# Deploy with full observability and knowledge graph

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

Distributed Two-Node Worker Architecture

For production security, Pentagi implements a distributed two-node architecture that isolates the control plane from the execution plane. The controller host runs core services (pentagi, pgvector, observability), while a separate worker node runs Docker-in-Docker (dind) containers that execute penetration-testing tools. This limits the blast radius if a tool container becomes compromised.

The complete implementation guide lives in examples/guides/worker_node.md. Key configuration steps include:

1. Provision the worker host with Docker-in-Docker running in privileged mode
2. Expose the Docker socket via TCP (typically port 2375) or secure TLS tunnel
3. Configure the controller to target the remote daemon

Worker-side docker-compose.yml configuration:

services:
  dind:
    image: docker:23-dind
    privileged: true
    environment:
      - DOCKER_TLS_CERTDIR=/certs
    volumes:
      - dind-data:/var/lib/docker
    networks:
      - pentagi-network

Controller environment configuration (.env):

# Point Pentagi to the remote worker

DOCKER_HOST=tcp://192.0.2.45:2375
DOCKER_TLS_VERIFY=0  # Enable TLS verification in production environments

With DOCKER_HOST set, the Pentagi controller schedules tool execution containers on the worker node while maintaining all data and API services on the controller host. The worker can reside on a separate VLAN or behind additional firewalls for defense-in-depth.

Interactive Installer Wizard

The interactive installer provides a terminal-based TUI (built with bubbletea) that automates environment validation and configuration. Located at backend/cmd/installer/main.go, the wizard performs system checks, collects LLM provider credentials (OpenAI, Anthropic, Ollama), and toggles optional components like observability, Langfuse, Graphiti, and worker-node deployment.

Building and running the installer:

# Compile the installer binary

go build -o installer ./backend/cmd/installer

# Execute with elevated privileges for Docker socket access

sudo ./installer

The installer logic defined in main.go walks through:

• Docker version verification and socket accessibility
• LLM API key configuration and search engine integration
• Optional stack selection (observability, knowledge graph, Langfuse analytics)
• Worker node enablement – adds DOCKER_HOST configuration automatically if selected
• Generation of a validated .env file and automatic docker compose orchestration

Documentation for the installer UI and supported options is available in backend/docs/installer.md, while environment variable parsing logic resides in backend/pkg/config/config.go.

Comparing Pentagi Deployment Strategies

Strategy	Setup Complexity	Security Isolation	Best For
Single-node Docker Compose	Very low – single command	Shared host (limited)	Local development, proof-of-concept, small teams
Distributed two-node	Moderate – requires second host	High – execution sandboxed on dedicated worker	Production, compliance environments, untrusted target testing
Interactive installer	Low-to-moderate – guided prompts	Configurable (depends on selections)	First-time users, reproducible team deployments, automated provisioning

The single-node strategy offers the fastest path to running Pentagi but executes security tools on the same host as the database and API. The distributed architecture adds operational overhead but provides critical isolation for production penetration testing. The installer bridges both approaches by generating configurations for either topology based on user selections.

Summary

• Single-node Docker Compose deploys all services via docker-compose.yml with optional stacks for observability (docker-compose-observability.yml), Langfuse (docker-compose-langfuse.yml), and Graphiti (docker-compose-graphiti.yml), suitable for testing and small deployments.
• Distributed two-node architecture separates the controller (API/database) from the worker node (tool execution via Docker-in-Docker), configured through examples/guides/worker_node.md using DOCKER_HOST environment variables for production security.
• Interactive installer automates configuration through a TUI wizard in backend/cmd/installer/main.go, generating validated .env files and supporting both single-node and worker-based deployments without manual file editing.

Frequently Asked Questions

What is the most secure deployment strategy for production Pentagi installations?

The distributed two-node architecture provides the highest security by isolating tool execution on a dedicated worker node running Docker-in-Docker. According to examples/guides/worker_node.md, this configuration prevents compromised security tools from accessing the controller host's database or API services, effectively limiting the blast radius during penetration testing operations.

How do I enable observability features when deploying Pentagi?

Observability requires combining the core compose file with docker-compose-observability.yml, which defines Grafana, Jaeger, Loki, and VictoriaMetrics services. You can deploy these manually via docker compose -f docker-compose.yml -f docker-compose-observability.yml up -d, or enable them through the interactive installer wizard at backend/cmd/installer/main.go, which automatically configures the integrated monitoring stack.

Can I deploy Pentagi using the interactive installer on a server with no GUI?

Yes. The interactive installer is a terminal-based TUI (text user interface) built with bubbletea that requires only a terminal and Docker socket access. It runs entirely via command line, making it suitable for SSH sessions on headless servers, and outputs a production-ready .env file and Docker Compose configuration without requiring manual YAML editing.

What environment variables are required for connecting Pentagi to a remote worker node?

The controller requires DOCKER_HOST set to the worker's TCP address (e.g., tcp://192.0.2.45:2375) and optionally DOCKER_TLS_VERIFY for TLS configuration. These variables, parsed by backend/pkg/config/config.go, instruct the Pentagi backend to schedule security tool containers on the remote Docker daemon rather than the local host, as documented in the worker node deployment guide.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}