Configuration Reference

⚙️ Complete reference for all PiSovereign configuration options

This document covers every configuration option available in config.toml.

Table of Contents

• Overview
• Environment Settings
• Server Settings
• Inference Engine
• Security Settings
  • Prompt Security
  • API Key Authentication
• Memory & Knowledge Storage
• Database & Cache
  • Database
  • Cache
• Integrations
  • Messenger Selection
  • WhatsApp Business
  • Signal Messenger
  • Speech Processing
  • Weather
  • Web Search
  • Public Transit (ÖPNV)
  • Reminder System
  • CalDAV Calendar
  • Email (IMAP/SMTP)
• Model Selector
• Telemetry
• Resilience
  • Degraded Mode
  • Retry Configuration
• Health Checks
• Event Bus
• Agentic Mode
• Vault Integration
• Environment Variables
• Example Configurations

Overview

PiSovereign uses a layered configuration system:

1. Default values - Built into the application
2. Configuration file - config.toml in the working directory
3. Environment variables - Override config file values (prefix: PISOVEREIGN_)

Configuration File Location

The application loads config.toml from the current working directory:

# Default location (relative to working directory)
./config.toml

Environment Variable Mapping

Config values can be overridden using environment variables:

[server]
port = 3000

# Becomes:
PISOVEREIGN_SERVER_PORT=3000

Nested values use double underscores:

[speech.local_stt]
threads = 4

# Becomes:
PISOVEREIGN_SPEECH_LOCAL_STT__THREADS=4

Environment Settings

# Application environment: "development" or "production"
# In production:
#   - JSON logging is enforced
#   - Security warnings block startup (unless PISOVEREIGN_ALLOW_INSECURE_CONFIG=true)
#   - TLS verification is enforced
environment = "development"

Server Settings

[server]
# Network interface to bind to
# "127.0.0.1" = localhost only (recommended for security)
# "0.0.0.0" = all interfaces (use behind reverse proxy)
host = "127.0.0.1"

# HTTP port
port = 3000

# Enable CORS (Cross-Origin Resource Sharing)
cors_enabled = true

# Allowed CORS origins
# Empty array = allow all (WARNING in production)
# Example: ["https://app.example.com", "https://admin.example.com"]
allowed_origins = []

# Graceful shutdown timeout (seconds)
# Time to wait for active requests to complete
shutdown_timeout_secs = 30

# Log format: "json" or "text"
# In production mode, defaults to "json" even if set to "text"
log_format = "text"

# Secure session cookies (requires HTTPS)
# Set to false for local HTTP development
secure_cookies = false

# Maximum request body size for JSON payloads (optional, bytes)
# max_body_size_json_bytes = 1048576  # 1MB

# Maximum request body size for audio uploads (optional, bytes)
# max_body_size_audio_bytes = 10485760  # 10MB

Inference Engine

[inference]
# Ollama-compatible server URL
# Works with both hailo-ollama (Raspberry Pi) and standard Ollama (macOS)
base_url = "http://localhost:11434"

# Default model for inference
default_model = "qwen2.5:1.5b"

# Request timeout (milliseconds)
timeout_ms = 60000

# Maximum tokens to generate
max_tokens = 2048

# Sampling temperature (0.0 = deterministic, 2.0 = creative)
temperature = 0.7

# Top-p (nucleus) sampling (0.0-1.0)
top_p = 0.9

# System prompt (optional)
# system_prompt = "You are a helpful AI assistant."

Security Settings

[security]
# Whitelisted phone numbers for WhatsApp
# Empty = allow all, Example: ["+491234567890", "+491234567891"]
whitelisted_phones = []

# API Keys (hashed with Argon2id)
# Generate hashed keys using: pisovereign-cli hash-api-key <your-key>
# Migrate existing plaintext keys: pisovereign-cli migrate-keys --input config.toml --dry-run
#
# [[security.api_keys]]
# hash = "$argon2id$v=19$m=19456,t=2,p=1$..."
# user_id = "550e8400-e29b-41d4-a716-446655440000"
#
# [[security.api_keys]]
# hash = "$argon2id$v=19$m=19456,t=2,p=1$..."
# user_id = "6ba7b810-9dad-11d1-80b4-00c04fd430c8"

