Home

Pentest Copilot

Pentest Copilot is an open-source, AI-driven penetration testing agent. It runs security tools on a workspace-specific local or SSH work host, analyzes the results, and iterates from a browser interface.

Prerequisites

Requirement	Minimum
Docker Engine	v20+ with Docker Compose v2
RAM	8 GB, plus 2 GB for the built-in Kali container
Disk	20 GB free
Node.js	v22+ for developer mode only
pnpm	v9+ for developer mode only

Windows users must run Pentest Copilot inside WSL2 with Docker Desktop's WSL integration enabled. Clone into the Linux filesystem under ~/, not /mnt/c.

Quick start

git clone https://github.com/bugbasesecurity/pentest-copilot.git
cd pentest-copilot
./run.sh start

Open http://127.0.0.1:3000 and create the installation-owner account. Only the first account can register. Then:

1. Open Settings → Models, add an orchestrator, and use Test & Save.
2. Create or open a workspace.
3. Open its Connection page and save a local folder or tested SSH alias.

The launcher creates configuration, runs preflight checks, builds the selected services, applies database migrations, and waits for readiness. See Setup and Troubleshooting for the complete environment and failure matrix.

Setup modes

Mode	What it runs	When to use
Core Docker	MongoDB, Redis, backend, frontend	Use a local folder or external SSH work host
Docker + Kali	Core services plus the built-in Kali desktop	Use the self-contained attack box
Developer	MongoDB and Redis, optionally Kali	Run the backend and frontend directly on the host

Launcher commands

Command	Description
./run.sh start	Guided start with preflight checks
./run.sh start -q	Reuse the existing configuration without prompts
./run.sh config	Update launcher-managed configuration
./run.sh dev	Start developer-mode infrastructure
./run.sh stop	Stop the selected stack
./run.sh logs [service]	Follow logs, optionally for one service
./run.sh status	Show container status
./run.sh backup	Back up databases, configuration, and workspace data
./run.sh help	Show full help

Configuration layers

The launcher owns four configuration layers:

File	Purpose
config.toml	Server, database, session, and tracing settings; restart required
backend/.env	Dynamic scalar settings and integration defaults
backend/model-registry.json	Model presets and assignments; normally edited through Settings
frontend/.env	Public frontend build settings; rebuild required

Model credentials are configured through Settings → Models. Work hosts are selected per workspace through Connection. Existing environment-based model and SSH settings are migrated or used as launcher defaults; they are not the recommended configuration workflow.

Docker mode binds published ports to 127.0.0.1. Do not expose the stack to a LAN or the internet without TLS, authentication, and a deliberate reverse proxy. The repository includes deploy/Caddyfile.example as a starting point.

Updating safely

./run.sh backup
git pull --ff-only
./run.sh start

Choose the rebuild option after pulling. Do not use docker compose down -v during a normal update because it deletes persistent volumes.

What's next

• Setup and Troubleshooting — installation, recovery, and deployment
• Architecture — system components and data flow
• Usage — day-to-day workflow
• Settings — models, work hosts, integrations, and agent behavior