Settings

Settings live in the engine’s database. The app writes them from the Settings page. Scripts write them with PUT /api/settings. A stored value wins over an environment variable, which wins over the default.

Key	Meaning	Default
retention_days	Days to keep telemetry before cleanup.	7
theme	system, light, or dark.	system
ai_provider	none, anthropic, openai, or ollama.	none
ai_model	Model name for the provider.	Provider default
ingest_require_auth	Require a bearer token on non-loopback ingest.	false
ingest_token	The accepted bearer token.	unset
ingest_tls_cert_file	PEM certificate for the receiver.	unset
ingest_tls_key_file	PEM key for the receiver.	unset

The AI key

The AI provider key is not a setting. The app stores it in the macOS Keychain and hands it to the engine over PUT /api/settings/ai-key. GET reports whether a key is set. DELETE clears it. The API never returns the key.

Environment variables

These apply to an engine you start yourself. The app sets what it needs.

Variable	Meaning
LOGGERHEAD_DB_PATH	Database file path. Wins over DATA_DIR.
DATA_DIR	Data directory. The file is DATA_DIR/loggerhead.db.
OTLP_GRPC_PORT, OTLP_HTTP_PORT	Preferred receiver ports. Default 14317 and 14318.
LOGGERHEAD_OTLP_AUTOPORT	Walk the port ladder when a port is busy. The app sets it.
LOGGERHEAD_OTLP_BIND_HOST	Bind host for the receiver. Default 127.0.0.1.
HTTP_API_PORT	Pin the API port. A busy pinned port is an error.