Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/AdithyaaSivamal/Agentic-AFL/llms.txt

Use this file to discover all available pages before exploring further.

Agentic-AFL reads all sensitive and deployment-specific settings from environment variables, keeping secrets and infrastructure addresses out of source code entirely. If a .env file is present at the project root, python-dotenv loads it before any field in AgenticAFLConfig is evaluated. Explicit environment variable exports set in the shell always take priority over .env values — python-dotenv deliberately does not overwrite variables that are already present in os.environ. This means you can commit a .env with safe development defaults and override individual keys in CI or production without modifying the file.

​
.env Template

Copy this template to the project root, fill in your values, and Agentic-AFL will pick them up automatically on the next start.
.env
# LLM Provider
LLM_API_PROVIDER=openai           # openai | gemini | local
LLM_API_KEY=sk-...               # OpenAI API key
GEMINI_API_KEY=                  # Google Gemini API key (if using Gemini)
LLM_MODEL_NAME=gpt-4.1-2025-04-14

# Ghidra
GHIDRA_INSTALL_DIR=/opt/ghidra
GHIDRA_PROJECT_DIR=/tmp/ghidra_projects

# PostgreSQL
POSTGRES_DSN=postgresql://agentic_afl:agentic_afl@localhost:5432/agentic_afl

# AFL++ Integration
AFL_OUTPUT_DIR=./afl_output
AFL_SYNC_DIR=./afl_output/sync_dir
MIN_STALL_TIME_SECONDS=0          # 0 = use cycle-based detection

# Z3
Z3_TIMEOUT_SECONDS=5
Z3_SANDBOX_DIR=/tmp/agentic_afl_sandbox

# Tuning
K_VOTE_COUNT=3

# Logging
LOG_LEVEL=INFO
LOG_DIR=./logs
DEBUG_MODE=false
Never commit your .env file or API keys to version control. Add .env to your .gitignore immediately. Leaked API keys can result in significant unexpected charges and security exposure.

​
Full Reference Table

Environment Variablesettings fieldDefaultDescription
LLM_API_PROVIDERllm_api_provideropenaiLLM backend: openai, gemini, or local
LLM_API_KEYllm_api_key(empty)OpenAI API key
GEMINI_API_KEYgemini_api_key(empty)Google Gemini API key
LLM_MODEL_NAMEllm_model_namegpt-4.1-2025-04-14Model identifier passed to the provider API
GHIDRA_INSTALL_DIRghidra_install_dir/opt/ghidraPath to Ghidra installation directory
GHIDRA_PROJECT_DIRghidra_project_dir/tmp/ghidra_projectsGhidra headless project storage directory
POSTGRES_DSNpostgres_dsnpostgresql://agentic_afl:agentic_afl@localhost:5432/agentic_aflPostgreSQL connection string
AFL_OUTPUT_DIRafl_output_dir./afl_outputAFL++ campaign output directory
AFL_SYNC_DIRafl_sync_dir./afl_output/sync_dirSync directory for solved payload injection
MIN_STALL_TIME_SECONDSmin_stall_time_seconds0Seconds without new edges before stall; 0 uses cycle-based detection
Z3_TIMEOUT_SECONDSz3_timeout_seconds5Hard timeout for each Z3 s.check() call
Z3_SANDBOX_DIRz3_sandbox_dir/tmp/agentic_afl_sandboxTemp directory for Z3 subprocess files
K_VOTE_COUNTk_vote_count3Number of Z3 scripts generated per stall for K-way voting
LOG_LEVELlog_levelINFOPython logging level (DEBUG, INFO, WARNING, ERROR, CRITICAL)
LOG_DIRlog_dir./logsDirectory for structured log output files
DEBUG_MODEdebug_modefalseSet to 1, true, or yes to save raw LLM completions and Z3 scripts to /tmp/agentic_afl_debug/

​
LLM Provider Configuration

Agentic-AFL supports three LLM backends. The LLM_API_PROVIDER variable selects which client is instantiated at startup; the remaining LLM variables are forwarded to that client only.

​
OpenAI (default)

LLM_API_PROVIDER=openai
LLM_API_KEY=sk-...
LLM_MODEL_NAME=gpt-4.1-2025-04-14

​
Switching to Google Gemini

LLM_API_PROVIDER=gemini
GEMINI_API_KEY=AIza...
LLM_MODEL_NAME=gemini-2.0-flash-exp
Gemini’s thinking-mode models count chain-of-thought tokens against llm_max_output_tokens. The default of 16384 is sufficient for most Z3 scripts, but raise it if you observe truncated outputs on complex constraint systems.

​
Local / Self-hosted

LLM_API_PROVIDER=local
LLM_MODEL_NAME=<your-local-model-name>
When local is selected, Agentic-AFL routes requests to a locally running inference server (for example, Ollama or vLLM). No API key is required. Ensure the server is reachable and the model name exactly matches what the server exposes.

​
PostgreSQL Setup

Agentic-AFL uses PostgreSQL as its spec store and CARM (Constraint-Aware Retrieval Module) backend. A custom jaccard_similarity() SQL function computes tag-set similarity server-side, making CARM queries efficient even on large template collections.

​
Starting PostgreSQL with Docker

The quickest way to spin up a compatible instance during development is the official PostgreSQL Docker image: 
docker run -d \
  --name agentic-afl-postgres \
  -e POSTGRES_USER=agentic_afl \
  -e POSTGRES_PASSWORD=agentic_afl \
  -e POSTGRES_DB=agentic_afl \
  -p 5432:5432 \
  postgres:16
This matches the default POSTGRES_DSN exactly, so no further configuration is needed for a local development setup.

​
Applying the Schema

Once the container is running, apply the initialization schema from the repository: 
psql postgresql://agentic_afl:agentic_afl@localhost:5432/agentic_afl \
  -f agentic-afl/db/init.sql
The init.sql script creates the constraint_templates table, the JSONB indexes, and the jaccard_similarity() function that CARM queries rely on. The schema must be applied before Agentic-AFL’s first run; subsequent runs are idempotent.

​
Connecting to a Remote or Managed Database

Override POSTGRES_DSN with any valid libpq connection string to point Agentic-AFL at a remote or managed PostgreSQL instance (for example, Amazon RDS or Cloud SQL): 
POSTGRES_DSN=postgresql://user:password@db.example.com:5432/agentic_afl?sslmode=require
python-dotenv is an optional dependency. If it is not installed in your environment, Agentic-AFL silently skips .env file loading and falls back to plain os.environ. All environment variables set directly in the shell or in your container runtime’s environment still work exactly as documented — no .env file is required.

Build docs developers (and LLMs) love

Get started for freeTalk to us