Pentestgpt

Setting Up PentestGPT in a Container on Proxmox — Beginner's Guide

Based on PentestGPT v1.0 (the December 2025 "agentic" release). Verified July 2026.

What you're actually building

PentestGPT changed a lot in v1.0. The old versions were a Python package you installed with pip. The current version ships as a Docker image that already contains Python 3.12, the pentest tools (nmap, netcat, whois, dnsutils, openvpn, etc.), and the Claude Code CLI it uses for reasoning.

So on Proxmox you'll do three things:

1.         Create a host on Proxmox (an LXC container or a VM) — this is your "container on Proxmox."

2.         Install Docker inside that host.

3.         Let PentestGPT's make commands build and run its own Docker container inside the host.

Yes — that's a container running a container. That's normal and expected here. The Proxmox LXC is the outer shell; PentestGPT lives in a Docker container inside it.

Before you start

You'll need:

•            A Proxmox VE host (version 8.x assumed) that you can reach via the web UI and open a shell on.

•            An LLM provider credential. The autonomous agent uses Claude. You have four options, pick one:

–           Anthropic API key — from console.anthropic.com. Pay-as-you-go. Simplest for a server. (Recommended for a headless box.)

–           Claude subscription (OAuth login) — requires a paid Claude Pro/Max subscription; you log in interactively.

–           OpenRouter API key — from openrouter.ai, gives access to many models.

–           Local LLM — point it at your own Ollama / LM Studio server (advanced).

•            About 30–45 minutes, most of which is the image build downloading.

A note on cost: because it calls a paid API, real runs cost money. The project's own published benchmarks average roughly $1.11 per successful task (median ~$0.42). Keep an eye on your API spend.

A note on scope: PentestGPT is a real offensive-security tool. Only point it at systems you own or have explicit written authorization to test — your own lab VMs, Hack The Box / TryHackMe targets, etc. The project ships with the same disclaimer.

Decision: LXC container or VM?

Since you asked for a container on Proxmox, this guide leads with an LXC container. It's lighter and boots instantly.

One honest caveat: PentestGPT's Docker setup asks for the NET_ADMIN capability and a TUN device so it can dial VPNs (for Hack The Box / TryHackMe). Getting those working inside an LXC takes a couple of extra tweaks (privileged container + nesting + TUN passthrough), which this guide covers. If you don't need built-in VPN, you can skip the TUN step entirely.

If you'd rather avoid the LXC tweaks altogether, a small VM is the more bulletproof host — the TUN device and NET_ADMIN "just work" with no special config. There's a short VM section at the end; everything from Part 2 onward is identical.

Part 1 — Create the LXC container

1.1 Get a template (if you don't have one)

In the Proxmox web UI: click your storage (e.g. local) → CT Templates → Templates, and download Ubuntu 24.04 (recommended — it matches PentestGPT's base image) or Debian 13.

Or from the Proxmox host shell:

bash

pveam update

pveam available | grep -Ei 'ubuntu-24.04|debian-13'

pveam download local ubuntu-24.04-standard_24.04-2_amd64.tar.zst

(The exact filename will vary — copy whatever the available command lists.)

1.2 Create the container

Click Create CT (top-right of the Proxmox UI) and set:

Setting	Value	Why
Unprivileged container	Unchecked (i.e. privileged)	Makes Docker-in-LXC far less painful for a beginner.
Hostname	pentestgpt	Anything you like.
Password / SSH key	your choice	You'll log in with this.
Template	the one from 1.1	—
Disk	32 GB	The image + tools need room.
CPU cores	2–4	More = faster reasoning.
Memory	4096 MB min, 8192 MB better	Compose defaults to an 8 GB limit.
Network	DHCP or a static IP on your LAN	Needs internet for the build + API.

Click through and Finish, but don't start it yet.

Why privileged? A privileged LXC is less isolated from the Proxmox host than an unprivileged one. For a homelab tool on a network you control, that's an acceptable trade for a smooth Docker experience. If you're security-conscious about the host itself, use the VM option instead.

1.3 Enable nesting (required for Docker)

Select the new container in the UI → Options → Features → Edit → tick Nesting (and keyctl if shown) → OK.

1.4 (Optional) Pass through the TUN device — only if you want built-in VPN

Skip this if you won't use Hack The Box / TryHackMe VPN from inside the tool.

On the Proxmox host shell, edit the container's config (replace 100 with your CT's ID):

bash

nano /etc/pve/lxc/100.conf

Add these two lines at the bottom:

lxc.cgroup2.devices.allow: c 10:200 rwm

lxc.mount.entry: /dev/net/tun dev/net/tun none bind,create=file

Save and exit.

1.5 Start it and log in

Start the container (Start button), then open Console, and log in as root with the password you set.

Part 2 — Install Docker inside the container

Run these inside the LXC console (this is for Ubuntu/Debian):

bash

# Update the system

apt update && apt upgrade -y

# Tools we'll need

apt install -y ca-certificates curl gnupg git make

# Add Docker's official GPG key + repository

install -m 0755 -d /etc/apt/keyrings

curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc

chmod a+r /etc/apt/keyrings/docker.asc

echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] \

