Configuration

Start MoleSignal with one TOML file:

molesignal --config /etc/molesignal/config.toml

Configuration is applied in this order, with later sources overriding earlier ones:

built-in Rust defaults;
the file passed through --config;
MS_ environment variables.

Structured environment names use a dot between sections:

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

[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

[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

[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.

[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

[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

[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

[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 = "[email protected]"
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

[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:

[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 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

[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.

Getting Started

Observe

Reliability

AI Ops

Data

Collaboration

Admin

Deploy & Operate

Secret-only values

Node roles

Network listeners

HTTP and TLS

Internal gRPC, Flight SQL, and OTLP

Metadata and object storage

Intake, WAL, query, and retention

Cluster and rate limits

Alerts and email

Authentication and licenses

Self-observability and profiling

Search jobs, cache, and cold metadata

Functions, reports, and Agent

Database-managed settings

​Secret-only values

​Node roles

​Network listeners

​HTTP and TLS

​Internal gRPC, Flight SQL, and OTLP

​Metadata and object storage

​Intake, WAL, query, and retention

​Cluster and rate limits

​Alerts and email

​Authentication and licenses

​Self-observability and profiling

​Search jobs, cache, and cold metadata

​Functions, reports, and Agent

​Database-managed settings

Secret-only values

Node roles

Network listeners

HTTP and TLS

Internal gRPC, Flight SQL, and OTLP

Metadata and object storage

Intake, WAL, query, and retention

Cluster and rate limits

Alerts and email

Authentication and licenses

Self-observability and profiling

Search jobs, cache, and cold metadata

Functions, reports, and Agent

Database-managed settings