Configuration Management
Relevant source files
The following files were used as context for generating this wiki page:
Horizon employs a multi-tiered configuration management strategy designed for flexibility across development, testing, and production environments. The system prioritizes "Inference-First" logic and leverages a three-level hierarchy for settings: Runtime APIs, Environment Variables (prefixed with HORIZON_), and Configuration Files (supporting YAML, TOML, and JSON).
The management infrastructure ensures that core services—including the API server, cross-platform agents, and database layers—can be initialized with consistent parameters while maintaining strict security standards such as avoiding hardcoded secrets and enforcing encrypted credential storage.
Sources: IMPLEMENTATION_PLAN.md:104-106, IMPLEMENTATION_PLAN.md:650-655, AGENTS.md:145-150
Configuration Hierarchy and Data Flow
Horizon's configuration is resolved through a specific priority order. Runtime configurations provided via the API or database override environment variables, which in turn override static configuration files.
The diagram above illustrates how settings are layered, with higher layers taking precedence during the application bootstrap process.
Sources: IMPLEMENTATION_PLAN.md:104-106, IMPLEMENTATION_PLAN.md:650-655
Database Configuration
The system uses specific structures to manage connectivity to its primary data store (PostgreSQL). This configuration is primarily driven by environment variables during the CLI startup sequence.
Database Connection Parameters
The DatabaseConfig struct in the CLI crate aggregates the necessary fields to construct a valid PostgreSQL connection string.
| Parameter | Env Variable | Default Value | Description |
|---|---|---|---|
| Host | HORIZON_DATABASE_HOST | localhost | Database server address |
| Port | HORIZON_DATABASE_PORT | 5432 | TCP port for connection |
| Database | HORIZON_DATABASE_NAME | horizon | Target database name |
| Username | HORIZON_DATABASE_USER | horizon | Authentication user |
| Password | HORIZON_DATABASE_PASSWORD | (Empty) | User password |
| SSL Mode | HORIZON_DATABASE_SSL_MODE | require | SSL negotiation mode |
| Pool Size | HORIZON_DATABASE_POOL_SIZE | 10 | Max connection pool size |
Sources: crates/cli/src/main.rs:24-52, docker-compose.yml:13-17
Connection String Assembly
The system dynamically builds the connection URL using the build_database_url function, following the format: postgres://username:password@host:port/database?sslmode=mode.
Sources: crates/cli/src/main.rs:55-62
Logging Infrastructure Configuration
Horizon utilizes a structured logging subsystem based on tracing. It supports multiple output formats and levels, configurable via the LoggingConfig struct.
Configuration Options
The logging system distinguishes between development and production needs through different "subscribers."
The diagram shows the logic within the logging crate that determines how logs are formatted and where they are dispatched.
Sources: crates/logging/src/config.rs:60-70, crates/logging/src/config.rs:73-100
Logging Variables
| Option | Env Variable | Allowed Values |
|---|---|---|
| Level | RUST_LOG | debug, info, warn, error |
| Format | HORIZON_LOG_FORMAT | json, pretty, compact |
| Log File | HORIZON_LOG_FILE | String (Path to file) |
| Environment | HORIZON_ENV | development, testing, production |
Sources: crates/logging/src/config.rs:16-35, crates/cli/src/main.rs:71-80
Infrastructure and Container Configuration
For development and deployment, Horizon uses Docker Compose to manage its dependencies. These configurations are designed to align with the application's internal expectations for service discovery.
Service Orchestration
The docker-compose.yml file defines the environment for the core services, ensuring they share a common network and persistent storage.
This diagram represents the relationship between the containerized infrastructure and the application layer.
Sources: docker-compose.yml:7-80, scripts/docker-dev.sh:111-125
Development Scripting
A dedicated utility script, scripts/docker-dev.sh, manages the lifecycle of the development environment, including directory setup for volumes (.docker/volumes/postgres) and environment file (.env) validation.
Sources: scripts/docker-dev.sh:56-65, scripts/docker-dev.sh:162-180
Security Configuration Management
Horizon strictly prohibits hardcoded secrets. Instead, it utilizes a sophisticated security framework for handling sensitive configuration data:
- Credential Storage: Sensitive credentials (like API keys for AI providers) are stored with encryption at rest using ChaCha20-Poly1305.
- Memory Safety: The system uses the
zeroizecrate to clear sensitive configuration data from memory after use. - Inference Provider Config: AI providers (OpenAI, Anthropic, etc.) are configured via an abstraction layer that allows for dynamic model selection and prompt template management.
- mTLS: Communication between agents and the server is configured via server-issued certificates and Ed25519 signing.
Sources: IMPLEMENTATION_PLAN.md:85-95, IMPLEMENTATION_PLAN.md:658-662, AGENTS.md:145-150
Summary
Horizon's configuration management system provides a robust framework for handling application state across diverse environments. By combining standard Rust patterns (struct-based config), industry-standard serialization (Serde/Figment), and strict security protocols (RustCrypto), the system achieves a balance between ease of deployment and enterprise-grade security. The reliance on environment variables and structured logging ensures that Horizon remains observable and configurable in containerized contexts.