Getting Started

Prerequisites

• Python 3.12+
• PostgreSQL (for result persistence, memory, lookouts)
• API keys for search providers

Local Development

# Clone and install
git clone https://github.com/phdowling/krawl.git
cd krawl
pip install -e ".[dev]"

Environment Variables

Create a .env file in the project root. Krawl uses pydantic-settings and loads from .env automatically.

Required

Required for LLM (at least one)

Optional

Tuning Parameters

Model Overrides

You can override the default models via env vars:

Run the Server

uvicorn app.main:app --host 0.0.0.0 --port 8080 --reload

Health Check

curl http://localhost:8080/health

{"status": "ok", "version": "0.2.0"}

First Research Request

curl -N -X POST http://localhost:8080/research \
  -H "Content-Type: application/json" \
  -d '{
    "query": "What are the latest developments in AI agents?",
    "mode": "deep",
    "breadth": 4,
    "depth_levels": 3
  }'

The -N flag disables output buffering so you see SSE events as they arrive.

First Search Request

For a simple single-source search without the full research pipeline:

curl -X POST http://localhost:8080/search \
  -H "Content-Type: application/json" \
  -d '{
    "query": "AI agents 2025",
    "source": "exa"
  }'

Authentication

When MOGRA_API_KEY is set, all endpoints require the X-API-Key header:

curl -H "X-API-Key: your-key" http://localhost:8080/health

When MOGRA_API_KEY is empty or unset, authentication is disabled and all endpoints are publicly accessible. The server logs a warning on startup when auth is disabled.

CORS

Default allowed origins:

• https://krawl.sh
• http://localhost:5173
• http://localhost:3000

Configure via CORS_ORIGINS env var (JSON array format).