Quickstart

April 19, 2026 · View on GitHub

Install

git clone https://github.com/Lazarus-AI/clearwing.git
cd clearwing
python3 -m venv venv
source venv/bin/activate  # fish: source venv/bin/activate.fish
pip install -e '.[dev]'

The [dev] extra pulls in pytest + mypy + ruff + build, which is what CI uses. For a production install, drop the [dev].

Faster alternative if you have uv installed: uv sync --all-extras reads pyproject.toml + uv.lock and reproduces the locked environment exactly.

Configure credentials

Clearwing talks to Anthropic by default. Either export the API key:

export ANTHROPIC_API_KEY=sk-ant-...

Or use an OpenAI-compatible endpoint (OpenRouter, Ollama, LM Studio, vLLM, Together, Groq, DeepSeek, OpenAI, ...):

# Per-command
clearwing interactive \
    --base-url https://openrouter.ai/api/v1 \
    --api-key "$OPENROUTER_API_KEY" \
    --model anthropic/claude-opus-4

# Per-session
export CLEARWING_BASE_URL=https://openrouter.ai/api/v1
export CLEARWING_API_KEY=$OPENROUTER_API_KEY
export CLEARWING_MODEL=anthropic/claude-opus-4
clearwing interactive

# Persistent
clearwing config --set-provider \
    base_url=http://localhost:11434/v1 \
    api_key=ollama \
    model=qwen2.5-coder:32b

See LLM providers for copy-paste snippets for every supported backend, including per-task routing (e.g. "hunter on OpenRouter, verifier on local Qwen for cross-provider independence").

Run a network scan

The simplest operation — scan a single host for open ports, services, and known vulnerabilities:

clearwing scan 192.168.1.10

Scan a specific port range with service detection:

clearwing scan 192.168.1.10 -p 22,80,443,8080 --detect-services

Scan a whole CIDR in parallel:

clearwing parallel 192.168.1.0/24 --max-concurrent 10

Results are persisted to a SQLite DB at ~/.clearwing/clearwing.db. View history:

clearwing history
clearwing report --session <session_id>

Run a source-hunt pass

Point Clearwing at a cloned repo or a git URL. The hunter will clone, rank, and analyze files according to the attack-surface ladder (see architecture for how ranking works).

# Quick pass — static analysis + regex patterns, no LLM, free
clearwing sourcehunt /path/to/repo --depth quick

# Standard pass — sandboxed LLM hunters, adversarial verifier,
# variant loop, mechanism memory, taint analysis. Default.
clearwing sourcehunt https://github.com/example/project \
    --depth standard

# Deep pass — adds crash-first harness generation (libFuzzer)
# and auto-patch validation (recompile + rerun PoC). The most
# rigorous mode; expects real build deps in the sandbox.
clearwing sourcehunt /path/to/repo \
    --depth deep --max-parallel 8 \
    --auto-patch

Output lives in ./results/sourcehunt/<session_id>/ (dev checkout) or ~/.clearwing/results/sourcehunt/<session_id>/ (PyPI install) — SARIF for IDE integration, markdown for humans, JSON for programmatic consumers.

Interactive agent

Start a ReAct-loop chat session with the full tool set:

clearwing interactive

The agent will plan, call tools (which may pause for human approval for anything destructive), and converge on a summary. Sessions are persisted; resume with:

clearwing sessions                 # list
clearwing interactive --resume <session_id>

Run the tests

make test          # pytest -q
make gate          # full CI gate locally: lint + type + test + build

Next