api
    2026-04-13

    Configuration Guide

    Complete environment variable reference for Aegis Sovereign — database, auth, secret key providers, LLM gateway, SIEM, and observability settings.

    configuration
    environment
    env-vars
    secrets
    multi-region

    Required Variables

    These variables must be set before the application will start.

    bash
    python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"
    VariableDescription
    `DATABASE_URL`PostgreSQL asyncpg connection string
    `REDIS_URL`Redis connection URL (pub/sub + cache)
    `CELERY_BROKER_URL`Redis URL for Celery broker (db 1)
    `CELERY_RESULT_BACKEND`Redis URL for task results (db 2)
    `SECRET_ENCRYPTION_KEY`32-byte Fernet key for at-rest encryption of provider credentials

    Authentication Variables

    OIDC and SCIM configuration. DEV_AUTH_ENABLED=true unlocks /auth/dev-login for local development — remove before production.

    VariableDescription
    `OIDC_ISSUER`OIDC provider issuer URL (e.g. Keycloak realm URL or Okta issuer)
    `OIDC_JWKS_URI`JWKS endpoint (auto-derived from issuer if blank)
    `DEV_AUTH_ENABLED``true` enables `/auth/dev-login` (CI/local only)
    `DEV_JWT_SECRET`HS256 secret for dev tokens
    `SCIM_BEARER_TOKEN`Static bearer token for SCIM 2.0 IdP provisioning connector

    Secret Key Provider

    The encryption key is resolved at runtime from one of four backends. env is the default. For production deployments use vault, aws_kms, or azure_keyvault to avoid storing the key in environment variables.

    VariableDescription
    `SECRET_KEY_PROVIDER``env` (default) | `vault` | `aws_kms` | `azure_keyvault`
    `SECRET_KEY_CACHE_TTL`Seconds to cache the resolved key (default: 300)
    `VAULT_ADDR`HashiCorp Vault address
    `VAULT_TOKEN`Vault token with read access
    `VAULT_SECRET_PATH`KV v2 path to the encryption key
    `KMS_KEY_ID`AWS Secrets Manager secret name or ARN
    `AZURE_KEYVAULT_URL`Azure Key Vault URL
    `AZURE_SECRET_NAME`Secret name in Azure Key Vault

    LLM Gateway Variables

    Control the LLM gateway routing and safety evaluation behaviour.

    VariableDescription
    `SAFETY_EVALUATOR_MODEL`Model for prompt safety evaluation (default: `gpt-4o-mini`)
    `GATEWAY_LOG_PROMPTS``true` logs full prompts (off by default for privacy)
    `LLM_ALLOW_EXTERNAL_PROVIDERS``false` for air-gapped or sovereign deployments (blocks OpenAI, Anthropic, etc.)
    `RATE_LIMIT_LLM_PER_MINUTE`Workspace-level LLM rate limit (default: 60 requests/minute)

    SIEM Variables

    Configure one or more SIEM backends. All adapters are optional — only set the variables for the providers you use.

    VariableDescription
    `SIEM_SPLUNK_HEC_URL`Splunk HEC endpoint URL
    `SIEM_SPLUNK_HEC_TOKEN`Splunk HEC token
    `SIEM_DATADOG_API_KEY`Datadog API key
    `SIEM_DATADOG_SITE`Datadog site (default: `datadoghq.com`; use `datadoghq.eu` for EU residency)
    `SIEM_CLOUDWATCH_LOG_GROUP`AWS CloudWatch log group name
    `SIEM_GCP_LOG_NAME`GCP Cloud Logging log name
    `GCP_PROJECT_ID`GCP project ID (used for Cloud Logging, Pub/Sub, and SCC)

    Observability Variables

    Logging format, rate limiting, and proxy trust settings.

    VariableDescription
    `LOG_FORMAT``json` (default) or `dev` (human-readable colour output)
    `LOG_LEVEL``INFO` / `DEBUG` / `WARNING`
    `RATE_LIMIT_ENABLED``true` / `false`
    `TRUST_PROXY``true` to use `X-Forwarded-For` for real client IP (required behind load balancers)

    AI Governance Agent Variables

    The four AI Governance Agents authenticate to the platform API using a machine-to-machine PAT with the ops role. Notification variables are optional — set only the providers you use. If none are set, incident notifications are logged to the audit trail only.

    bash
    1curl -X POST https://sovereign.yourcompany.com/api/v1/auth/tokens \
