Settings

Most settings belong to one environment. They live in the database of that environment, and the Data tab of the Settings page writes them. The key names below are the names in the database, so a support answer and a log line agree with this page.

Key	Meaning	Default
retention_days	Days to keep telemetry before cleanup.	7
log_required_attributes	The attribute keys every log record must carry, comma separated. Blank means Loggerhead works the shape out from your logs. The Log shape drift rule on the Rules tab of the Linting page edits it.	unset
lint_rule_<id>	The rule settings of an older version, per environment. The app copies them into the workspace file once. See below.	unset
ingest_require_auth	Require a bearer token on ingest that does not come from loopback.	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 settings of the Mac

The AI settings belong to the whole Mac, as the AI key in the keychain does. Every workspace and every environment uses them, and a switch to another environment does not change them. Loggerhead keeps them in its own preferences, by the key names below. The AI tab of the Settings page writes them.

Key	Meaning	Default
ai_provider	apple (Apple Intelligence on this Mac), none, anthropic (an Anthropic-compatible API), or openai (an OpenAI-compatible API). The old value ollama works as openai.	apple
ai_model	Model name for the provider. The OpenAI-compatible type has no default, so it needs a value.	Provider default
ai_base_url	The base URL of the cloud API, for example https://openrouter.ai/api/v1. It must use https, or http on localhost. See Set up an AI provider.	Default URL of the API type
ai_custom_masks	The masks you add on the AI tab, as a JSON array of {"name", "pattern"} objects. Before a cloud model gets a sample of your telemetry, each match becomes <name>.	unset

Older versions kept the AI settings in the database of each environment. The first start of a newer version copies the AI settings of the environment that opens first, one time.

Appearance (system, light, or dark) also belongs to the Mac. It is not a database setting.

The lint rules

The lint rule settings belong to the workspace, not to one environment. They are in lint-settings.json in the workspace folder, workspaces/<workspace>/lint-settings.json. The file has one entry per rule that is not at its defaults, under rules, by the rule id from Tune the rules:

{"rules":{"noisy_logs":{"enabled":false,"overrides":{"noisyLogRatio":0.4,"minLogVolume":250}}}}

Field	Meaning
enabled	false when the user switched the rule off. The rule then skips every scan.
overrides	The threshold values the user changed, by config field name. A field that is absent keeps its default. A share is a number between 0 and 1, a duration is a number of seconds, and a list is a JSON array of strings.

The file also holds exceptions, ignores, and changes: the exceptions of each rule, the findings the workspace ignores, and the last 200 changes with their source (mcp or ui), time, reason, and the value before and after, which Undo reads.

An entry with an unknown rule id, or an override on a field the rule does not read, is ignored and reported as a warning on the Rules tab of the Linting page. A file that does not parse is kept as lint-settings.json.bad, and the rules run with their defaults.

Before the settings moved to the workspace, each environment’s database kept one row per rule, lint_rule_<id>, with the same JSON value. The first time the app opens a workspace with no settings file, it copies the rows of the open environment into the file.

The MCP tool list_lint_rules reads the settings and reports the value in force next to the default. The MCP tools set_lint_rule_enabled, set_lint_threshold, reset_lint_threshold, add_lint_exception, remove_lint_exception, ignore_finding, and unignore_finding change them, with a reason. See the Tools reference.

The log shape

log_required_attributes drives the Log records miss a field check. It kept its own key when the lint rules moved to their page, so an older setting still works. Type the attribute keys every record must carry, separated by commas, in the Required fields threshold of the Log shape drift rule on the Rules tab of the Linting page:

service.name,env,request.id

The app accepts at most 32 keys of at most 128 characters each. The rule saves the list in the workspace file, and log_required_attributes applies only while the workspace sets no list. Leave the field blank and Loggerhead infers the shape of each message instead: a key that 90% or more of the records of one message carry counts as part of that message’s shape, and the records that miss it are the drift. The numbers and ids in a message do not count, so Batch 3 of 15 complete and Batch 4 of 15 complete are one message. See What it checks.

The AI masks

ai_custom_masks holds the masks that you add in Settings › AI › Masks for cloud models, as a JSON array:

[{"name":"account","pattern":"ACC-\\d{8}"}]

Before a cloud model gets the telemetry, each match of pattern becomes <name>. Your masks apply before the built-in masks, which are not stored. A name is 1 to 32 characters: lower-case letters, digits, _, or -. A pattern is a regular expression of at most 500 characters, and it must not match an empty text. The app keeps at most 20 masks. See What it checks.

The AI key

The AI provider key is not a setting. The app stores it in the macOS Keychain, and it never enters the database or a log line. Add it on the Settings › AI tab. AI analysis is a Pro feature.

The receiver ports

The receiver prefers 4317 for gRPC and 4318 for HTTP. When another program holds a port, the app moves along a fixed ladder and shows the port in use on the Collectors page. See Ports and the effective port.