# Trusted reverse proxies (IP addresses) - optional
# Add your proxy IPs here if behind a reverse proxy
# trusted_proxies = ["127.0.0.1", "::1"]

# Rate limiting
rate_limit_enabled = true
rate_limit_rpm = 120  # Requests per minute per IP

# TLS settings for outbound connections
tls_verify_certs = true
connection_timeout_secs = 30
min_tls_version = "1.2"  # "1.2" or "1.3"

Prompt Security

Protects against prompt injection and other AI security threats.

[prompt_security]
# Enable prompt security analysis
enabled = true

# Sensitivity level: "low", "medium", or "high"
# - low: Only block high-confidence threats
# - medium: Block medium and high confidence threats (recommended)
# - high: Block all detected threats including low confidence
sensitivity = "medium"

# Block requests when security threats are detected
block_on_detection = true

# Maximum violations before auto-blocking an IP
max_violations_before_block = 3

# Time window for counting violations (seconds)
violation_window_secs = 3600  # 1 hour

# How long to block an IP after exceeding max violations (seconds)
block_duration_secs = 86400  # 24 hours

# Immediately block IPs that send critical-level threats
auto_block_on_critical = true

# Custom patterns to detect (in addition to built-in patterns) - optional
# custom_patterns = ["DROP TABLE", "eval("]

API Key Authentication

API keys are now securely hashed using Argon2id. Use the CLI tools to generate and migrate keys.

Generate a new hashed key:

pisovereign-cli hash-api-key <your-api-key>

Migrate existing plaintext keys:

pisovereign-cli migrate-keys --input config.toml --dry-run
pisovereign-cli migrate-keys --input config.toml --output config-new.toml

Configuration:

[[security.api_keys]]
hash = "$argon2id$v=19$m=19456,t=2,p=1$..."
user_id = "550e8400-e29b-41d4-a716-446655440000"

Usage:

curl -H "Authorization: Bearer <your-api-key>" http://localhost:3000/v1/chat

Memory & Knowledge Storage

Persistent AI memory for RAG-based context retrieval. Stores interactions, facts, preferences, and corrections using embeddings for semantic similarity search.

[memory]
# Enable memory storage (default: true)
# enabled = true

# Enable RAG context retrieval (default: true)
# enable_rag = true

# Enable automatic learning from interactions (default: true)
# enable_learning = true

# Number of memories to retrieve for RAG context (default: 5)
# rag_limit = 5

# Minimum similarity threshold for RAG retrieval (0.0-1.0, default: 0.5)
# rag_threshold = 0.5

# Similarity threshold for memory deduplication (0.0-1.0, default: 0.85)
# merge_threshold = 0.85

# Minimum importance score to keep memories (default: 0.1)
# min_importance = 0.1

# Decay factor for memory importance over time (default: 0.95)
# decay_factor = 0.95

# Enable content encryption (default: true)
# enable_encryption = true

# Path to encryption key file (generated if not exists)
# encryption_key_path = "memory_encryption.key"

[memory.embedding]
# Embedding model name (default: nomic-embed-text)
# model = "nomic-embed-text"

# Embedding dimension (default: 384 for nomic-embed-text)
# dimension = 384

# Request timeout in milliseconds (default: 30000)
# timeout_ms = 30000

Embedding Settings:

Database & Cache

Database

[database]
# SQLite database file path
path = "pisovereign.db"

# Connection pool size
max_connections = 5

# Auto-run migrations on startup
run_migrations = true

Cache

PiSovereign uses a 3-layer caching architecture:

1. L1 (Moka) - In-memory cache for fastest access
2. L2 (Redb) - Persistent disk cache for exact-match lookups
3. L3 (Semantic) - pgvector-based similarity cache for semantically equivalent queries

[cache]
# Enable caching (disable for debugging)
enabled = true

# TTL values (seconds)
ttl_short_secs = 300       # 5 minutes - frequently changing
ttl_medium_secs = 3600     # 1 hour - moderately stable
ttl_long_secs = 86400      # 24 hours - stable data

# LLM response caching
ttl_llm_dynamic_secs = 3600   # Dynamic content (briefings)
ttl_llm_stable_secs = 86400   # Stable content (help text)

# L1 (in-memory) cache size
l1_max_entries = 10000

Semantic Cache