2  -H "Authorization: Bearer $ADMIN_TOKEN" \
3  -H "Content-Type: application/json" \
4  -d '{"name": "agent-m2m", "role": "ops", "expires_in_days": 365}'
5# → { "token": "pat_..." }
6# Set this value as AGENT_API_KEY
    VariableDescription
    `AGENT_API_KEY`M2M PAT with `ops` role — used by all four agents to call platform APIs
    `AGENT_LLM_MODEL`LLM model for agent reasoning (default: `gpt-4o-mini`). Routed through the internal LLM gateway.
    `AGENT_SLACK_WEBHOOK_URL`Slack incoming webhook URL for IncidentResponseAgent notifications
    `AGENT_JIRA_URL`JIRA base URL (e.g. `https://yourorg.atlassian.net`) for automated ticket creation
    `AGENT_JIRA_EMAIL`JIRA user email for API authentication
    `AGENT_JIRA_API_TOKEN`JIRA API token (Atlassian account settings → Security → API tokens)
    `AGENT_JIRA_PROJECT_KEY`JIRA project key where governance incident tickets are created (e.g. `GOV`)
    `AGENT_PAGERDUTY_KEY`PagerDuty Events API v2 routing key — critical-severity incidents only (robustness < 0.4, DIR < 0.6, or `safety_violation.critical`).

    MCP Server Variables

    These variables are set in the MCP Server process environment (not the backend). They configure the standalone @aegissovereign/mcp-server package used by Claude Code and Claude Desktop.

    VariableDescription
    `AEGISSOVEREIGN_BASE_URL`Platform API base URL (e.g. `https://sovereign.yourcompany.com`)
    `AEGISSOVEREIGN_API_KEY`API key with at least `ops` role — can be the same PAT as `AGENT_API_KEY`
    `AEGISSOVEREIGN_WORKSPACE_ID`Default workspace ID used when tools are called without an explicit workspace argument

    AI Safety Platform Variables

    Configure the Safety Policy Engine ML classifier ensemble, the external safety integrations (SIEM + alerting), and the ModelSafetyRegistry. All variables are optional — the platform runs safely with defaults when not set, falling back to regex-only detection and no external dispatch.

    bash
    1# Enable Llama Guard via Ollama (no API key required)
2docker run -d -p 11434:11434 ollama/ollama
3docker exec <container> ollama pull llama-guard3
4export SAFETY_CLASSIFIER=llama_guard
5
6# Production ensemble (highest severity across all classifiers)
7export SAFETY_CLASSIFIER=llama_guard,openai_moderation
8export SAFETY_CLASSIFIER_STRATEGY=highest_severity
9
10# External integrations (hub dispatches to all configured providers)
11export SAFETY_INTEGRATIONS=pagerduty,slack,jira
12export PAGERDUTY_ROUTING_KEY=your-routing-key
13export SLACK_WEBHOOK_URL=https://hooks.slack.com/...
14export JIRA_BASE_URL=https://corp.atlassian.net
15export JIRA_EMAIL=safety-bot@corp.com
16export JIRA_API_TOKEN=your-token
17export JIRA_PROJECT_KEY=SAFE
    VariableDefaultDescription
    `SAFETY_CLASSIFIER`*(empty = NullClassifier)*Comma-separated classifier names: `llama_guard`, `openai_moderation`, `azure_content_safety`, `shieldgemma`, `null`
    `SAFETY_CLASSIFIER_STRATEGY``highest_severity`Ensemble voting strategy: `highest_severity`, `majority_vote`, `all_flag`, `weighted_vote`
    `LLAMA_GUARD_ENDPOINT``http://localhost:11434`Ollama / HuggingFace TGI base URL for Llama Guard
    `LLAMA_GUARD_MODEL``llama-guard3`Ollama model name
    `AZURE_CONTENT_SAFETY_ENDPOINT`Azure AI Content Safety endpoint URL
    `AZURE_CONTENT_SAFETY_KEY`Azure AI Content Safety API key
    `OPENAI_API_KEY`OpenAI API key (for `openai_moderation` classifier)
    `GOOGLE_API_KEY`Google API key (for `shieldgemma` classifier)
    `SAFETY_INTEGRATIONS`*(empty = none)*Comma-separated integration providers: `splunk`, `cloudwatch`, `pagerduty`, `slack`, `jira`
    `SAFETY_REGISTRY_PATH`*(in-memory)*JSON file path for ModelSafetyRegistry persistence across restarts
    `SPLUNK_HEC_URL`Splunk HEC collector URL
    `SPLUNK_HEC_TOKEN`Splunk HEC token
    `PAGERDUTY_ROUTING_KEY`PagerDuty Events API v2 routing key (for safety alert dispatch; distinct from `AGENT_PAGERDUTY_KEY`)
    `SLACK_WEBHOOK_URL`Slack incoming webhook URL (for safety alert dispatch)
    `JIRA_BASE_URL`Jira instance URL
    `JIRA_EMAIL`Jira account email
    `JIRA_API_TOKEN`Jira API token
    `JIRA_PROJECT_KEY``SAFE`Jira project key for safety tickets
    Edit this page on GitHub