Skip to content

Configuration reference

ravnar can be configured in multiple ways:

  1. Through environment variables using the RAVNAR_ prefix.
  2. Through a YAML configuration file located at the value of the RAVNAR_CONFIG environment variable.

  3. Through a YAML configuration file named config.yaml or config.yml in the following directories:

    1. ./
    2. ~/.config/ravnar/
    3. /etc/ravnar/

The final configuration is merged from all sources in decreasing order of priority in the list above.

Templating

All configuration options are subject to Jinja templating. In addition to builtin functionality, the templates have access to the environment variables. This allows an otherwise static configuration file to be hydrated by dynamic or sensitive values.

Example

Consider a set database credentials as two environment variables DB_USERNAME and DB_PASSWORD for a PostgreSQL database located at DB_HOST. ravnar requires the connection details as DSN. In the configuration file this could like

storage:
  database:
    dsn: 'postgresql+psycopg://{{ DB_USERNAME }}:{{ DB_PASSWORD }}@{{ DB_HOST }}'

Plugins

ravnar is built upon a flexible plugin architecture for its core components. Plugins are defined in the configuration as string references to Python objects. These references can point to either a class (type) or a factory function, e.g.:

security:
  authenticator: ravnar.authenticators.ForwardedUserAuthenticator

On startup, the objects will be loaded and instantiated roughly equivalent to the following Python code:

from ravnar.authenticators import ForwardedUserAuthenticator

handler = ForwardedUserAuthenticator()

Import

For ravnar to import any object, it has to be on Python's search path. There are multiple ways to achieve this, e.g.:

  • Install your module as part of a package in your current environment.
  • Set the PYTHONPATH environment variable to include the directory your module is located in.
  • Set the RAVNARPATH environment variable that functions just as PYTHONPATH, but only affects ravnar.

Parameters

To parametrize the instantiation of a plugin, the configuration can be provided as dictionary containing cls_or_fn and params keys.

For example, the user ID header for ForwardedUserAuthenticator can be configured with:

security:
  authenticator:
    cls_or_fn: ravnar.authenticators.ForwardedUserAuthenticator
    params:
      id_header: X-My-User-Id
  • cls_or_fn: A string containing the import path to the class or factory function, following the same semantics as the simple string reference.
  • params: A dictionary of parameters that will be passed as keyword arguments to the class constructor or factory function.
from ravnar.authenticators import ForwardedUserAuthenticator as cls_or_fn

params = {
    "id_header": "X-My-User-Id",
}

handler = cls_or_fn(**params)

Nesting

The values for a plugin's parameters are not limited to simple types like strings or booleans. Any parameter can itself be defined using the same cls_or_fn and params structure.

Warning

You cannot use string references inside the params dictionary as they cannot be differentiated from simple strings.

For example, to configure a Pydantic AI agent for ravnar, you can nest its definition into the configuration of an agent plugin:

agents:
  my-agent:
    cls_or_fn: ravnar.agents.PydanticAiAgentWrapper
    params:
      agent:
        cls_or_fn: pydantic_ai.Agent
        params:
          model:
            cls_or_fn: pydantic_ai.models.openrouter.OpenRouterModel
            params:
              model_name: anthropic/claude-sonnet-4

ravnar will recognize the nested structure and recursively resolve it from the bottom upwards. First, it will instantiate the inner pydantic_ai.models.openrouter.OpenRouterModel object. Then, it will pass that newly created object as the model parameter when instantiating the middle pydantic_ai.Agent, which is finally passed to the outer ravnar.agents.PydanticAiAgentWrapper. This process is roughly equivalent to the following Python code:

from pydantic_ai.models.openrouter import OpenRouterModel as cls_or_fn

params = {
    "model_name": "anthropic/claude-sonnet-4",
}

model = cls_or_fn(**params)

from pydantic_ai import Agent as cls_or_fn

params = {
    "model": model,
}

agent = cls_or_fn(**params)

from ravnar.agents import PydanticAiAgentWrapper as cls_or_fn

params = {
    "agent": agent,
}

agents = {
    "my-agent": cls_or_fn(**params)
}

Configuration Options

Unless stated otherwise, all values for the configuration options displayed in this section are the default that will be used unless explicitly configured.

Server

Hostname

Hostname to bind the ravnar server to.

server:
  hostname: 127.0.0.1

RAVNAR_SERVER__HOSTNAME="127.0.0.1"

Port

Port to bind the ravnar server to.

server:
  port: 8000

RAVNAR_SERVER__PORT=8000

Proxy headers

Whether the X-Forwarded-Proto and X-Forwarded-For headers are used to populate the URL scheme and remote address information.

server:
  proxy_headers: false

RAVNAR_SERVER__PROXY_HEADERS=false

Forwarded Allow IPs

List if IP addresses for which the proxy headers are trusted.

server:
  forwarded_allow_ips:
    - '*'

RAVNAR_SERVER__FORWARDED_ALLOW_IPS="[\"*\"]"