The semantic cache provides an additional layer that matches queries based on embedding similarity rather than exact string matching. This enables cache hits for semantically equivalent queries like:

• “What’s the weather?” ≈ “How’s the weather today?”
• “Tell me about the capital of France” ≈ “What is Paris?”

[cache.semantic]
# Enable semantic caching
enabled = true

# Minimum cosine similarity for cache hit (0.0-1.0)
# Higher = stricter matching, lower = more cache hits
similarity_threshold = 0.92

# TTL for cached entries (hours)
ttl_hours = 48

# Maximum cached entries
max_entries = 10000

# Patterns that bypass semantic cache (time-sensitive queries)
bypass_patterns = ["weather", "time", "date", "today", "tomorrow", "now", "latest", "current", "recent"]

# How often to evict expired entries (minutes)
eviction_interval_minutes = 60

Integrations

Messenger Selection

PiSovereign supports one messenger at a time:

# Choose one: "whatsapp", "signal", or "none"
messenger = "whatsapp"

WhatsApp Business

[whatsapp]
# Meta Graph API access token (store in Vault)
# access_token = "your-access-token"

# Phone number ID from WhatsApp Business
# phone_number_id = "your-phone-number-id"

# App secret for webhook signature verification
# app_secret = "your-app-secret"

# Verify token for webhook setup
# verify_token = "your-verify-token"

# Require webhook signature verification
signature_required = true

# Meta Graph API version
api_version = "v18.0"

# Phone numbers allowed to send messages (empty = allow all)
# whitelist = ["+1234567890"]

# Conversation Persistence Settings
[whatsapp.persistence]
# Enable conversation persistence (default: true)
# enabled = true

# Enable encryption for stored messages (default: true)
# enable_encryption = true

# Enable RAG context retrieval from memory system (default: true)
# enable_rag = true

# Enable automatic learning from interactions (default: true)
# enable_learning = true

# Maximum days to retain conversations (optional, unlimited if not set)
# retention_days = 90

# Maximum messages per conversation before FIFO truncation (optional)
# max_messages_per_conversation = 1000

# Number of recent messages to use as context (default: 50)
# context_window = 50

Persistence Options:

Signal Messenger

[signal]
# Your phone number registered with Signal (E.164 format)
phone_number = "+1234567890"

# Path to signal-cli JSON-RPC socket
socket_path = "/var/run/signal-cli/socket"

# Path to signal-cli data directory (optional)
# data_path = "/var/lib/signal-cli"

# Connection timeout in milliseconds
timeout_ms = 30000

# Phone numbers allowed to send messages (empty = allow all)
# whitelist = ["+1234567890", "+0987654321"]

# Conversation Persistence Settings
[signal.persistence]
# Enable conversation persistence (default: true)
# enabled = true

# Enable encryption for stored messages (default: true)
# enable_encryption = true

# Enable RAG context retrieval from memory system (default: true)
# enable_rag = true

# Enable automatic learning from interactions (default: true)
# enable_learning = true

# Maximum days to retain conversations (optional, unlimited if not set)
# retention_days = 90

# Maximum messages per conversation before FIFO truncation (optional)
# max_messages_per_conversation = 1000

# Number of recent messages to use as context (default: 50)
# context_window = 50

Persistence Options:

📖 See Signal Setup Guide for installation instructions.

Speech Processing

Voice message support for speech-to-text (STT) and text-to-speech (TTS).

Cloud Provider (OpenAI):

• Works on all platforms
• Requires API key

Local Provider (whisper.cpp + Piper):

• Raspberry Pi: Models in /usr/local/share/{whisper,piper}/
• macOS: Models in ~/Library/Application Support/{whisper,piper}/
• Install whisper.cpp: brew install whisper-cpp (Mac) or build from source (Pi)
• Install Piper: Download from https://github.com/rhasspy/piper/releases

[speech]
# Speech provider: "openai" (cloud) or "local" (whisper.cpp + Piper)
# provider = "openai"

# OpenAI API key for Whisper (STT) and TTS
# openai_api_key = "sk-..."

# OpenAI API base URL (for custom endpoints)
# openai_base_url = "https://api.openai.com/v1"

# Speech-to-text model (OpenAI Whisper)
# stt_model = "whisper-1"

