Providers

Providers are YAML files in .aura/config/providers/. Each file configures a connection to an LLM backend.

Provider Types

Type	Protocol	Capabilities
`ollama`	Native Ollama API	Chat, embedding, thinking, vision
`llamacpp`	OpenAI-compatible	Chat, reranking, thinking, vision, STT (whisper), TTS (kokoro)
`llamaswap`	llama-swap with llama.cpp workers	llama.cpp inference, per-model tokenization, load/unload routing
`openrouter`	OpenRouter API	Chat, embedding (cloud models, token auth)
`openai`	OpenAI Responses / Chat Completions	Chat, embedding, transcription, synthesis
`anthropic`	Native Anthropic Messages API	Chat, thinking, vision, tools
`google`	Native Gemini API	Chat, thinking, vision, tools, embedding
`copilot`	GitHub Copilot (dual-protocol)	Chat (GPT via Responses API, Claude via Messages API)
`codex`	OpenAI Plus (Responses API)	Chat (ChatGPT Plus/Pro subscription)
`script`	Local replay file	Deterministic chat for tests (no model)

All providers implement a 4-method core interface (Chat, Models, Model, Estimate). Optional capabilities use opt-in interfaces discovered via providers.As[T](provider).

YAML Schema

provider_name:
  # Required for most providers; optional for anthropic/google (have defaults).
  url: http://host.docker.internal:11434

  # Determines which API protocol to use (required).
  # Values: ollama, llamacpp, llamaswap, openrouter, openai, anthropic, google, copilot, codex.
  type: ollama

  # Auth token. Falls back to AURA_PROVIDERS_{NAME}_TOKEN env var.
  # token: ""

  # Additional HTTP headers (openai type only). Values support environment expansion.
  # headers:
  #   X-Custom-Header: value

  # Wire API for type openai only: responses or chat_completions.
  # Omitted: SDK model-name detection. Set responses for current OpenAI models.
  # api: responses

  # How long models stay loaded in VRAM (Ollama only). Go duration syntax.
  # keep_alive: 15m

  # Wait for server to start responding. Does not affect streaming. Default: 5m.
  # timeout: 5m

  # Model visibility filter for `aura models` and `/model`.
  # Does NOT affect --model flag or feature agents.
  models:
    include: [] # Glob patterns — empty means all
    exclude: [] # Applied after include

  # Declared capabilities. Empty = all assumed.
  # Values: chat, embed, rerank, transcribe, synthesize.
  # capabilities: []

  # Retry for transient Chat() failures. Disabled by default (max_attempts: 0).
  # Only applies to ollama/llamacpp/llamaswap — other providers have built-in retry.
  retry:
    max_attempts: 0
    base_delay: 1s
    max_delay: 30s

For type: openai, set api: responses when using the OpenAI API or a gateway that implements Responses. Set api: chat_completions for a server that only implements Chat Completions. This explicit choice also applies to models introduced after the SDK was released; an unrecognized name must not determine which endpoint you use. Omitting api retains the SDK’s model-name detection. Copilot follows its discovered supported endpoints, and Codex always uses Responses.

Token Resolution

token field in provider YAML — supports $VAR / ${VAR} expansion
AURA_PROVIDERS_{NAME}_TOKEN environment variable
Value from --env-file

openrouter:
  type: openrouter
  url: https://openrouter.ai/api/v1
  token: ${OPENROUTER_API_KEY}

anthropic:
  type: anthropic
  token: ${ANTHROPIC_API_KEY}

Examples

# Ollama (local)
my_ollama:
  url: http://host.docker.internal:11434
  type: ollama
  keep_alive: 15m
  models:
    exclude: ["*embed*"]

# OpenAI (also works for Groq, DeepSeek, or any /v1/responses-compatible service)
openai:
  url: https://api.openai.com/v1
  type: openai
  timeout: 5m

# Anthropic — URL defaults to https://api.anthropic.com
anthropic:
  type: anthropic
  timeout: 5m

# Google Gemini — URL defaults to Google's endpoint
google:
  type: google
  timeout: 5m

# GitHub Copilot — authenticate via `aura login copilot` or AURA_PROVIDERS_COPILOT_TOKEN
copilot:
  type: copilot
  timeout: 5m

