Configuration

Environment variables

Variable	Purpose	Required
`DATABASE_URL`	Postgres connection string	yes
`ADMIN_TOKEN`	Bearer token guarding `/api/*` (except `/api/health`)	yes in production
`ENCRYPTION_KEY`	64 hex chars (32 bytes). AES-256-GCM key for encrypting provider API keys at rest	yes if you store keys via the UI
`OPENAI_API_KEY`	Embeddings (`text-embedding-3-large`, 1024 dims)	yes for the demo
`ANTHROPIC_API_KEY`	Generation tasks (bug coverage, Q&A)	yes for the demo
`STORAGE_PATH`	Where uploaded files are written. Defaults to `/app/data/files` in Docker	no
`LOG_LEVEL`	pino level (`trace` … `fatal`)	no — defaults to `info`
`PORT`	Defaults to `3000`	no

Providers and tasks

Every AI call goes through a single runTask(taskName, input) path that resolves the configured provider/model for that task. There are four tasks:

Task	Description	Capabilities
`embed`	Embeds text for semantic retrieval	embedding
`bug_coverage`	Decides if a bug is covered by existing tests	structured output
`qa_chat`	Streaming Q&A over the corpus	streaming, long context
`semantic_link`	(forward-compat) decides if a commit implements a candidate ticket	structured output, fast

Resolution order, in priority:

Database assignment. If AiTaskAssignment has a row for the task, that wins. The provider’s encrypted API key is decrypted with ENCRYPTION_KEY.
Env fallback. If no DB row, Oracus.ai picks the first provider whose env key is set, using sensible defaults from AI_TASKS (Anthropic for generation, OpenAI for embeddings).
Unconfigured. The task fails with a clear error pointing the user to Settings or env.

Defaults

Out of the box, the embed task uses text-embedding-3-large with dimensions: 1024 (Matryoshka truncation — official OpenAI feature). This keeps the schema’s vector(1024) column fixed and pgvector’s HNSW index consistent.

Generation tasks default to Claude Sonnet 4.5 (or Haiku 4.5 for the fast semantic_link path). Override per-task in Settings or by creating an AiTaskAssignment row directly.

Switching to a local model

Oracus.ai has no bundled local model — the image stays small. To run locally, point the openai_compatible provider at an Ollama or LM Studio endpoint:

Kind: openai_compatible
Base URL: http://host.docker.internal:11434/v1
API key: anything (some servers ignore it)

Then assign the appropriate model name (e.g. llama3.1:8b-instruct for generation, nomic-embed-text:v1.5 truncated to 1024 dims for embeddings — note that some Ollama embed models don’t support truncation).

Forgetting credentials

Click Forget admin token at the bottom of Settings to remove the bearer token from this browser. To rotate API keys, delete the provider row and add a new one — Oracus.ai re-assigns tasks automatically.