# Text-to-speech model
# tts_model = "tts-1"

# Default TTS voice: alloy, echo, fable, onyx, nova, shimmer
# default_voice = "nova"

# Output audio format: opus, ogg, mp3, wav
# output_format = "opus"

# Request timeout in milliseconds
# timeout_ms = 60000

# Maximum audio duration in milliseconds (25 min for Whisper)
# max_audio_duration_ms = 1500000

# Response format preference: mirror, text, voice
# response_format = "mirror"

# TTS speaking speed (0.25 to 4.0)
# speed = 1.0

Weather

[weather]
# Open-Meteo API (free, no key required)
# base_url = "https://api.open-meteo.com/v1"

# Connection timeout in seconds
# timeout_secs = 30

# Number of forecast days (1-16)
# forecast_days = 7

# Cache TTL in minutes
# cache_ttl_minutes = 30

# Default location (when user has no profile)
# default_location = { latitude = 52.52, longitude = 13.405 }  # Berlin

CalDAV Calendar

[caldav]
# CalDAV server URL (Baïkal, Radicale, Nextcloud)
# server_url = "https://cal.example.com"
# When using Baïkal via Docker (setup --baikal):
# server_url = "http://baikal:80/dav.php"

# Authentication (store in Vault)
# username = "your-username"
# password = "your-password"

# Default calendar path (optional)
# calendar_path = "/calendars/user/default"

# TLS verification
# verify_certs = true

# Connection timeout in seconds
# timeout_secs = 30

Email (IMAP/SMTP)

PiSovereign supports any email provider that offers IMAP/SMTP access, including Gmail, Outlook, Proton Mail (via Bridge), and custom servers. Authentication is supported via password or OAuth2 (XOAUTH2).

Migration note: The config section was previously named [proton]. The old name still works (via a serde alias) but [email] is the canonical name going forward.

Quick setup with provider presets:

The easiest way to configure email is using the provider field, which automatically sets sensible defaults for IMAP/SMTP hosts and ports:

[email]
provider = "gmail"    # or "proton" or "custom"
email = "user@gmail.com"
password = "app-password"

Available providers:

Explicit imap_host, imap_port, smtp_host, smtp_port values always override provider presets.

Full configuration:

[email]
# Provider preset: "proton" (default), "gmail", or "custom"
# provider = "proton"

# IMAP server host (overrides provider preset)
# imap_host = "imap.gmail.com"       # Gmail
# imap_host = "outlook.office365.com" # Outlook
# imap_host = "127.0.0.1"            # Proton Bridge

# IMAP server port (993 for TLS, 1143 for Proton Bridge STARTTLS)
# imap_port = 993

# SMTP server host
# smtp_host = "smtp.gmail.com"       # Gmail
# smtp_host = "smtp.office365.com"   # Outlook
# smtp_host = "127.0.0.1"           # Proton Bridge

# SMTP server port (465 for TLS, 587 for STARTTLS, 1025 for Proton Bridge)
# smtp_port = 465

# Email address
# email = "user@gmail.com"

# Authentication: password or OAuth2
# For password-based auth (app passwords, Bridge passwords):
# password = "app-password"

# For OAuth2 (Gmail, Outlook):
# [email.auth]
# type = "oauth2"
# access_token = "ya29.your-token"

# TLS configuration
[email.tls]
# Verify TLS certificates (set false for self-signed certs like Proton Bridge)
# verify_certificates = true

# Minimum TLS version
# min_tls_version = "1.2"

# Custom CA certificate path (optional)
# ca_cert_path = "/path/to/ca.pem"

Provider-specific examples:

[email]
provider = "gmail"
email = "user@gmail.com"
# Use an App Password (not your Google account password)
# Generate at: https://myaccount.google.com/apppasswords
password = "xxxx xxxx xxxx xxxx"

[email]
provider = "custom"
imap_host = "outlook.office365.com"
imap_port = 993
smtp_host = "smtp.office365.com"
smtp_port = 587
email = "user@outlook.com"
password = "your-app-password"

[email]
provider = "proton"  # default — uses Bridge at 127.0.0.1
email = "user@proton.me"
# Use the Bridge password (from Bridge UI), NOT your Proton account password
password = "bridge-password"

[email.tls]
verify_certificates = false  # Bridge uses self-signed certs

