name: exaaiagent description: "Run, debug, maintain, or extend ExaAiAgent for AI-assisted penetration testing, attack-surface mapping, repo/code security review, and multi-agent offensive-security workflows. Use when an AI agent needs onboarding instructions for operating ExaAiAgent, when a user wants to launch scans from CLI/TUI, when ExaAiAgent itself needs maintenance, or when another agent should use ExaAiAgent with any LiteLLM-supported provider (OpenAI, Anthropic, OpenRouter, Ollama, Gemini-compatible endpoints, and other LiteLLM-backed providers)."

ExaAiAgent Skill

Use ExaAiAgent as a Docker-backed security testing framework powered by LiteLLM-compatible providers.

Core operating rules

• Treat EXAAI_LLM as the active model selector; set LLM_API_KEY and LLM_API_BASE only when the chosen provider needs them.
• The first run pulls the sandbox Docker image automatically.
• Save results under exaai_runs/<run-name>.
• Use only on assets the operator is authorized to test.

Installation and first scan

Install ExaAiAgent with either method:

# Method 1: pip
pip install exaai-agent

# Method 2: pipx
pipx install exaai-agent

Configure a LiteLLM-supported provider using the pattern export EXAAI_LLM="provider/model-name". Set LLM_API_KEY and LLM_API_BASE when the provider requires them.

Verify the setup before scanning:

docker version && exaai --version

Run the first scan and verify results:

exaai --target https://your-app.com
# Check results — if empty or errored, re-run with verbose output
ls exaai_runs/*/  || exaai --target https://your-app.com --verbose

Basic usage

# Local codebase
exaai --target ./app-directory

# GitHub repository review
exaai --target https://github.com/org/repo

# Black-box web assessment
exaai --target https://your-app.com

# Headless mode
exaai -n --target https://your-app.com

# Interactive mode
exaai tui

Smart auto-loading

ExaAiAgent auto-resolves prompt modules when --prompt-modules is not set.

exaai --target https://api.example.com/graphql          # GraphQL
exaai --target wss://chat.example.com/socket             # WebSocket
exaai --target https://auth.example.com/oauth/authorize  # OAuth/OIDC
exaai --target example.com --instruction "enumerate subdomains"  # Recon

Advanced usage

# Authenticated or grey-box testing
exaai --target https://your-app.com --instruction "Perform authenticated testing using provided credentials and identify authorization flaws"

# Multi-target testing
exaai -t https://github.com/org/app -t https://your-app.com

# Explicit modules
exaai --target https://api.example.com --prompt-modules graphql_security,waf_bypass

# Lightweight mode
EXAAI_LIGHTWEIGHT_MODE=true exaai --target https://example.com --instruction "quick security scan"

Diagnose common failures

Follow this order — each layer depends on the one above it:

1. Docker: Run docker version && docker info. Fix Docker before debugging anything else.
2. Provider/LiteLLM: Verify EXAAI_LLM, LLM_API_KEY, and LLM_API_BASE (when applicable). Confirm the provider/model pair is supported by LiteLLM.
3. Tool/runtime: If startup succeeds but scan execution fails, inspect sandbox startup, tool-server health, missing system dependencies, and model/provider rate limits.

Maintain ExaAiAgent itself

When editing ExaAiAgent:

1. Fix runtime, CLI, TUI, and tool-server issues before adding new features.
2. Keep version strings synchronized in pyproject.toml, exaaiagnt/interface/main.py, exaaiagnt/interface/tui.py, and README.md.
3. Keep LiteLLM as the model-provider abstraction layer.
4. Prefer stronger error surfacing over silent failure.

Before release, confirm tests pass, CI is green, version strings are aligned, docs are updated, and at least one real startup path was exercised.

pytest -q
python -m py_compile exaaiagnt/interface/main.py exaaiagnt/interface/tui.py exaaiagnt/runtime/tool_server.py
exaai --version