# How to Run VulnClaw from Source: Complete Installation and Setup Guide

> Learn to run VulnClaw from source. Follow our guide to clone the repo, install the package, configure credentials, and use the CLI for powerful vulnerability analysis.

- Repository: [Unclecheng/VulnClaw](https://github.com/Unclecheng-li/VulnClaw)
- Tags: how-to-guide
- Published: 2026-07-03

---

**To run VulnClaw from source, clone the repository, install the package in editable mode with `pip install -e .`, configure your LLM provider credentials, and invoke the `vulnclaw` CLI commands.**

VulnClaw is a pure‑Python penetration‑testing framework built around an LLM‑driven agent, a modular **MCP** (Model Context Protocol) toolchain, and a blackboard‑style solver. Running it directly from the Unclecheng-li/VulnClaw repository allows you to leverage the latest commits, customize the plugin subsystem, and debug the orchestration layer. This guide walks through the installation flow, runtime initialization, and command execution based on the actual source code architecture.

## Prerequisites and System Requirements

Before installing from source, ensure your environment meets the following baseline:

- **Python ≥3.10** (required for modern async/await patterns used in the agent core)
- **Node.js ≥20** (optional but recommended for Chrome DevTools MCP integration)
- **Git** (for cloning the repository)
- **pip** (for editable installation)

The `vulnclaw doctor` command (available after installation) validates these dependencies and reports any missing binaries.

## Cloning and Installing from Source

VulnClaw uses a standard Python package layout with [`pyproject.toml`](https://github.com/Unclecheng-li/VulnClaw/blob/main/pyproject.toml) as the build configuration. Installing in editable mode (`-e`) creates a `vulnclaw` console script that maps to the Typer entry point in [`vulnclaw/cli/main.py`](https://github.com/Unclecheng-li/VulnClaw/blob/main/vulnclaw/cli/main.py).

Execute the following steps:

```bash

# Clone the repository

git clone https://github.com/Unclecheng-li/VulnClaw.git
cd VulnClaw

# Install in editable mode

pip install -e .

```

Upon completion, the `vulnclaw` command becomes available in your shell. The installation exposes several CLI modules located under `vulnclaw/cli/*`, including the main entry point and specialized commands for reconnaissance and reporting.

## Configuring the LLM Provider

VulnClaw requires LLM credentials to power its reasoning engine. The configuration module ([`vulnclaw/config/settings.py`](https://github.com/Unclecheng-li/VulnClaw/blob/main/vulnclaw/config/settings.py)) reads from `~/.vulnclaw/config.yaml` and merges environment variables such as `VULNCLAW_LLM_API_KEY`.

Initialize your configuration:

```bash

# Check environment health

vulnclaw doctor

# Set provider (e.g., OpenAI)

vulnclaw config provider openai

# Set API key

vulnclaw config set llm.api_key sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxx

```

Alternatively, export the key directly:

```bash
export VULNCLAW_LLM_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxx

```

The configuration schema is defined in [`vulnclaw/config/schema.py`](https://github.com/Unclecheng-li/VulnClaw/blob/main/vulnclaw/config/schema.py) using Pydantic models, ensuring type safety for all settings.

## Understanding the Runtime Architecture

When you invoke a `vulnclaw` command, the system initializes a complex orchestration pipeline. Understanding these components helps troubleshoot execution flows and extend functionality.

### CLI Entry Points and Command Structure

The `vulnclaw` executable launches from [`vulnclaw/cli/main.py`](https://github.com/Unclecheng-li/VulnClaw/blob/main/vulnclaw/cli/main.py), which registers Typer commands for different operational modes. Key commands include:

- `vulnclaw run` – Full penetration test with the default solver engine
- `vulnclaw recon` – Reconnaissance phase only
- `vulnclaw web` – Launch the optional web UI (requires `pip install "vulnclaw[web]"`)

Commands that require agent execution delegate to [`vulnclaw/orchestrator.py`](https://github.com/Unclecheng-li/VulnClaw/blob/main/vulnclaw/orchestrator.py), specifically the `run_agent_task` helper function.

### Agent Core and Solver Engine

The agent logic resides in [`vulnclaw/agent/core.py`](https://github.com/Unclecheng-li/VulnClaw/blob/main/vulnclaw/agent/core.py), which coordinates LLM calls, tool routing, and blackboard updates. When using the default solve engine (`session.engine=solve`), the system invokes the OODA loop implementation in [`vulnclaw/agent/solver.py`](https://github.com/Unclecheng-li/VulnClaw/blob/main/vulnclaw/agent/solver.py).

This solver drives the blackboard graph (composed of `Fact` and `Intent` nodes) through repeated cycles:

1. **Reason** – Generate prompts based on current state
2. **Explore** – Execute tools and analyze responses
3. **Conclude** – Update the goal status or terminate when the frontier is exhausted

The loop terminates when the penetration goal is achieved, the safety budget is consumed, or no further exploration paths exist.

### MCP Router and Tool Execution

When the agent requires external data (e.g., fetching a webpage or querying memory), [`vulnclaw/mcp/router.py`](https://github.com/Unclecheng-li/VulnClaw/blob/main/vulnclaw/mcp/router.py) dynamically maps tool calls to the appropriate MCP service. Available services include:

- `fetch` – HTTP requests via `httpx`
- `memory` – Vector store queries
- `chrome-devtools` – Browser automation (requires Node.js)

Service definitions live in [`vulnclaw/mcp/registry.py`](https://github.com/Unclecheng-li/VulnClaw/blob/main/vulnclaw/mcp/registry.py), while lifecycle management (startup/shutdown) is handled by [`vulnclaw/mcp/lifecycle.py`](https://github.com/Unclecheng-li/VulnClaw/blob/main/vulnclaw/mcp/lifecycle.py).

### State Persistence and Snapshot Management

VulnClaw maintains session state through the target-state store ([`vulnclaw/target_state/store.py`](https://github.com/Unclecheng-li/VulnClaw/blob/main/vulnclaw/target_state/store.py)). The orchestrator's `apply_target_state_to_agent` function restores previous snapshots before running tasks, enabling resumable penetration tests.

Session data includes discovered findings, tool outputs, and the blackboard graph. The [`vulnclaw/plugins/runtime.py`](https://github.com/Unclecheng-li/VulnClaw/blob/main/vulnclaw/plugins/runtime.py) merges plugin outputs into `session_state.findings`, which [`vulnclaw/report/generator.py`](https://github.com/Unclecheng-li/VulnClaw/blob/main/vulnclaw/report/generator.py) renders into Markdown or HTML reports.

## Running Your First Scan

With the installation and configuration complete, execute a full penetration test against a target:

```bash

# Full automated scan

vulnclaw run http://target.example.com

```

For stage-specific execution:

```bash

# Reconnaissance only

vulnclaw recon http://target.example.com

```

To resume a previous session using the snapshot ID displayed in prior output:

```bash
vulnclaw run http://target.example.com --resume --snapshot-id abc123

```

## Advanced Usage Patterns

### Launching the Web Interface

The optional web UI provides a visual interface for monitoring scans. Install extra dependencies and launch:

```bash
pip install "vulnclaw[web]"
vulnclaw web

```

This opens `http://127.0.0.1:7788` by default.

### Developing Custom Plugins

The low-coupling plugin subsystem in `vulnclaw/plugins/` allows you to extend vulnerability detection capabilities. Plugins feed findings back into the blackboard, where the solver integrates them into the reasoning loop. When running from source, modifications to plugin files take effect immediately without reinstallation.

## Summary

- **Installation**: Clone Unclecheng-li/VulnClaw and run `pip install -e .` to expose the `vulnclaw` CLI via [`vulnclaw/cli/main.py`](https://github.com/Unclecheng-li/VulnClaw/blob/main/vulnclaw/cli/main.py).
- **Configuration**: Set LLM credentials via `vulnclaw config` or environment variables; storage is handled by [`vulnclaw/config/settings.py`](https://github.com/Unclecheng-li/VulnClaw/blob/main/vulnclaw/config/settings.py).
- **Architecture**: The [`vulnclaw/orchestrator.py`](https://github.com/Unclecheng-li/VulnClaw/blob/main/vulnclaw/orchestrator.py) manages the agent lifecycle, delegating to [`vulnclaw/agent/core.py`](https://github.com/Unclecheng-li/VulnClaw/blob/main/vulnclaw/agent/core.py) and the OODA loop in [`vulnclaw/agent/solver.py`](https://github.com/Unclecheng-li/VulnClaw/blob/main/vulnclaw/agent/solver.py).
- **Tooling**: MCP services route through [`vulnclaw/mcp/router.py`](https://github.com/Unclecheng-li/VulnClaw/blob/main/vulnclaw/mcp/router.py), with definitions in [`vulnclaw/mcp/registry.py`](https://github.com/Unclecheng-li/VulnClaw/blob/main/vulnclaw/mcp/registry.py).
- **Persistence**: Session snapshots enable resumable scans via [`vulnclaw/target_state/store.py`](https://github.com/Unclecheng-li/VulnClaw/blob/main/vulnclaw/target_state/store.py).
- **Execution**: Use `vulnclaw run` for full tests, `vulnclaw recon` for specific phases, and `--resume` with `--snapshot-id` to continue interrupted sessions.

## Frequently Asked Questions

### What Python version is required to run VulnClaw from source?

VulnClaw requires **Python 3.10 or higher** due to its reliance on modern asynchronous patterns and type hinting features used in [`vulnclaw/agent/core.py`](https://github.com/Unclecheng-li/VulnClaw/blob/main/vulnclaw/agent/core.py) and the solver engine. The `vulnclaw doctor` command verifies your Python version before allowing execution.

### Can I run VulnClaw without an LLM API key?

Yes, VulnClaw supports a key-less login flow through certain providers, though functionality may be limited compared to authenticated sessions. You can also configure local LLM endpoints that don't require API keys by modifying the provider settings in `~/.vulnclaw/config.yaml` or via the `vulnclaw config` CLI commands.

### How does VulnClaw maintain state between interrupted scans?

The framework uses a snapshot system implemented in [`vulnclaw/target_state/store.py`](https://github.com/Unclecheng-li/VulnClaw/blob/main/vulnclaw/target_state/store.py). When you run a scan, the orchestrator periodically saves the session state, including the blackboard graph and findings. Use the `--resume` flag with the specific `--snapshot-id` (displayed in previous command output or via `vulnclaw doctor`) to restore the exact agent state and continue from the previous checkpoint.

### Where are the vulnerability findings stored after a scan completes?

Findings are accumulated in `session_state.findings` by the plugin runtime ([`vulnclaw/plugins/runtime.py`](https://github.com/Unclecheng-li/VulnClaw/blob/main/vulnclaw/plugins/runtime.py)) during execution. Upon completion, the report generator ([`vulnclaw/report/generator.py`](https://github.com/Unclecheng-li/VulnClaw/blob/main/vulnclaw/report/generator.py)) processes these findings into Markdown or HTML reports saved to your local filesystem. The specific output path is configurable through the [`vulnclaw/config/schema.py`](https://github.com/Unclecheng-li/VulnClaw/blob/main/vulnclaw/config/schema.py) settings.