Local Deployment Instructions

Linux (Ubuntu/Debian)

1. Prerequisites

Tool	Why	Install
Python 3.12+	Runtime	sudo apt install python3 python3-pip
uv	Python dependency manager	curl -LsSf https://astral.sh/uv/install.sh | sh
Node.js 18+ & npm	Runs the Playwright MCP browser server	sudo apt install nodejs npm
ffuf (recommended)	Directory/endpoint fuzzing (skipped gracefully if absent)	sudo apt install ffuf
Ollama	Local LLM for the primary-testing agent	curl -fsSL https://ollama.com/install.sh | sh
NVIDIA NIM API key	Remote LLM for discovery & sequencing	Get a key from https://build.nvidia.com

2. Install the project dependencies

git clone <your-repo-url> && cd api-sec-agent
uv sync

3. Install the browser + Playwright MCP server

The discovery agent drives a real headless browser (@playwright/mcp). Install its Chromium:

 npx -y playwright@1.62.0-alpha-1783623505000 install chromium

(npx downloads @playwright/mcp automatically on first run.)

4. Configure environment

cp .env.example .env

Edit .env — at minimum:

NIM_API_KEY=your_nvidia_nim_api_key          # discovery & sequencing LLM
OLLAMA_MODEL=dolphin3-cyber                  # primary-testing LLM (local)
OLLAMA_BASE_URL=http://localhost:11434       # local Ollama endpoint
WORDLIST_PATH=/usr/share/SecLists/Discovery/Web-Content/common.txt  # for ffuf (optional)

5. Start a target application

This agent is designed to test authorized targets. The recommended one is crAPI (intentionally vulnerable API):

cd crAPI/deploy/docker
docker compose up          # web UI: http://localhost:8888

Or point it at any target you have permission to test.

6. Run the agent

# Back to the repo root:
uv run python main.py --url <TARGET_URL>
# e.g.
uv run python main.py --url http://localhost:8888

(Optional) Web UI [SOON]

A live dashboard with the browser explorer, endpoint list, workflow, and findings:

uv run python main_web.py          # open http://localhost:8080

(Optional) Run inside Docker with identity management [SOON]

sudo docker compose build
sudo docker compose up             # CLI mode
MODE=web sudo docker compose up    # Web UI mode on :8080