/
·
Build LogSeptember 14, 2026·5 min read
How to Install VulnClaw | Agent for Pentesting
How to Install VulnClaw
VulnClaw is an AI-powered penetration testing CLI that combines an LLM agent with MCP-based tooling for authorized security testing.
⚠️ Security Notice: Use VulnClaw only against systems you own or have explicit permission to test.
Prerequisites
Before installing VulnClaw, make sure you have:
- Python 3.10 or newer
pip- An API key from a supported LLM provider
- Git, if installing from source
VulnClaw supports providers such as OpenAI, Anthropic, DeepSeek, MiniMax, Zhipu, Moonshot, Qwen, SiliconFlow, and Ollama.
1. Install VulnClaw
Option 1: Install from PyPI
The easiest way to install VulnClaw:
bash
pip install vulnclaw
Verify the installation:
bash
vulnclaw --help
If the help menu appears, VulnClaw is installed successfully.
Option 2: Install from GitHub
Clone the repository:
bash
git clone https://github.com/Netw0rkNoob/VulnClaw.git
cd VulnClaw
Install it in editable mode:
bash
pip install -e .
2. Configure Your LLM Provider
VulnClaw requires an LLM provider to power its AI agent.
For example, to use OpenAI:
bash
vulnclaw config provider openai
Then add your API key:
bash
vulnclaw config set llm.api_key sk-your-key-here
You can also use other providers:
bash
vulnclaw config provider anthropic
vulnclaw config provider deepseek
vulnclaw config provider minimax
vulnclaw config provider qwen
vulnclaw config provider moonshot
3. Configure a Custom Model
If you want to use a custom API endpoint:
bash
vulnclaw config set llm.base_url https://your-api.example.com/v1
Set the model:
bash
vulnclaw config set llm.model your-model-name
Make sure your API key, base URL, and model belong to the same provider.
4. Configure Using .env
For Docker or environment-variable based configuration, copy the example file:
bash
cp .env.example .env
Then configure your provider:
dotenv
VULNCLAW_LLM_API_KEY=sk-your-key-here
VULNCLAW_LLM_PROVIDER=openai
VULNCLAW_LLM_BASE_URL=https://api.openai.com/v1
VULNCLAW_LLM_MODEL=gpt-4o
Important: When using environment variables,
VULNCLAW_LLM_PROVIDERis only a provider label. You must explicitly configure the correctBASE_URLandMODEL.
5. Using Ollama
VulnClaw can also use local models through Ollama.
Example:
dotenv
VULNCLAW_LLM_API_KEY=ollama
VULNCLAW_LLM_PROVIDER=ollama
VULNCLAW_LLM_BASE_URL=http://localhost:11434/v1
VULNCLAW_LLM_MODEL=llama3.1
Make sure your Ollama model supports tool/function calling, because VulnClaw relies on tool calls.
6. Check Your Installation
Run the built-in environment checker:
bash
vulnclaw doctor
It checks:
- Python
- Node.js
npxnmap- LLM configuration
- MCP services
A successful setup should show:
text
🦞 VulnClaw Environment Check
✅ Ready. Run vulnclaw to start.
7. Start VulnClaw
Start the interactive CLI:
bash
vulnclaw
You can also launch the terminal UI:
bash
vulnclaw tui
8. Launch the Web UI
VulnClaw includes a local Web UI.
Start it with:
bash
vulnclaw web
By default, it runs at:
text
http://127.0.0.1:7788
Open that address in your browser.
9. Run Your First Authorized Test
Run a full pentest workflow:
bash
vulnclaw run <target>
For example:
bash
vulnclaw run https://your-authorized-lab.example.com
You can also use the goal-driven solver:
bash
vulnclaw solve <target> --goal "identify vulnerabilities in the authorized lab"
For reconnaissance only:
bash
vulnclaw recon <target>
For vulnerability scanning:
bash
vulnclaw scan <target>
⚠️ Only run these commands against systems you own or have explicit authorization to test.
Docker Installation
If you don't want to install everything directly on your machine, you can run VulnClaw using Docker.
1. Clone the Repository
bash
git clone https://github.com/Netw0rkNoob/VulnClaw.git
cd VulnClaw
2. Create the Environment File
bash
cp .env.example .env
Add your LLM credentials to .env.
3. Build and Start
bash
docker compose up --build
The Web UI will be available at:
text
http://127.0.0.1:7788
One-Off Docker Command
bash
docker run --rm -it \
-e VULNCLAW_LLM_API_KEY=sk-your-key-here \
-v vulnclaw-data:/data \
vulnclaw:latest scan <target>
Docker networking:
localhostinside a container refers to the container itself. If your target is running on the host machine, usehost.docker.internal.
Optional Features
VulnClaw provides optional dependency groups.
Web UI
bash
pip install "vulnclaw[web]"
Knowledge Base
bash
pip install "vulnclaw[kb]"
PDF Reports
bash
pip install "vulnclaw[pdf]"
Traffic Tooling
bash
pip install "vulnclaw[traffic]"
Install multiple extras together:
bash
pip install "vulnclaw[web,kb,pdf,traffic]"
Troubleshooting
vulnclaw: command not found
Check whether VulnClaw is installed:
bash
python -m pip show vulnclaw
If you're using a virtual environment, activate it:
bash
source .venv/bin/activate
Then install again:
bash
pip install vulnclaw
invalid api key
Check these settings:
text
VULNCLAW_LLM_API_KEY
VULNCLAW_LLM_PROVIDER
VULNCLAW_LLM_BASE_URL
VULNCLAW_LLM_MODEL
A common mistake is using an API key from one provider while pointing BASE_URL to another provider.
MCP or Runtime Problems
Run:
bash
vulnclaw doctor
The diagnostic output will show missing runtimes or services.
Installation Complete
Once:
bash
vulnclaw doctor
shows:
text
✅ Ready. Run vulnclaw to start.
you're ready to launch VulnClaw:
bash
vulnclaw
For the complete documentation, architecture, advanced configuration, skills, and MCP setup, visit the VulnClaw GitHub repository.
Written by Akshat Singh
35K+ followers
Hey, I'm Akshat — a full-stack dev, AI tinkerer, and relentless builder who documents every step of the journey. I share what I learn in real-time — dev tutorials, design insights, and AI + tech news.
Comments