Setup and Troubleshooting

Setup and Troubleshooting

Pentest Copilot supports macOS, Linux, and Windows through WSL2. The default Docker deployment is local-only: application and infrastructure ports bind to 127.0.0.1.

Setup matrix

Priority	Environment or failure	What Pentest Copilot does	What you should do
P0	Native Windows PowerShell, CMD, or Git Bash	The launcher stops before creating partial configuration.	Install WSL2, enable Docker Desktop's WSL integration, and clone inside the WSL filesystem.
P0	Remote Docker context	The launcher rejects ssh:// and tcp:// Docker endpoints because bind mounts would point at the remote machine.	Switch to a local context or run the repository on the Docker host.
P0	Public or LAN exposure	Compose binds every published port to loopback. Production mode refuses non-HTTPS frontend and CORS settings.	Keep the workstation default or follow the reverse-proxy procedure below.
P0	Open registration	Only the first account can register; the UI and API close registration afterward.	Create the installation-owner account once and retain its credentials.
P0	Invalid model key, model name, URL, or subscription login	Test & Save performs real inference. Unverified models cannot satisfy onboarding.	Correct the model test error. For a Docker-hosted local API, use host.docker.internal, not localhost.
P0	Upgrade from the session-only data model	Idempotent MongoDB migrations run automatically before readiness succeeds.	Let startup finish; inspect ./run.sh logs backend if readiness fails.
P0	Lost databases, configuration, or workspace data	./run.sh backup exports databases and archives configuration and durable workspace data with owner-only permissions.	Back up before upgrades and never use docker compose down -v unintentionally.
P0	Untrusted SSH server	External SSH profiles require a matching known_hosts entry, including nonstandard ports.	Connect once with ssh alias, verify the fingerprint, and retry.
P0	VPN uses separate certificates, keys, PKCS#12, or credentials	The uploader accepts one .ovpn/.conf plus referenced assets and transfers them together.	Select every bundle file. Interactive auth-user-pass prompts are rejected; include a credentials file or connect manually.
P0	Stale VPN PID or unrelated OpenVPN process	Status and disconnect only act on PID files and command lines owned by Pentest Copilot.	Manage unrelated VPN processes outside Pentest Copilot.
P0	Browser target is only reachable through an SSH host's VPN	The browser agent warns that it runs beside the backend, not on the SSH work host.	Connect the VPN beside the backend or expose a reachable HTTP/SOCKS proxy.
P0	Backend compromise reaches Docker	The backend does not mount the Docker socket or control work hosts through Docker APIs.	No action required.
P1	Docker missing, stopped, old, or Compose v1	The launcher checks Engine 20+, Compose v2, and daemon connectivity.	Install or update Docker Desktop, or Docker Engine plus the Compose plugin.
P1	Port collision	The launcher reports occupied TCP ports and the owning listener where possible.	Stop the listener and retry. Standard ports are 3000, 8080, 6080, 9020, 27017, and 6379; Kali adds 4200, 4242, and 5901.
P1	Low disk or memory	The launcher warns below 20 GB free disk or 8 GB RAM.	Free disk, increase Docker resources, reduce concurrency, or avoid built-in Kali.
P1	ARM64 host	The launcher warns because some third-party Kali tools are x86_64-only.	Prefer core mode with an ARM64 work host or use an x86_64 attack box.
P1	Rootless Docker	The launcher warns and blocks built-in Kali, which needs privileged networking.	Use core mode with an external SSH work host or non-rootless Docker.
P1	Repository or work-folder permission error	The launcher checks repository writability; workspace selection performs a real create/write/delete probe.	Fix ownership and Docker Desktop file sharing, then retry.
P1	SSH config uses Include	Concrete aliases in common include files and config.d/* globs are discovered.	Select a concrete alias; wildcard-only entries are intentionally hidden.
P1	Key outside .ssh, encrypted key, or SSH agent	~/.ssh, ~/keys, ssh-keys/, and a live SSH_AUTH_SOCK are supported.	Set the host directory variables, copy a key to ssh-keys/, or run ssh-add.
P1	ProxyJump or ProxyCommand profile	The connection test reports that the embedded SSH client cannot use it.	Create a local tunnel or direct alias reachable by the backend.
P1	Non-Debian Linux work host	Automatic APT capability installs stop with a specific distro message; supported macOS installs use Homebrew.	Install with the host package manager and run detection again.
P1	Slow package install	Capability installation allows up to ten minutes.	Watch terminal output and preinstall unusually large GUI tools when needed.
P1	Corporate proxy or custom CA	Docker build proxy variables are detected and a valid NODE_EXTRA_CA_CERTS file is mounted automatically.	Export proxy/CA variables and configure Docker Desktop trust for pulls and builds.
P1	Developer mode	The launcher checks pnpm, installs locked dependencies, starts infrastructure, and prints the local commands.	Use Node 22+ and pnpm 9+; install Patchright Chromium when prompted.
P2	SELinux enforcing	Docker may reject bind mounts despite correct Unix ownership.	Label only the required bind paths according to distribution policy; do not disable SELinux globally.
P2	Air-gapped or intermittent network	Existing images continue to work; first builds, browser downloads, package installs, and hosted model tests require upstream access.	Pre-pull images and preinstall tools while online, then use a reachable local model.
P2	Multiple clones	The launcher rejects a Compose project owned by another working directory; fixed ports are also checked.	Run one clone or deliberately assign unique projects, ports, and URLs.
P2	Workspace path contains spaces	Local and SSH work folders are quoted and tested before saving.	Use an absolute path; ~ is accepted over SSH. Control characters are rejected.
P2	IPv6-only target or unusual DNS	Commands use the selected work host's network and resolver.	Verify routing and resolution in the workspace terminal and use IPv6-capable tool flags.

Normal installation

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

Open http://localhost:3000, create the owner account, verify an orchestrator under Settings → Models, and save a work host on the workspace's Connection page. Subsequent starts can use ./run.sh start -q.

Windows with WSL2

1. Install WSL2 and a Linux distribution.
2. Enable that distribution in Docker Desktop's WSL Integration settings.
3. Clone under ~/, not /mnt/c.
4. Run ./run.sh start in WSL and open the printed localhost URL in Windows.

If Docker is unavailable in WSL, repair Docker Desktop integration instead of installing a second Docker daemon inside the distribution.

SSH checklist

ssh-add -l
ssh-keygen -F lab-box
ssh -v lab-box

The backend discovers concrete OpenSSH aliases with ssh -G. In Docker, localhost means the backend container. Use host.docker.internal for a host service and the generated kali profile for the built-in Kali container.

Backups and recovery

Run ./run.sh backup. The timestamped folder under backups/ contains MongoDB and Redis exports, configuration, and durable work data. It contains credentials: store it encrypted and never commit or share it.

Restore is intentionally manual because it replaces live data. Stop the stack, review the archive, restore with the native MongoDB, Redis, and tar tools, and keep the original backup until the restored stack passes health checks.

Reverse proxy and TLS

The supported default is workstation-local. For remote access:

1. Keep Compose ports on 127.0.0.1.
2. Put an authenticated TLS reverse proxy on the same host; start from deploy/Caddyfile.example.
3. Set production mode, the frontend URL, and CORS origins to the same HTTPS origin in config.toml.
4. Set the matching NEXT_PUBLIC_* values in frontend/.env and rebuild.
5. Verify login, API requests, shell WebSockets, and closed registration from a private browser window.

Do not proxy MongoDB, Redis, Kali SSH/shell, or an unauthenticated noVNC port. Production startup also rejects a session secret shorter than 32 characters.