Skip to content

Configuration reference

Aegis is configured via aegis.yaml. All fields are validated at startup via pydantic v2 models. A schema change that breaks a config example breaks CI.

Plugin lifecycle

%%{init: {'theme': 'base', 'themeVariables': {'background': 'transparent', 'primaryColor': '#3f51b5', 'primaryTextColor': '#ffffff', 'primaryBorderColor': '#283593', 'lineColor': '#7986cb', 'secondaryColor': '#3949ab', 'tertiaryColor': '#5c6bc0', 'clusterBkg': '#e8eaf6', 'clusterBorder': '#7986cb', 'edgeLabelBackground': '#e8eaf6', 'titleColor': '#1a237e', 'nodeTextColor': '#ffffff'}}}%%
flowchart LR
    subgraph INSTALL[Install]
        PKG[pip install aegis-guardrail-foo]
        EP[entry_points aegis.guardrails]
    end
    subgraph STARTUP[Startup]
        DISC[PluginRegistry.discover]
        VAL[validate_config AegisConfig]
        ASM[PipelineAssembler.compile per route]
    end
    subgraph RUNTIME[Runtime]
        ROUTE[Route request]
        NODE[Node.run RunState]
        VERDICT[Verdict aggregate]
    end
    PKG --> EP --> DISC --> VAL --> ASM --> ROUTE --> NODE --> VERDICT

Top-level keys

All top-level keys are optional — omitted keys use defaults.

providers

A map of named provider profiles.

providers:
  my_provider:
    type: anthropic          # required: provider type
    api_key: secret://env/KEY  # optional: credential
    base_url: https://...    # optional: endpoint override
    model: claude-sonnet-4-5  # optional: default model
    residency:               # optional: residency metadata
      region: eu-west
      jurisdiction: GDPR
      source_url: https://provider.com/privacy

Bases: _StrictModel

A single LLM provider profile.

guardrails

A map of named guardrail configurations.

guardrails:
  pii:
    pack: aegis.pii          # required: dotted module path or pack name
    mode: mask               # optional: pack-specific option
  injection:
    pack: aegis.regex_guard

Bases: _StrictModel

pipeline

Ordered node lists for each pipeline stage.

pipeline:
  ingress: [pii, injection]    # run before model call
  tool_call: []                # run on model tool-call output
  tool_result: [injection]     # run on tool/RAG results
  egress: [pii.unmask]         # run on model response

Bases: _StrictModel

routes

A map of named route profiles.

aegis.yaml (partial)
routes:
  default:
    provider: my_provider    # required: must reference a declared provider
    model: gpt-4o            # optional: model override

Bases: _StrictModel

auth

Authentication mode.

auth:
  type: api_key    # "none" (dev only) or "api_key"

Bases: _StrictModel

Environment layering

Any config key can be overridden with an environment variable using double-underscore separators:

AEGIS__ROUTES__DEFAULT__MODEL=gpt-4o
AEGIS__AUTH__TYPE=api_key

This follows pydantic-settings conventions. Environment variables take precedence over aegis.yaml values.

Validation

Run aegis config validate to check your config before starting the server:

aegis config validate
# ✓ aegis.yaml is valid

Errors use AEG-CFG-* codes. See error codes for the full table.