Bftcpa606: Created page with " = 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 u..."

2026-07-13T20:47:12Z

Created page with " = 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 u..."

New page

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

<nowiki>#</nowiki> Update the system

apt update && apt upgrade -y

<nowiki>#</nowiki> Tools we'll need

apt install -y ca-certificates curl gnupg git make

<nowiki>#</nowiki> Add Docker's official GPG key + repository

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

curl -fsSL <nowiki>https://download.docker.com/linux/ubuntu/gpg</nowiki> -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] \

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

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

<nowiki>#</nowiki> Install Docker Engine + Compose plugin

apt update

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

<nowiki>#</nowiki> 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

<nowiki>#</nowiki> Clone with the benchmark suite included

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

cd PentestGPT

<nowiki>#</nowiki> 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

<nowiki>#</nowiki> Basic run against a target IP

pentestgpt --target 10.10.11.234

<nowiki>#</nowiki> Give it context to focus its approach

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

<nowiki>#</nowiki> 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:
{| class="wikitable"
| valign="top" |Command
| valign="top" |What it does
|-
| valign="top" |make connect
| valign="top" |Start + attach to the PentestGPT shell (your main entry point).
|-
| valign="top" |make stop
| valign="top" |Stop the container; all config/logins are kept.
|-
| valign="top" |make config
| valign="top" |Re-run provider setup (e.g. to switch keys).
|-
| valign="top" |make clean-docker
| valign="top" |Remove the container and image.
|-
| valign="top" |make docker-nuke
| valign="top" |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

<nowiki>#</nowiki> per run

pentestgpt --target 10.10.11.234 --no-telemetry

<nowiki>#</nowiki> 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.

Pentestgpt - Revision history