Web Search

[websearch]
# Brave Search API key (required for primary provider)
# Get your key at: https://brave.com/search/api/
# api_key = "BSA-your-brave-api-key"

# Maximum results per search query (default: 5)
max_results = 5

# Request timeout in seconds (default: 30)
timeout_secs = 30

# Enable DuckDuckGo fallback if Brave fails (default: true)
fallback_enabled = true

# Safe search: "off", "moderate", "strict" (default: "moderate")
safe_search = "moderate"

# Country code for localized results (e.g., "US", "DE", "GB")
country = "DE"

# Language code for results (e.g., "en", "de", "fr")
language = "de"

# Rate limit: requests per minute (default: 60)
rate_limit_rpm = 60

# Cache TTL in minutes (default: 30)
cache_ttl_minutes = 30

Security Note: Store the Brave API key in Vault rather than config.toml:

vault kv put secret/pisovereign/websearch brave_api_key="BSA-..."

Public Transit (ÖPNV)

Provides public transit routing for German transport networks via transport.rest API. Used for “How do I get to X?” queries and location-based reminders.

[transit]
# Base URL for transport.rest API (default: v6.db.transport.rest)
# base_url = "https://v6.db.transport.rest"

# Request timeout in seconds
# timeout_secs = 10

# Maximum number of journey results
# max_results = 3

# Cache TTL in minutes
# cache_ttl_minutes = 5

# Include transit info in location-based reminders
# include_in_reminders = true

# Transport modes to include:
# products_bus = true
# products_suburban = true  # S-Bahn
# products_subway = true    # U-Bahn
# products_tram = true
# products_regional = true  # RB/RE
# products_national = false # ICE/IC

# User's home location for route calculations
# home_location = { latitude = 52.52, longitude = 13.405 }  # Berlin

Reminder System

Configures the proactive reminder system including CalDAV sync, custom reminders, and scheduling settings.

[reminder]
# Maximum number of snoozes per reminder
# max_snooze = 5

# Default snooze duration in minutes
# default_snooze_minutes = 15

# How far in advance to create reminders from CalDAV events (minutes)
# caldav_reminder_lead_time_minutes = 30

# Interval for checking due reminders (seconds)
# check_interval_secs = 60

# CalDAV sync interval (minutes)
# caldav_sync_interval_minutes = 15

# Morning briefing time (HH:MM format)
# morning_briefing_time = "07:00"

# Enable morning briefing
# morning_briefing_enabled = true

Model Selector (Deprecated)

Deprecated since v0.6.0: Use [model_routing] instead. See Adaptive Model Routing.

The old [model_selector] section with small_model / large_model is still accepted but will be removed in a future release.

Adaptive Model Routing

Routes requests to different LLM models based on complexity. See the dedicated Adaptive Model Routing page for full documentation.

[model_routing]
enabled = true

[model_routing.models]
trivial = "template"
simple = "gemma3:1b"
moderate = "gemma3:4b"
complex = "gemma3:12b"

Telemetry

[telemetry]
# Enable OpenTelemetry export
enabled = false

# OTLP endpoint (Tempo, Jaeger)
# otlp_endpoint = "http://localhost:4317"

# Sampling ratio (0.0-1.0, 1.0 = all traces)
# sample_ratio = 1.0

# Service name for traces
# service_name = "pisovereign"

# Log level filter (e.g., "info", "debug", "pisovereign=debug,tower_http=info")
# log_filter = "pisovereign=info,tower_http=info"

# Batch export timeout in seconds
# export_timeout_secs = 30

# Maximum batch size for trace export
# max_batch_size = 512

# Graceful fallback to console-only logging if OTLP collector is unavailable.
# When true (default), the application starts with console logging if the collector
# cannot be reached. Set to false to require a working collector in production.
# graceful_fallback = true

Resilience

Degraded Mode

[degraded_mode]
# Enable fallback when backend unavailable
enabled = true

# Message returned during degraded mode
unavailable_message = "I'm currently experiencing technical difficulties. Please try again in a moment."

# Cooldown before retrying primary backend (seconds)
retry_cooldown_secs = 30

# Number of failures before entering degraded mode
failure_threshold = 3

# Number of successes required to exit degraded mode
success_threshold = 2

Retry Configuration

