How to Install VulnClaw: AI-Powered Penetration Testing Agent
Set up an open-source AI pentesting agent combining LLMs, MCP tools, and security tooling.
What is VulnClaw?
AI-Powered Penetration Testing Agent
VulnClaw is an open-source AI-powered penetration testing agent that combines Large Language Models, MCP tools, and security tooling to automate parts of the security testing workflow.
It can work with providers such as OpenAI, Anthropic, DeepSeek, MiniMax, Ollama, and other compatible APIs. It provides a command-line interface, terminal UI, and browser-based Web UI.
Important: Use VulnClaw only on systems you own or have explicit permission to test.
Prerequisites
Before installing VulnClaw, make sure your machine has:
- Python 3.10 or newer
- Git
- pip
- A supported LLM API key, or a local model such as Ollama
- Node.js / npx and tools such as Nmap are recommended for additional functionality
VulnClaw officially requires Python 3.10 or newer. Check your Python installation:
python3 --versionCheck Git:
git --versionMethod 1: Install VulnClaw from GitHub
This method is recommended if you want the latest source code or plan to modify VulnClaw.
1. Clone the Repository
git clone https://github.com/Netw0rkNoob/VulnClaw.gitMove inside the project directory:
cd VulnClawThe official repository also supports installing directly through PyPI, but source installation is useful for developers who want access to the full project.
2. Create a Python Virtual Environment
Using a virtual environment keeps VulnClaw and its dependencies isolated from the rest of your system.
### macOS / Linux
python3 -m venv .venv
source .venv/bin/activate### Windows PowerShell
python -m venv .venv
.\.venv\Scripts\Activate.ps1After activation, your terminal should normally show something similar to:
(.venv)3. Upgrade pip
python -m pip install --upgrade pip4. Install VulnClaw
For the standard CLI installation:
pip install -e .If you also want the browser Web UI:
pip install -e ".[web]"The Web UI extra installs FastAPI and Uvicorn dependencies required by the browser interface.
5. Verify the Installation
Run:
vulnclaw --helpThen run the built-in environment checker:
vulnclaw doctorThe doctor command checks components such as Python, Node.js, npx, Nmap, LLM configuration, and MCP services.
Method 2: Quick Installation Using pip
If you simply want to use VulnClaw without modifying its source code, install it directly from PyPI:
pip install vulnclawFor Web UI support:
pip install "vulnclaw[web]"Verify the installation:
vulnclaw doctorThe VulnClaw maintainers currently list PyPI installation as the recommended quick-start method.
Configure an AI Provider
VulnClaw requires an LLM to power its AI agent. You can configure providers using the VulnClaw CLI.
## OpenAI
vulnclaw config provider openaiAdd your API key:
vulnclaw config set llm.api_key YOUR_OPENAI_API_KEY## Anthropic Claude
vulnclaw config provider anthropicThen configure your Anthropic API key:
vulnclaw config set llm.api_key YOUR_ANTHROPIC_API_KEY## DeepSeek
vulnclaw config provider deepseekThen:
vulnclaw config set llm.api_key YOUR_DEEPSEEK_API_KEY## Ollama If you prefer running a local model:
vulnclaw config provider ollamaYou can customize the model if required:
vulnclaw config set llm.model YOUR_MODEL_NAMEThe provider command can automatically populate the appropriate base URL and default model configuration for supported providers. After configuring your provider, verify everything:
vulnclaw doctorStart VulnClaw
## Standard CLI Run:
vulnclawThis opens the interactive VulnClaw shell. ## Terminal UI For the terminal workbench:
vulnclaw tui## Web UI Start the browser interface:
vulnclaw webBy default, the Web UI runs locally at: ```text http://127.0.0.1:7788 ``` VulnClaw binds the Web UI to localhost by default. To use another port:
vulnclaw web --port 8080Install VulnClaw with Docker
VulnClaw also provides an official Docker setup. Clone the repository:
git clone https://github.com/Netw0rkNoob/VulnClaw.git
cd VulnClawCreate the environment file:
cp .env.example .envOpen `.env` and configure your LLM credentials. Then start VulnClaw:
docker compose up --buildOpen: ```text http://127.0.0.1:7788 ``` The Docker image includes the Web UI and runtimes such as `npx` and `uvx`, while persistent configuration, sessions, targets, and reports can be stored in a Docker volume.
Install VulnClaw Automatically Using Claude Code or Codex
Instead of manually running every installation command, you can ask an AI coding agent such as Claude Code or OpenAI Codex to inspect the repository and perform the installation. Open Claude Code or Codex inside the directory where you want to install VulnClaw and paste the following prompt.
Install and fully configure https://github.com/Netw0rkNoob/VulnClaw.git on this computer. Detect my operating system and architecture first, inspect the latest README_EN.md, pyproject.toml, .env.example and DOCKER.md before making changes, verify or install the required dependencies including Git, Python 3.10+, pip and venv, then clone the repository, create an isolated Python virtual environment, install VulnClaw from source with Web UI support using pip install -e ".[web]", fix reasonable dependency or PATH errors automatically, run vulnclaw --help and vulnclaw doctor, configure an appropriate LLM provider using existing environment credentials if available but never display, hard-code or commit secrets, and if an API key is missing tell me exactly what credential I need to provide manually. Finally verify that vulnclaw web starts successfully on 127.0.0.1:7788 and give me a short summary containing the installation directory, Python environment, provider status, doctor results, Web UI URL, startup command, shutdown command and any remaining manual steps. Only configure the tool for systems, labs or targets that I own or am explicitly authorized to security test.This approach is useful because Claude Code or Codex can first inspect the current repository instructions instead of relying on an outdated installation guide.
Common Installation Problems
## `vulnclaw: command not found` Make sure your virtual environment is activated. macOS/Linux:
source .venv/bin/activateWindows:
.\.venv\Scripts\Activate.ps1Then test:
vulnclaw --help## Python Version Error Check your Python version:
python3 --versionVulnClaw requires: ```text Python >= 3.10 ``` ## Web UI Dependencies Missing Install the Web UI dependencies:
pip install "vulnclaw[web]"Or when installing from the cloned repository:
pip install -e ".[web]"## Check Your Environment The easiest troubleshooting command is:
vulnclaw doctorIt will identify many common configuration and dependency problems.
Final Setup
Once everything is configured, your typical workflow is simply:
cd VulnClaw
source .venv/bin/activate
vulnclaw doctor
vulnclaw webThen visit: ```text http://127.0.0.1:7788 ``` You now have VulnClaw running locally with an AI provider and optional browser interface.
Security Notice VulnClaw is a cybersecurity and penetration-testing tool. Only use it against applications, servers, networks, CTF environments, security labs, or infrastructure where you have explicit authorization. Never test third-party infrastructure without permission.