Root path

A path prefix handled by a proxy that is not seen by the server.

server:
  root_path: ''

RAVNAR_SERVER__ROOT_PATH=""

Observability

Observability configuration comprising logging and tracing.

Logging

Level

Minimum level for log messages. Can be one of

  • "debug"
  • "info"
  • "warning"
  • "error"
  • "critical"
observability:
  logging:
    level: INFO

RAVNAR_OBSERVABILITY__LOGGING__LEVEL="INFO"
As JSON

Whether log messages should be emitted as JSON objects instead a human-readable format.

Note

Defaults to false in an interactive session.

observability:
  logging:
    as_json: true

RAVNAR_OBSERVABILITY__LOGGING__AS_JSON=true

Tracing

Span Processors

List of span processors configured as plugins.

Note

Defaults to exporting spans to the console using ravnar.observability.StructlogSpanExporter in interactive sessions and otherwise no span processing.

observability:
  tracing:
    span_processors: []

RAVNAR_OBSERVABILITY__TRACING__SPAN_PROCESSORS="[]"

Security

Authenticator

Optional reference to a ravnar.authenticators.Authenticator.

Warning

If not authenticator is configured, authentication is disabled.

security:
  authenticator: null

RAVNAR_SECURITY__AUTHENTICATOR=null

CORS

CORS configuration options

Allowed Origins

List of allowed origins. Use "*" to allow all origins. If "*" is used, it must be the sole entry.

security:
  cors:
    allowed_origins:
      - '*'

RAVNAR_SECURITY__CORS__ALLOWED_ORIGINS="[\"*\"]"
Allowed Headers

List of allowed headers. Use "*" to allow all headers. If "*" is used, it must be the sole entry.

security:
  cors:
    allowed_headers: []

RAVNAR_SECURITY__CORS__ALLOWED_HEADERS="[]"

Storage

Enabled

Whether storage is enabled.

storage:
  enabled: true

RAVNAR_STORAGE__ENABLED=true

Database DSN

URL of the database in the format

{dialect}+{driver}://{username}:{password}@{host}:{port}/{database}

Tip

Special characters such as @ or : have to be URL encoded. This can be achieved with the urlencode Jinja filter

'{{ "my:secret@password" | urlencode }}'

storage:
  database:
    dsn: sqlite:///{{ PWD }}/.ravnar_local/state.db

RAVNAR_STORAGE__DATABASE__DSN="sqlite:///${PWD}/.ravnar_local/state.db"

File Storage Path

Path of the file storage. See the universal-pathlib documentation for supported filesystems and protocols.

storage:
  files:
    path: '{{ PWD }}/.ravnar_local/files'

RAVNAR_STORAGE__FILES__PATH="${PWD}/.ravnar_local/files"

URL Data Source

Configuration for fetching files from URLs.

Enabled

Whether URL data sources are enabled.

storage:
  files:
    url_data_source:
      enabled: false

RAVNAR_STORAGE__FILES__URL_DATA_SOURCE__ENABLED=false
Allowed Hostnames

List of allowed hostnames for URL data sources. Use "*" to allow all hostnames. If "*" is used, it must be the sole entry.

storage:
  files:
    url_data_source:
      allowed_hostnames: []

RAVNAR_STORAGE__FILES__URL_DATA_SOURCE__ALLOWED_HOSTNAMES="[]"
Timeout

Timeout for fetching URL data sources in ISO8601 durations notation.

storage:
  files:
    url_data_source:
      timeout: PT30S

RAVNAR_STORAGE__FILES__URL_DATA_SOURCE__TIMEOUT="PT30S"

Agents

Either dynamic agents have to be enabled or at least one static agent has to be configured.

Dynamic Agents

Enabling Dynamic Agents

Whether references to ravnar.agents.Agents can be (un-)registered through the REST API.

agents:
  dynamic:
    enabled: false

RAVNAR_AGENTS__DYNAMIC__ENABLED=false
Allowed Environment Variables

List of environment variables that dynamic agents are allowed to access during creation. Use "*" to allow all environment variables. If "*" is used, it must be the sole entry.

agents:
  dynamic:
    allowed_env_vars: []

RAVNAR_AGENTS__DYNAMIC__ALLOWED_ENV_VARS="[]"

Static Agents

Mapping of references to ravnar.agents.Agents. The key is used as identifier for the agent.

agents:
  static:
    default: ravnar.agents.DefaultAgent

RAVNAR_AGENTS__STATIC="{\"default\": \"ravnar.agents.DefaultAgent\"}"

Example

Configuration for Claude Sonnet 4 used through OpenRouter:

agents:
  claude-sonnet-4:
    cls_or_fn: ravnar.agents.PydanticAiAgentWrapper
    params:
      agent:
        cls_or_fn: pydantic_ai.Agent
        params:
          model:
            cls_or_fn: pydantic_ai.models.openrouter.OpenRouterModel
            params:
              model_name: anthropic/claude-sonnet-4