https://download.docker.com/linux/ubuntu $(. /etc/os-release && echo $VERSION_CODENAME) stable" \

  | tee /etc/apt/sources.list.d/docker.list > /dev/null

# Install Docker Engine + Compose plugin

apt update

apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

# Confirm it works

docker run --rm hello-world

On Debian instead of Ubuntu, change the two ubuntu words in the repo URL to debian.

If hello-world prints a friendly message, Docker is working. If you get a permission or cgroup error, double-check that Nesting is enabled (Part 1.3) and reboot the container (reboot).

Part 3 — Install PentestGPT

Still inside the LXC:

bash

# Clone with the benchmark suite included

git clone --recurse-submodules https://github.com/GreyDGL/PentestGPT.git

cd PentestGPT

# Build the Docker image (this is the slow step — grab a coffee)

make install

make install builds the pentestgpt:latest image from the included Dockerfile. First run pulls Ubuntu 24.04 and installs all the pentest tools, so it can take several minutes.

If you forgot --recurse-submodules: run git submodule update --init --recursive from inside the PentestGPT folder.

Part 4 — Configure your LLM provider

bash

make config

This launches an interactive menu. Choose the option matching what you set up in "Before you start":

•            Anthropic API → paste your sk-ant-... key. (Easiest for a server.)

•            Claude login (OAuth) → for subscription users; you'll finish the login in Part 5.

•            OpenRouter → paste your OpenRouter key.

•            Local LLM → point it at your Ollama/LM Studio server (see Troubleshooting for the host.docker.internal note).

Your credentials are stored in a persistent Docker volume, so you only do this once — they survive restarts.

Part 5 — Connect and run your first test

bash

make connect

This starts the PentestGPT container (if it isn't already running) and drops you into a shell inside it, in the /workspace directory.

If you chose the Claude OAuth option, log in once now:

bash

claude login

(Follow the URL/code prompt. This also persists across restarts.)

Now run the agent against a target:

bash

# Basic run against a target IP

pentestgpt --target 10.10.11.234

# Give it context to focus its approach

pentestgpt --target 10.10.11.50 --instruction "WordPress site, focus on plugin vulnerabilities"

# Cap how long it runs

pentestgpt --target 10.10.11.234 --max-iterations 5

This opens an interactive text UI where you watch the agent work through reconnaissance → vulnerability analysis → exploitation. Useful keys: F1 = help, Ctrl+P = pause/resume, Ctrl+Q = quit.

When you're done, exit the shell and stop the container:

bash

make stop

Your image, config, and login all persist — next time it's just make connect.

Managing the container day-to-day

Run these from the ~/PentestGPT folder inside your LXC:

Command	What it does
make connect	Start + attach to the PentestGPT shell (your main entry point).
make stop	Stop the container; all config/logins are kept.
make config	Re-run provider setup (e.g. to switch keys).
make clean-docker	Remove the container and image.
make docker-nuke	Remove everything including saved logins (forces a fresh login next time).

Monitor resource use anytime with:

bash

docker stats pentestgpt

Optional: the multi-provider interactive mode

Inside the container, there's also a classic human-in-the-loop mode called pentestgpt-legacy. Unlike the autonomous agent (Claude-only), it talks to many providers — OpenAI, Anthropic, Gemini, DeepSeek, Grok, Qwen, Moonshot, and local Ollama — and you steer it with commands like next, more, todo, and discuss. Set the relevant API key(s) in a .env file first (copy .env.example), then:

bash

pentestgpt-legacy --list-models     # see what's available/configured

pentestgpt-legacy                   # auto-pick best available models

Turning off telemetry (optional)

PentestGPT sends anonymous usage metadata (session type, duration, which tools ran — not commands, credentials, or flag contents) to the project's analytics. To disable it:

bash

# per run

pentestgpt --target 10.10.11.234 --no-telemetry

# or globally, inside the container

export LANGFUSE_ENABLED=false

If you'd rather use a VM instead of an LXC

A VM is the more foolproof host, especially if you want the VPN features. The only differences:

•            In Proxmox, choose Create VM and install Ubuntu 24.04 Server (give it ~2–4 vCPU, 4–8 GB RAM, 32 GB disk).

•            Skip Part 1.2's privileged setting, 1.3 nesting, and 1.4 TUN passthrough entirely — none of that is needed. /dev/net/tun and NET_ADMIN work natively.

•            Everything from Part 2 (Install Docker) onward is exactly the same.

Troubleshooting

docker: permission denied (as a non-root user): add your user to the docker group, then re-log: usermod -aG docker $USER and newgrp docker. (If you're running everything as root in the LXC, you won't hit this.)

make: command not found: you missed it in Part 2 — apt install -y make.

Docker won't start / cgroup errors in the LXC: confirm Nesting is enabled (Part 1.3), then reboot the container. If it persists, the privileged setting (Part 1.2) is the usual fix.

"Permission denied" writing to /workspace: the repo ships a helper — from the PentestGPT folder on the host, run ./fix-workspace-permissions.sh.

Local LLM can't connect (connection refused): from inside the Docker container, your host machine is reachable as host.docker.internal, not localhost. Point the model URL there (the compose file already maps it).

Image build fails downloading packages: check the container has working internet/DNS (ping github.com), and that your Proxmox network bridge is reachable.