Agent Auditor

Deployment

Docker Compose (API + worker + PostgreSQL)

cp .env.example .env        # then set POSTGRES_PASSWORD and AUDITOR_API_KEY
docker compose up --build
curl http://127.0.0.1:8000/readyz        # {"status":"ok"}

Compose refuses to start without both variables. The API container applies migrations (alembic upgrade head) before it serves; the worker starts after the API reports ready. Data lives in the pgdata volume.

Point the SDK at it:

auditor = Auditor("http://127.0.0.1:8000", agent="support-bot", api_key="<AUDITOR_API_KEY>")

Configuration

Variable Default Meaning
AUDITOR_DATABASE_URL sqlite:///./agent_auditor.db SQLAlchemy URL. Use postgresql+psycopg://user:pass@host/db in production.
AUDITOR_API_KEY unset (open) When set, every /v1 request must send it as X-API-Key. /healthz and /readyz stay open.
ANTHROPIC_API_KEY unset (helper off) Optional. Turns on the dashboard's AI helper and "Suggest a fix". Questions send the dashboard's figures to the Claude API.
AUDITOR_ASSISTANT_MODEL claude-sonnet-5-5 Model the helper uses.
AUDITOR_AUTO_CREATE_TABLES true Create missing tables at startup. Set false when Alembic manages the schema (Compose does).

Migrations

alembic upgrade head                       # new database
alembic stamp head                         # database that the app created itself (SQLite default)
alembic revision --autogenerate -m "..."   # after changing models/

Read the note at the top of migrations/versions/0001_baseline.py before changing a model for the first time. Run migrations from one place at a time; two API replicas starting together can race on the first upgrade.

Worker

agent-auditor-worker scores and diagnoses new runs for every agent every 30 seconds (production and canary environments). --once runs a single cycle. Run one worker per database.

Without Docker

pip install -e ".[postgres]"
export AUDITOR_DATABASE_URL=postgresql+psycopg://...
alembic upgrade head
AUDITOR_AUTO_CREATE_TABLES=false uvicorn agent_auditor.api.main:app --host 0.0.0.0
agent-auditor-worker

Before you expose it