# Deployment Strategies for Pentagi: 3 Production-Ready Architectures Explained

> Explore the three production-ready deployment strategies for Pentagi: single-node Docker Compose, secure distributed two-node, and guided installer wizard. Learn containerized architectures from vxcontrol/pentagi.

- Repository: [VXControl/pentagi](https://github.com/vxcontrol/pentagi)
- Tags: architecture
- Published: 2026-03-21

---

**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`](https://github.com/vxcontrol/pentagi/blob/main/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`](https://github.com/vxcontrol/pentagi/blob/main/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`](https://github.com/vxcontrol/pentagi/blob/main/docker-compose-observability.yml)

Deploying locally requires minimal configuration:

```bash

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

```bash

# 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`](https://github.com/vxcontrol/pentagi/blob/main/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`](https://github.com/vxcontrol/pentagi/blob/main/docker-compose.yml) configuration:

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

```dotenv

# 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`](https://github.com/vxcontrol/pentagi/blob/main/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:

```bash

# 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`](https://github.com/vxcontrol/pentagi/blob/main/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`](https://github.com/vxcontrol/pentagi/blob/main/backend/docs/installer.md)**, while environment variable parsing logic resides in **[`backend/pkg/config/config.go`](https://github.com/vxcontrol/pentagi/blob/main/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`](https://github.com/vxcontrol/pentagi/blob/main/docker-compose.yml) with optional stacks for observability ([`docker-compose-observability.yml`](https://github.com/vxcontrol/pentagi/blob/main/docker-compose-observability.yml)), Langfuse ([`docker-compose-langfuse.yml`](https://github.com/vxcontrol/pentagi/blob/main/docker-compose-langfuse.yml)), and Graphiti ([`docker-compose-graphiti.yml`](https://github.com/vxcontrol/pentagi/blob/main/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`](https://github.com/vxcontrol/pentagi/blob/main/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`](https://github.com/vxcontrol/pentagi/blob/main/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`](https://github.com/vxcontrol/pentagi/blob/main/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`](https://github.com/vxcontrol/pentagi/blob/main/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`](https://github.com/vxcontrol/pentagi/blob/main/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`](https://github.com/vxcontrol/pentagi/blob/main/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.