TraceroAI

Configuration

Every setting is an environment variable. The API and worker read the TRACEROAI_ ones; the dashboard has four of its own.

The API and the worker read the same settings. List-valued settings take JSON, for example TRACEROAI_ADMIN_API_KEYS='["<key>"]'; use [] or {} for none, never an empty string. An empty variable still counts as set: TRACEROAI_REDIS_URL= turns Redis off even if a .env file sets it.

The judge#

VariableDefaultWhat it does
TRACEROAI_OPENAI_API_KEYnoneTurns on embeddings and the LLM judge. Without it every diagnosis is an estimate
TRACEROAI_JUDGE_MODELgpt-4o-miniThe judge model
TRACEROAI_JUDGE_BASE_URLnoneAn OpenAI-compatible endpoint for another provider or a model you host; the key and model are then that provider's
TRACEROAI_EMBEDDING_MODELgemini-embedding-001 (Compose: text-embedding-3-small)The embedding model for the relevance check
TRACEROAI_DEEP_EVAL_ENABLEDtrueSet false to keep only the quick checks

Storage and queue#

VariableDefaultWhat it does
TRACEROAI_DATABASE_URLlocal PostgresPostgres connection string
TRACEROAI_REDIS_URLnoneThe evaluation queue and shared rate limits. Without it, evaluations run inside the API process
TRACEROAI_TRACE_RETENTION_DAYSkeep foreverDelete traces older than this. The worker checks hourly; without the worker, run python -m app.retention on a schedule
TRACEROAI_DB_POOL_SIZE / _MAX_OVERFLOW5 / 10Database connections per process

Access#

VariableDefaultWhat it does
TRACEROAI_APP_ENVdevelopmentdevelopment or testing: keys optional. staging or production: keys required
TRACEROAI_REQUIRE_API_KEYfrom APP_ENVOverride whether keys are required
TRACEROAI_ADMIN_API_KEYS[]Keys that read every project, such as the dashboard's
TRACEROAI_PROJECT_API_KEYS{}Bootstrap project keys as {"key": "project"}. Prefer python -m app.keys, which stores them hashed
TRACEROAI_PUBLIC_READ_PROJECTS[]Projects anyone may read without a key
TRACEROAI_CORS_ORIGINS[]Extra browser origins allowed to call the API
TRACEROAI_TRUSTED_PROXY_COUNT0Proxies in front of the API that add X-Forwarded-For (1 behind a single load balancer); used to tell callers apart for rate limits
TRACEROAI_PLAYGROUND_ENABLEDfalseThe keyless "try it" endpoint. Leave off on anything public

Limits#

VariableDefaultWhat it does
TRACEROAI_MAX_REQUEST_BYTES1,000,000Largest request body (413 above it)
TRACEROAI_INGEST_RATE_LIMIT_PER_MINUTE1,200Traces per key (or per address without one)
TRACEROAI_GRADE_RATE_LIMIT_PER_MINUTE120Grading calls per key
TRACEROAI_MAX_FEEDBACK_PER_TRACE100Feedback entries kept per trace

The worker#

VariableDefaultWhat it does
TRACEROAI_WORKER_CONCURRENCY1Jobs one worker processes at once
TRACEROAI_WORKER_VISIBILITY_TIMEOUT_SECONDS600How long a job may run before another worker takes it over
TRACEROAI_STALLED_EVALUATION_SECONDS900A trace still pending this long, with nothing queued, is queued again
TRACEROAI_FALLBACK_EVAL_WORKERS2Threads for evaluation inside the API when there's no Redis
TRACEROAI_WORKER_METRICS_PORTnoneServe the worker's Prometheus metrics on this port
TRACEROAI_LOG_LEVELINFOLog level

The dashboard#

VariableWhat it does
TRACEROAI_API_URLWhere the dashboard's server reaches the API (http://api:8000 in Compose). With no API address set, the dashboard shows how to self-host instead
NEXT_PUBLIC_TRACEROAI_API_URLThe API address for code running in the browser (the docs playground). Set at build time
TRACEROAI_API_KEYThe admin key the dashboard reads with, on the server only
TRACEROAI_DASHBOARD_PASSWORDRequire a shared password to open the dashboard

The SDK#

VariableWhat it does
TRACEROAI_API_URLThe API address, if not passed as base_url
TRACEROAI_API_KEYThe key, if not passed as api_key
TRACEROAI_ENABLEDfalse turns every send into a no-op