Expand description
Configuration types and loaders for Zeph.
This crate contains configuration struct and enum definitions, the TOML loader,
environment variable overrides, validation, and migration helpers.
Vault secret resolution is handled in zeph-core through the SecretResolver trait.
§TODO (D4 — deferred: typed config presets)
This crate currently has 131 config structs across 30 files (~19K LOC). Many subsystem configs duplicate the same optional/default patterns and there is no compile-time guarantee that a feature’s config section is consistent with its runtime behaviour.
Planned: typed preset newtype wrappers (e.g., MemoryConfig<Minimal>, MemoryConfig<Full>)
so callers can use a named preset instead of setting 20+ individual fields, avoiding silent
config drift when new fields are added.
Blocked by: requires a clear preset taxonomy and a backwards-compatible TOML migration strategy. Must be a standalone epic with its own SDD spec. Do NOT bundle with other refactors.
§Loading configuration
use std::path::Path;
use zeph_config::Config;
// Load from file (falls back to defaults when the file does not exist)
let config = Config::load(Path::new("/etc/zeph/config.toml"))
.expect("failed to load config");
// Validate numeric bounds and cross-references
config.validate().expect("config validation failed");
println!("Agent name: {}", config.agent.name);
println!("History limit: {}", config.memory.history_limit);§Environment variable overrides
After loading from TOML, Config::load automatically applies env-var overrides.
Key variables:
| Variable | Field overridden |
|---|---|
ZEPH_LLM_PROVIDER | llm.providers[0].provider_type |
ZEPH_LLM_MODEL | llm.providers[0].model |
ZEPH_SQLITE_PATH | memory.sqlite_path |
ZEPH_QDRANT_URL | memory.qdrant_url |
The Qdrant API key is vault-only (not an env-var override):
zeph vault set ZEPH_QDRANT_API_KEY "<key>" → memory.qdrant_api_key.
§Config migration
Use migrate::ConfigMigrator to upgrade existing TOML configs with newly-added
parameters added as commented-out entries:
use zeph_config::migrate::ConfigMigrator;
let user_toml = std::fs::read_to_string("config.toml").unwrap();
let migrator = ConfigMigrator::new();
let result = migrator.migrate(&user_toml).expect("migration failed");
println!("Added {} new parameters", result.changed_count);
std::fs::write("config.toml", &result.output).unwrap();Re-exports§
pub use agent::AgentConfig;pub use agent::ContextInjectionMode;pub use agent::FocusConfig;pub use agent::ModelSpec;pub use agent::SubAgentConfig;pub use agent::SubAgentLifecycleHooks;pub use agent::TaskSupervisorConfig;pub use agent::ToolFilterConfig;pub use channels::A2aServerConfig;pub use channels::ChannelSkillsConfig;pub use channels::DiscordConfig;pub use channels::IbctKeyConfig;pub use channels::McpConfig;pub use channels::McpOAuthConfig;pub use channels::McpPolicy;pub use channels::McpServerConfig;pub use channels::McpTrustLevel;pub use channels::OAuthTokenStorage;pub use channels::RateLimit;pub use channels::SlackConfig;pub use channels::TelegramConfig;pub use channels::ToolDiscoveryConfig;pub use channels::ToolDiscoveryStrategyConfig;pub use channels::ToolPruningConfig;pub use channels::TrustCalibrationConfig;pub use channels::is_skill_allowed;pub use cli::CliConfig;pub use cli::LoopConfig;pub use defaults::DEFAULT_DEBUG_DIR;pub use defaults::DEFAULT_LOG_FILE;pub use defaults::DEFAULT_SKILLS_DIR;pub use defaults::DEFAULT_SQLITE_PATH;pub use defaults::default_debug_dir;pub use defaults::default_integrity_registry_path;pub use defaults::default_log_file_path;pub use defaults::default_skills_dir;pub use defaults::default_sqlite_path;pub use defaults::is_legacy_default_debug_dir;pub use defaults::is_legacy_default_log_file;pub use defaults::is_legacy_default_skills_path;pub use defaults::is_legacy_default_sqlite_path;pub use dump_format::DumpFormat;pub use experiment::AdaptOrchConfig;pub use experiment::ExperimentConfig;pub use experiment::ExperimentSchedule;pub use experiment::OrchestrationConfig;pub use experiment::PlanCacheConfig;pub use features::CompressionSpectrumConfig;pub use features::CostConfig;pub use features::DaemonConfig;pub use features::DebugConfig;pub use features::GatewayConfig;pub use features::IndexConfig;pub use features::ProactiveExplorationConfig;pub use features::ScheduledTaskConfig;pub use features::ScheduledTaskKind;pub use features::SchedulerConfig;pub use features::SchedulerDaemonConfig;pub use features::SkillEvaluationConfig;pub use features::SkillMiningConfig;pub use features::SkillPromptMode;pub use features::SkillsConfig;pub use features::TraceConfig;pub use features::VaultConfig;pub use hooks::FileChangedConfig;pub use hooks::HooksConfig;pub use learning::DetectorMode;pub use learning::LearningConfig;pub use logging::LogRotation;pub use logging::LoggingConfig;pub use mcp_security::CapabilityClass;pub use mcp_security::DataSensitivity;pub use mcp_security::FlaggedParameter;pub use mcp_security::ToolSecurityMeta;pub use memory::AdmissionConfig;pub use memory::AdmissionStrategy;pub use memory::AdmissionWeights;pub use memory::AutoDreamConfig;pub use memory::BeliefRevisionConfig;pub use memory::CategoryConfig;pub use memory::CompressionConfig;pub use memory::CompressionStrategy;pub use memory::ContextFormat;pub use memory::ContextStrategy;pub use memory::DigestConfig;pub use memory::DocumentConfig;pub use memory::ForgettingConfig;pub use memory::GraphConfig;pub use memory::HebbianConfig;pub use memory::MagicDocsConfig;pub use memory::MemoryConfig;pub use memory::MicrocompactConfig;pub use memory::NoteLinkingConfig;pub use memory::PersonaConfig;pub use memory::PruningStrategy;pub use memory::ReasoningConfig;pub use memory::RetrievalConfig;pub use memory::RpeConfig;pub use memory::SemanticConfig;pub use memory::SessionsConfig;pub use memory::SidequestConfig;pub use memory::StoreRoutingConfig;pub use memory::StoreRoutingStrategy;pub use memory::TierConfig;pub use memory::TrajectoryConfig;pub use memory::TreeConfig;pub use memory::VectorBackend;pub use metrics::MetricsConfig;pub use notifications::NotificationsConfig;pub use providers::BanditConfig;pub use providers::CacheTtl;pub use providers::CandleConfig;pub use providers::CandleInlineConfig;pub use providers::CascadeClassifierMode;pub use providers::CascadeConfig;pub use providers::CoeConfig;pub use providers::ComplexityRoutingConfig;pub use providers::GeminiThinkingLevel;pub use providers::GenerationParams;pub use providers::LlmConfig;pub use providers::LlmRoutingStrategy;pub use providers::MAX_TOKENS_CAP;pub use providers::ProviderEntry;pub use providers::ProviderKind;pub use providers::ProviderName;pub use providers::RouterConfig;pub use providers::RouterStrategyConfig;pub use providers::SttConfig;pub use providers::ThinkingConfig;pub use providers::ThinkingEffort;pub use providers::TierMapping;pub use providers::validate_pool;pub use providers::default_stt_language;pub use providers::default_stt_provider;pub use quality::QualityConfig;pub use quality::TriggerPolicy;pub use rate_limit::RateLimitConfig;pub use sanitizer::CausalIpiConfig;pub use sanitizer::ContentIsolationConfig;pub use sanitizer::CustomPiiPattern;pub use sanitizer::EmbeddingGuardConfig;pub use sanitizer::ExfiltrationGuardConfig;pub use sanitizer::MemoryWriteValidationConfig;pub use sanitizer::PiiFilterConfig;pub use sanitizer::QuarantineConfig;pub use sanitizer::ResponseVerificationConfig;pub use sanitizer::GuardrailAction;pub use sanitizer::GuardrailConfig;pub use sanitizer::GuardrailFailStrategy;pub use security::ScannerConfig;pub use security::SecurityConfig;pub use security::TimeoutConfig;pub use security::TrustConfig;pub use session::RecapConfig;pub use session::SessionConfig;pub use subagent::HookAction;pub use subagent::HookDef;pub use subagent::HookMatcher;pub use subagent::MemoryScope;pub use subagent::PermissionMode;pub use subagent::SkillFilter;pub use subagent::SubagentHooks;pub use subagent::ToolPolicy;pub use telemetry::TelemetryBackend;pub use telemetry::TelemetryConfig;pub use ui::AcpAuthMethod;pub use ui::AcpConfig;pub use ui::AcpLspConfig;pub use ui::AcpSubagentsConfig;pub use ui::AcpTransport;pub use ui::AdditionalDir;pub use ui::AdditionalDirError;pub use ui::SubagentPresetConfig;pub use ui::TuiConfig;pub use ui::DiagnosticSeverity;pub use ui::DiagnosticsConfig;pub use ui::HoverConfig;pub use ui::LspConfig;pub use vigil::VigilConfig;pub use classifiers::ClassifiersConfig;pub use classifiers::InjectionEnforcementMode;pub use error::ConfigError;pub use root::Config;pub use root::ResolvedSecrets;
Modules§
- agent
- channels
- classifiers
- cli
- Session-scoped CLI configuration: bare mode, JSON output, and auto-approval flags.
- defaults
- dump_
format - error
- experiment
- features
- hooks
- learning
- logging
- mcp_
security - Pure-data security types for MCP tool metadata.
- memory
- metrics
- Prometheus metrics export configuration (
[metrics]TOML section). - migrate
- Config migration: add missing parameters from the canonical reference as commented-out entries.
- notifications
- Configuration for the per-turn completion notification subsystem.
- providers
- quality
- Configuration for the MARCH self-check quality pipeline.
- rate_
limit - root
- sanitizer
- security
- session
- Session-scoped user experience settings (#3064).
- subagent
- telemetry
- tools
- Pure-data tool configuration types.
- ui
- vigil
- VIGIL (Verify-Before-Commit Intent Gate) configuration.