# Security Best Practices for Pentagi Deployment: A Production Hardening Guide

> Secure your Pentagi deployment with production hardening best practices. Use the built-in installer, enforce TLS, and isolate worker nodes for a robust, secure system.

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

---

**Run the built-in installer to generate cryptographically-secure secrets, enforce TLS verification for all connections, and isolate worker nodes to create a hardened, production-grade PentAGI deployment.**

PentAGI is a self-hosted, AI-driven penetration-testing platform developed by vxcontrol/pentagi. Because it executes powerful security tools and arbitrary code inside Docker containers, following strict **security best practices for Pentagi deployment** is mandatory to prevent privilege escalation, data exfiltration, and unauthorized system access.

## Use the Built-In Installer to Automate Secret Hardening

The interactive installer eliminates hard-coded credentials by automatically generating cryptographically-secure values for every sensitive variable. In [`backend/cmd/installer/hardening/hardening.go`](https://github.com/vxcontrol/pentagi/blob/main/backend/cmd/installer/hardening/hardening.go), the `GenerateHardenedEnv()` function (lines 44-48) replaces placeholders like `COOKIE_SIGNING_SALT` and `PENTAGI_POSTGRES_PASSWORD` with high-entropy strings.

The generation policies are defined in `varsHardeningPolicies` (lines 102-108), specifying hex strings, UUIDs, and random passwords that satisfy the complexity rules documented in [`CLAUDE.md`](https://github.com/vxcontrol/pentagi/blob/main/CLAUDE.md) (lines 8-12).

```bash

# Clone and run the installer to create a hardened .env file

git clone https://github.com/vxcontrol/pentagi
cd pentagi
./installer   # Interactive UI generates secure defaults automatically

```

After completion, inspect the generated credentials to verify no default passwords remain:

```bash
cat .env | grep -E 'COOKIE_SIGNING_SALT|PENTAGI_POSTGRES_PASSWORD'

```

## Enforce TLS Verification for External Connections

All outbound connections to LLM providers and search engines must verify SSL certificates. The configuration flag `ExternalSSLInsecure` in [`backend/pkg/config/config.go`](https://github.com/vxcontrol/pentagi/blob/main/backend/pkg/config/config.go) (lines 92-94) controls this behavior and defaults to `false`.

**Never set `EXTERNAL_SSL_INSECURE=true`** in production environments. This flag should only be used temporarily when testing against servers with self-signed certificates. For private certificate authorities, mount the CA bundle and set `EXTERNAL_SSL_CA_PATH`.

```env

# .env – secure TLS configuration

EXTERNAL_SSL_INSECURE=false
EXTERNAL_SSL_CA_PATH=/etc/ssl/certs/internal_ca.pem

```

The TLS implementation in [`backend/pkg/system/utils.go`](https://github.com/vxcontrol/pentagi/blob/main/backend/pkg/system/utils.go) (lines 84-94) enforces these settings for all HTTP clients:

```go
tr := &http.Transport{
    TLSClientConfig: &tls.Config{
        InsecureSkipVerify: cfg.ExternalSSLInsecure, // Must remain false
    },
}

```

## Isolate Execution with a Two-Node Architecture

Separate the control plane from execution environments to limit blast radius. The primary node runs the API, UI, database, and orchestration logic, while a dedicated worker node handles sandboxed Docker-in-Docker containers. This architecture is documented in [`README.md`](https://github.com/vxcontrol/pentagi/blob/main/README.md) (lines 10-13) and detailed in [`examples/guides/worker_node.md`](https://github.com/vxcontrol/pentagi/blob/main/examples/guides/worker_node.md).

Benefits include network isolation (workers cannot access internal LAN services) and TLS-authenticated Docker communication via `DOCKER_TLS_VERIFY` and `DOCKER_CERT_PATH`.

```yaml

# docker-compose.yml on primary node

services:
  pentagi:
    image: vxcontrol/pentagi:latest
    environment:
      - PENTAGI_WORKER_URL=tls://worker.example.com:2376
      - DOCKER_TLS_VERIFY=1
      - DOCKER_CERT_PATH=/certs
    ports: ["8443:8443"]

```

```yaml

# docker-compose.yml on worker node

services:
  worker:
    image: vxcontrol/pentagi-worker:latest
    privileged: false
    environment:
      - DOCKER_TLS_VERIFY=1
    volumes:
      - /var/lib/docker:/var/lib/docker
      - ./certs:/certs

```

## Run Docker in Rootless Mode to Prevent Privilege Escalation

Avoid running containers as root. The [`README.md`](https://github.com/vxcontrol/pentagi/blob/main/README.md) security warning (lines 600-601) explicitly cautions against adding users to the Docker group, as this effectively grants root access.

**Production deployments** must use **rootless Docker** on worker nodes. The main PentAGI service already runs as the `pentagi` user (non-root UID) in the Dockerfile.

```bash

# Install and enable rootless Docker on the worker

export DOCKER_HOST=unix:///run/user/$(id -u)/docker.sock
dockerd-rootless-setuptool.sh install

```

If you must expose the Docker API over TCP, always enable TLS encryption and client certificate verification.

## Secure API Tokens with Strict TTL and Rotation Policies

All programmatic access uses **Bearer tokens** with configurable lifespans. As documented in [`README.md`](https://github.com/vxcontrol/pentagi/blob/main/README.md) (line 1198), tokens support a minimum TTL of 1 minute and maximum of 3 years. Choose the shortest lifespan practical for your workflow.

Rotate tokens regularly via the GraphQL API defined in `backend/pkg/graph/schema.graphqls` (lines 990-1005). Never commit tokens to repositories; inject them via environment variables or secret managers.

```bash

# Example API request with Bearer token

curl -X POST https://pentagi.example.com/api/v1/flows \
  -H "Authorization: Bearer $PENTAGI_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title":"Security Scan","input":"https://target.example.com"}'

```

```graphql

# Rotate a token via GraphQL

mutation RotateToken {
  rotateToken(id: "abcd1234") {
    token
    expiresAt
  }
}

```

## Configure Network Segmentation and Firewall Rules

Restrict network exposure to essential ports only. Block outbound traffic from workers to prevent data exfiltration while allowing necessary inbound connections.

- **Port 8443/tcp**: HTTPS UI/API access
- **Port 2376/tcp**: TLS-protected Docker-in-Docker (worker node only)

```bash

# UFW firewall configuration example

sudo ufw allow 8443/tcp
sudo ufw allow from 10.0.0.0/24 to any port 2376 proto tcp
sudo ufw deny out on eth0 to any port 22  # Prevent SSH from worker

```

## Prevent Secret Leakage in Source Control

The repository includes `.gitignore` rules to exclude `.env` files and private keys. The installer explicitly warns about secret handling in [`backend/cmd/installer/wizard/locale/locale.go`](https://github.com/vxcontrol/pentagi/blob/main/backend/cmd/installer/wizard/locale/locale.go) (line 1853).

Use a dedicated secret manager (HashiCorp Vault, AWS Secrets Manager, or Kubernetes Secrets) to inject values at container startup. When sharing configuration examples, always replace real values with placeholders like `YOUR_POSTGRES_PASSWORD`.

## Maintain Updated Dependencies and Images

PentAGI's container images receive frequent security updates. Pull the latest tags before each deployment and verify checksums.

```bash

# Update all services to latest security patches

docker pull vxcontrol/pentagi:latest
docker pull vxcontrol/pentagi-worker:latest
docker compose pull
docker compose up -d --force-recreate

```

## Summary

- **Run the installer** to automatically generate hardened secrets via [`backend/cmd/installer/hardening/hardening.go`](https://github.com/vxcontrol/pentagi/blob/main/backend/cmd/installer/hardening/hardening.go)
- **Keep TLS verification enabled** by ensuring `EXTERNAL_SSL_INSECURE=false` in [`backend/pkg/config/config.go`](https://github.com/vxcontrol/pentagi/blob/main/backend/pkg/config/config.go)
- **Deploy two-node architecture** with isolated workers running rootless Docker
- **Use short-lived API tokens** and rotate them via the GraphQL endpoint
- **Restrict firewall rules** to ports 8443 and 2376 only
- **Never commit secrets**; use external secret managers
- **Update images regularly** to incorporate security patches

## Frequently Asked Questions

### What is the most critical first step when deploying PentAGI securely?

Run the interactive installer immediately after cloning vxcontrol/pentagi. The hardening logic in [`backend/cmd/installer/hardening/hardening.go`](https://github.com/vxcontrol/pentagi/blob/main/backend/cmd/installer/hardening/hardening.go) (lines 44-48) automatically generates cryptographically-secure values for all credentials, eliminating default passwords that could be exploited.

### Can I disable TLS verification for testing with self-signed certificates?

While the `ExternalSSLInsecure` flag in [`backend/pkg/config/config.go`](https://github.com/vxcontrol/pentagi/blob/main/backend/pkg/config/config.go) (lines 92-94) allows setting `EXTERNAL_SSL_INSECURE=true`, **never enable this in production**. Doing so exposes your deployment to man-in-the-middle attacks. For internal CAs, mount the certificate bundle via `EXTERNAL_SSL_CA_PATH` instead.

### How does the two-node architecture improve security?

Separating the primary node (API/UI) from worker nodes creates network and filesystem isolation. The worker node, which executes arbitrary penetration testing tools in Docker containers, cannot access your internal services or database. Communication occurs over TLS-authenticated Docker-in-Docker protocols defined in [`examples/guides/worker_node.md`](https://github.com/vxcontrol/pentagi/blob/main/examples/guides/worker_node.md).

### What is the recommended lifecycle for API tokens?

Configure the shortest Time-To-Live (TTL) feasible for your automation—minimum 1 minute, maximum 3 years. Regularly rotate tokens using the GraphQL mutation in `backend/pkg/graph/schema.graphqls` (lines 990-1005) and never store tokens in version control or environment files committed to repositories.