# ChatGPT Plus/Pro — authenticate via `aura login codex` or AURA_PROVIDERS_CODEX_TOKEN
codex:
  type: codex
  timeout: 5m

Local servers and gateways

For the openai type, generation.think_budget is forwarded as the thinking_budget_tokens extension on both Chat Completions and Responses requests. Use it with a compatible backend; the OpenAI API itself does not support this numeric budget. Omitting it leaves the backend default unchanged. Bifrost requires its documented passthrough header to retain extensions:

bifrost:
  type: openai
  url: https://bifrost.example.com/v1
  token: ${BIFROST_TOKEN}
  headers:
    x-bf-passthrough-extra-params: "true"

Use llamacpp for llama-server and its native router. Use llamaswap for llama-swap backed by llama.cpp workers:

local_models:
  type: llamaswap
  url: http://localhost:8080

Both share the chat implementation. llama-swap routes native properties, template application and tokenization through /upstream/<model>/; its unload API is /api/models/unload/<model>. Loading requests the worker’s properties. These routes differ from llama.cpp’s native router, which uses /models/load and /models/unload.

Model listings retain the context and capabilities the server advertises. Resolving a selected llama.cpp model also reads /props and checks whether applying its template with thinking enabled versus disabled changes the prompt. This uses no generated tokens. An unchanged template or an unavailable template endpoint leaves boolean thinking support unknown; it does not establish that reasoning is unsupported. Prior-reasoning preservation is a separate capability.

Bifrost uses type: openai with its /v1 URL and qualified model IDs. It does not expose llama-swap’s native control endpoints. Reasoning efforts follow the OpenAI contract; model-specific template switches are not inferred or injected into gateway requests. If the upstream has no token-count endpoint, native estimation reports that limitation and uses the configured local estimator. Use rough+tiktoken explicitly when native counting is unavailable.

Script

The script provider replays a JSON file of scripted responses, tool calls, delays and typed failures through the real engine. It exists to test automation clients and lifecycle behaviour deterministically.

scripted:
  type: script
  script: /abs/path/script.json

{
  "models": [{ "name": "script", "context": 65536 }],
  "steps": [
    { "content": "Looking.", "calls": [{ "name": "Bash", "args": { "command": "ls" } }] },
    { "content": "partial", "stall": "30s" },
    { "error": { "class": "server", "status": 503, "message": "the engine is not running" } }
  ]
}

Each chat request consumes the next step: delay (wait before responding), thinking, content, stall (wait after streaming, before returning), calls (id optional), finish (the reported finish reason: stop, length, tool_calls, content_filter, error, other or unreported; by default tool_calls with calls and stop otherwise) or error (class is one of network, server, rate_limit, auth, credit, model_unavailable, content_filter, context; optional status, retry_after). Waits honour cancellation. metadata_error (same shape as error) fails every model metadata request. The replay position is persisted in <script>.cursor (a step is consumed when it starts), so a run killed and resumed in a new process continues with the next step; delete the cursor to restart. An exhausted script fails the request explicitly. Unknown fields, classes or durations fail at load.

Catwalk Registry

The openai provider resolves model IDs from GET /models, so gateways do not need a separate GET /models/<id> endpoint. Use the exact ID advertised by the gateway, such as openai/gpt-5-nano behind Bifrost. Requests retain that qualified ID; registry enrichment also recognizes the matching provider prefix. OpenAI models use the Responses API; other model IDs use Chat Completions. Catalog context lengths and reported vision, tools and reasoning capabilities are retained. Missing capability fields remain unknown.

Model capabilities (context length, vision, thinking levels) are enriched at startup using Catwalk metadata. Aura ships with compiled-in embedded data for offline use. On startup it fetches fresh data and caches it to .aura/cache/catwalk/; on failure it falls back to the disk cache then the embedded data.

Enrichment only fills gaps — it never overwrites capabilities reported by the provider API. Applies to anthropic, openai, and google (their listing APIs return only model IDs). Other providers build capabilities inline from their own API responses.

Use --no-cache to force a fresh fetch, or aura cache clean to delete cached data.

Add as many providers as needed — create new YAML files in providers/. Any provider type can use a custom URL (remote Ollama instance, self-hosted OpenAI-compatible server, etc.).