Exponential backoff for retrying failed requests.

[retry]
# Initial delay before first retry in milliseconds
initial_delay_ms = 100

# Maximum delay between retries in milliseconds
max_delay_ms = 10000

# Multiplier for exponential backoff (delay = initial * multiplier^attempt)
multiplier = 2.0

# Maximum number of retry attempts
max_retries = 3

Formula: delay = min(initial_delay * multiplier^attempt, max_delay)

Health Checks

[health]
# Global timeout for all health checks in seconds
global_timeout_secs = 5

# Service-specific timeout overrides (uncomment to customize):
# inference_timeout_secs = 10
# email_timeout_secs = 5
# calendar_timeout_secs = 5
# weather_timeout_secs = 5

Event Bus

The in-process event bus decouples post-processing from the user-facing response path. When enabled, background handlers asynchronously handle fact extraction, audit logging, conversation persistence verification, and metrics collection — reducing perceived latency by 100–500 ms per request.

[events]
# Enable or disable the event bus (default: true)
enabled = true

# Broadcast channel buffer capacity (default: 1024)
# Increase if handlers can't keep up under high load.
channel_capacity = 1024

# Error handling policy: "log" or "retry" (default: "log", reserved for future use)
# handler_error_policy = "log"

# Retry settings (reserved for future use)
# max_retry_attempts = 3
# retry_delay_ms = 500

Background handlers spawned automatically:

Tip: Set enabled = false to disable all background processing and fall back to synchronous inline behavior.

Agentic Mode

Multi-agent orchestration for complex tasks. When enabled, the system decomposes complex user requests into parallel sub-tasks, each handled by an independent AI agent.

Note: Requires [agent.tool_calling] enabled = true to be set.

[agentic]
# Enable agentic mode (default: false)
enabled = false

# Maximum concurrent sub-agents running in parallel
max_concurrent_sub_agents = 4

# Maximum sub-agents spawned per task
max_sub_agents_per_task = 10

# Total timeout for the entire agentic task (minutes)
total_timeout_minutes = 30

# Timeout for each individual sub-agent (minutes)
sub_agent_timeout_minutes = 10

# Operations that require user approval before execution
# Example: ["send_email", "delete_contact", "execute_code"]
require_approval_for = []

Vault Integration

[vault]
# Vault server address
# address = "http://127.0.0.1:8200"

# AppRole authentication (recommended)
# role_id = "your-role-id"
# secret_id = "your-secret-id"

# Or token authentication
# token = "hvs.your-token"

# KV engine mount path
# mount_path = "secret"

# Request timeout in seconds
# timeout_secs = 5

# Vault Enterprise namespace (optional)
# namespace = "admin/pisovereign"

Environment Variables

All configuration options can be set via environment variables. Use __ (double underscore) as the nesting separator to avoid conflicts with field names containing underscores (e.g., phone_number):

Special variables:

Example Configurations

Development

environment = "development"

[server]
host = "127.0.0.1"
port = 3000
log_format = "text"

[inference]
base_url = "http://localhost:11434"
default_model = "qwen2.5:1.5b"

[database]
path = "./dev.db"

[cache]
enabled = false  # Disable for debugging

[security]
rate_limit_enabled = false
tls_verify_certs = false

Production

environment = "production"

[server]
host = "127.0.0.1"  # Behind reverse proxy
port = 3000
log_format = "json"
cors_enabled = true
allowed_origins = ["https://app.example.com"]

[inference]
base_url = "http://localhost:11434"
default_model = "qwen2.5:1.5b"
timeout_ms = 120000

[database]
path = "/var/lib/pisovereign/pisovereign.db"
max_connections = 10

[security]
rate_limit_enabled = true
rate_limit_rpm = 30
min_tls_version = "1.3"

[prompt_security]
enabled = true
sensitivity = "high"
block_on_detection = true

[vault]
address = "https://vault.internal:8200"
role_id = "..."
mount_path = "secret"

[telemetry]
enabled = true
otlp_endpoint = "http://tempo:4317"
sample_ratio = 0.1

Minimal (Quick Start)

environment = "development"

[server]
port = 3000

[inference]
base_url = "http://localhost:11434"
default_model = "qwen2.5:1.5b"

[database]
path = "pisovereign.db"