> ## Documentation Index > Fetch the complete documentation index at: https://docs.molesignal.com/llms.txt > Use this file to discover all available pages before exploring further. # Configuration > Configure the current single-crate service, ports, storage, workers, security, telemetry, and optional runtimes. Start MoleSignal with one TOML file: ```bash theme={null} molesignal --config /etc/molesignal/config.toml ``` Configuration is applied in this order, with later sources overriding earlier ones: 1. built-in Rust defaults; 2. the file passed through `--config`; 3. `MS_` environment variables. Structured environment names use a dot between sections: ```bash theme={null} env 'MS_HTTP.PORT=5081' \ 'MS_STORE.META.DSN=postgres://user:pass@db:5432/molesignal' \ molesignal --config /etc/molesignal/config.toml ``` The schema is defined under `src/config/`. The repository's maintained production-oriented sample is `conf/config.toml`; review the file when upgrading because newly added settings receive code defaults when absent. ## Secret-only values Keep these outside TOML when possible: | Environment variable | Purpose | | --------------------------------- | ---------------------------------------------------------------------------- | | `MS_AUTH_JWT_SECRET_OVERRIDE` | Pin bootstrap JWT signing material when required by deployment policy. | | `MS_CIPHER_KEY` | Root material for the organization cipher-key store. | | `MS_LICENSE_FILE` | Initial or disaster-fallback signed license package when explicitly enabled. | | `MS_SELF_TELEMETRY_CLUSTER_TOKEN` | Authenticate self-telemetry forwarding between split roles. | | `MS_AGENT_OPENAI_*` | Development fallback OpenAI key and base URL. | | `MS_AGENT_ANTHROPIC_*` | Development fallback Anthropic key and base URL. | | `MS_AGENT_COMPATIBLE_*` | Development fallback OpenAI-compatible key and base URL. | Production Mole Agent providers should normally be created in **Mole Agent → Agent settings**. Provider keys are encrypted, write-only, and resolved from PostgreSQL before the environment fallback. ## Node roles ```toml theme={null} [node] roles = ["standalone"] id = "" drain_timeout_secs = 30 ``` Choose from `standalone`, `router`, `intake`, `querier`, `compactor`, and `alert_manager`. `standalone` composes the complete service. An empty `id` is generated at startup. Shutdown waits up to `drain_timeout_secs` for pending intake data to flush. ## Network listeners | Default port | Section | Exposure | | ------------ | -------------- | -------------------------------------------------------------------- | | `5080` | `[http]` | Product HTTP API, UI proxy target, health, and metrics. | | `5082` | `[grpc]` | Trusted internal node, scan, and private intake protocols. | | `5083` | `[flight_sql]` | External authenticated Arrow Flight SQL; disabled by default. | | `4317` | `[otlp_grpc]` | External standard OTLP gRPC; enabled by default. | | `5084` | `[profiling]` | Node-local pprof diagnostics; disabled and loopback-only by default. | ### HTTP and TLS ```toml theme={null} [http] bind = "0.0.0.0" port = 5080 gzip = true external_url = "" [http.tls] enabled = false plain_port = 80 port = 443 acme_directory = "production" account_email = "" key_storage_dir = "/var/lib/molesignal/acme" issue_poll_secs = 60 renewal_retry_secs = 21600 ``` Set `external_url` to the public origin when a reverse proxy changes the host or scheme. Enabling TLS starts the ACME HTTP-01 listener and rustls SNI endpoint. ### Internal gRPC, Flight SQL, and OTLP ```toml theme={null} [grpc] bind = "0.0.0.0" port = 5082 max_message_size_mb = 32 [flight_sql] enabled = false bind = "0.0.0.0" port = 5083 default_lookback_hours = 24 max_message_size_mb = 32 [otlp_grpc] enabled = true bind = "0.0.0.0" port = 4317 max_message_size_mb = 32 ``` Do not expose `5082` to untrusted networks. External OTLP and Flight SQL require bearer authentication; terminate TLS before public exposure. ## Metadata and object storage Built-in development defaults use SQLite and the local filesystem. The repository sample uses PostgreSQL for metadata. ```toml theme={null} [store.meta] backend = "postgres" dsn = "postgres://molesignal:molesignal@db:5432/molesignal" max_connections = 16 [store.object] backend = "s3" root = "" bucket = "molesignal" region = "ap-southeast-1" endpoint = "" credentials_file = "/etc/molesignal/object-store.toml" multipart_threshold_mb = 32 multipart_part_size_mb = 8 range_threshold_mb = 16 range_chunk_mb = 8 max_concurrency = 8 op_timeout_secs = 30 health_probe_interval_secs = 30 [store.object.retry] max_attempts = 4 base_backoff_ms = 100 max_backoff_ms = 5000 jitter_ratio = 0.2 ``` Object backends are `local`, `s3`, `azure`, and `gcs`. Credential precedence is environment, credentials file, then inline TOML. Use shared object storage and PostgreSQL for multi-node deployments. ## Intake, WAL, query, and retention ```toml theme={null} [wal] dir = "./data/wal" segment_size_mb = 256 flush_strategy = "batch" sync_level = "data" batch_max_pending = 64 batch_max_delay_ms = 50 [intake] buffer_max_mb = 256 flush_interval_secs = 30 flush_parallelism = 4 [querier] concurrency = 0 max_scan_rows = 100000000 auto_async_threshold_rows = 50000000 estimate_throughput_per_sec = 1000 [compactor] interval_secs = 300 target_mb = 512 max_concurrent_groups = 4 retention_days = 30 downsample_after_days = 0 downsample_interval_secs = 3600 ``` `concurrency = 0` uses the available CPUs. A query estimate above `auto_async_threshold_rows` becomes an asynchronous search job; set the threshold to `0` to disable automatic conversion. Per-stream retention overrides the compactor default. ## Cluster and rate limits ```toml theme={null} [cluster] advertise_addr = "127.0.0.1:5082" heartbeat_interval_secs = 5 peer_timeout_secs = 15 [router.rate_limit] intake_qps = 1000 query_qps = 100 burst_multiplier = 2 ``` Set `advertise_addr` to an address reachable by every peer. A rate of `0` disables that limit. Remote cluster definitions and organization mappings are managed in the database, not this block. ## Alerts and email ```toml theme={null} [alert_manager] eval_interval_secs = 30 dispatch_interval_secs = 10 eval_timeout_secs = 10 default_ack_timeout_secs = 300 [notify.smtp] host = "" port = 587 username = "" password = "" from = "molesignal@example.com" tls = "starttls" timeout_secs = 10 ``` SMTP is enabled when `host` is non-empty. Slack, webhook channels, notification templates, schedules, and escalation policies are organization resources managed through the UI or API. ## Authentication and licenses ```toml theme={null} [auth] token_ttl_secs = 86400 issuer = "molesignal" root_email = "" root_password = "" [license] bootstrap_from_environment = false disaster_fallback_from_environment = false ``` JWT signing keys are persisted in PostgreSQL. The old `[auth].jwt_secret` setting is ignored and should be removed. License content is never embedded in TOML. The two license switches only control whether `MS_LICENSE_FILE` may seed an empty database or recover from a broken active version. ## Self-observability and profiling Process logs use `[telemetry]`. Tail sampling, protected `_sys` intake, external trace export, and the pprof listener use these nested sections: ```toml theme={null} [telemetry] log_level = "info" log_format = "text" log_output = "console" [telemetry.self_collect] enabled = false retention_days = 7 metrics_retention_days = 7 traces_retention_days = 7 profiles_retention_days = 7 metrics_enabled = true metrics_interval_secs = 15 queue_capacity = 8192 [telemetry.trace] enabled = true force_disabled = false filter = "info" deployment_environment = "production" normal_sample_ratio = 0.10 development_sample_ratio = 1.0 decision_window_secs = 30 [telemetry.trace.external] endpoint = "" protocol = "grpc" timeout_ms = 5000 queue_capacity = 8192 batch_size = 256 gzip = false allow_self_export = false [profiling] enabled = false bind = "127.0.0.1" port = 5084 allow_remote = false ``` The complete tail limits, slow thresholds, per-signal retention, exporter TLS, and profile schedule are shown in `conf/config.toml`. See [Self-observability](/en-US/self-observability) before changing these settings. ## Search jobs, cache, and cold metadata The following sections tune query admission and operational storage: * `[search.admission]` sets node and cluster concurrency by workgroup. * `[search] max_result_rows` guards unbounded non-aggregate results. * `[search.stream_agg_cache]` caches closed PromQL windows; `capacity = 0` disables the cache. * `[search_jobs]` controls worker count, idle polling, and cleanup. * `[cache.*]` sizes FileMeta, Parquet metadata, query-result, Tantivy, footer, and cold-dump caches. * `[cache.disk_cache] max_size_gb = 0` disables the local Parquet cache. * `[storage.file_meta_dump]` moves old FileMeta partitions to object storage. Use the canonical sample for the full cache keys and defaults. ## Functions, reports, and Agent ```toml theme={null} [functions] llm_eval_enabled = false [scheduled_reports.renderer] enabled = false base_url = "http://127.0.0.1:5173" concurrent_renders = 2 render_timeout_secs = 30 viewport_width = 1280 viewport_height = 800 [agent] enabled = false default_provider = "openai" ``` VRL is always available. JavaScript requires a build with `js-runtime` and has no separate runtime configuration switch. `llm_eval_enabled` permits per-event model evaluation in pipelines and can increase intake latency and cost. PDF and PNG reports require an enabled renderer and reachable Web `base_url`. `[agent].enabled` is a local development unlock. Production uses a signed `agent` entitlement plus IAM permissions. Model providers, prompts, tools, MCP servers, and approval policy are stored in PostgreSQL and managed in the product. ## Database-managed settings Do not add removed TOML sections for SSO or product policy. OIDC/SAML providers, signup and sharing policy, remote clusters, domains, cipher keys, model pricing, Agent settings, channels, and most other organization configuration are stored in PostgreSQL and changed through the UI or API.