Configuration

Configuration

Almost everything is configured from ⚙ Settings in the UI. Under the hood it's stored in data/config.yaml. For Docker, environment variables can override the file (handy for AI setup).

• Database + settings: data/boltarr.db and data/config.yaml (keep the ./data volume).
• Precedence: environment variables override config.yaml when set.

---

Sample config.yaml

You normally don't hand-edit this — the UI writes it — but here's the full structure with every option, using generic values:

# General
general:
  timezone: "Etc/UTC"          # IANA name, e.g. "Europe/London", "America/New_York".
                               # Drives schedule times, quiet hours, the digest, and displayed times.

# AI assistant (optional — leave provider: none to disable)
llm:
  provider: none               # none | ollama | openai | anthropic
  base_url: ""                 # ollama: http://ollama-host:11434 · openai-compatible: https://api.openai.com/v1
  api_key: ""                  # openai / anthropic only
  model: ""                    # e.g. llama3.2 · gpt-4o · claude-haiku-4-5-20251001
  timeout: 120                 # seconds, standard requests
  long_timeout: 600            # seconds, long jobs (e.g. full network analysis)

# Notifications via ntfy (https://ntfy.sh or self-hosted)
notifications:
  enabled: false
  server: "https://ntfy.sh"    # your ntfy server
  topic: "my-boltarr-topic"    # the topic you subscribe to in the ntfy app
  token: ""                    # optional access token if your ntfy needs a login

# Service monitor + global alert timing
monitoring:
  alert_after_minutes: 5       # a service must be down this long before a down-alert fires (0 = immediate)
  quiet_enabled: false         # mute alerts during a window (local time)
  quiet_start: "22:00"
  quiet_end: "07:00"
  suppress_when_host_down: true  # when a host is offline, hold its services' down-alerts (one host alert instead of many)

# Public status page push (one-way, over your LAN)
statuspage:
  enabled: false
  url: "http://status-box-ip:12102"   # the separate status app
  token: ""                            # shared secret (also set in the status app's .env)

# Host liveness (the ping tier)
liveness:
  enabled: true
  interval_minutes: 3          # how often to sweep
  offline_after: 3             # consecutive missed sweeps before a host is "offline"

# Change tracking — what each scan records to the Changes feed
change_tracking:
  enabled: true
  host_new: true
  port_opened: true
  port_closed: true
  mac_changed: true
  hostname_changed: true
  host_offline: true
  host_online: true
  retention_days: 90           # how long to keep change history

# Change alerts — which recorded changes push to ntfy
change_alerts:
  enabled: true
  scope: static                # static | dynamic | all  (unknown-classified hosts never alert)
  host_new: true
  port_opened: true
  port_closed: false
  mac_changed: false
  hostname_changed: false
  host_offline: true
  host_online: true
  include_mac: false           # attach the device MAC to alerts (handy for roaming devices)
  on_scan: true                # send a summary after each scan
  digest_enabled: true         # daily morning digest
  digest_time: "08:00"

⚠️ config.yaml holds your tokens and API keys. Treat backups of it as sensitive.

---

Environment variables (Docker)

Set these in the environment: block of your compose file to override config.yaml — most useful for AI, so you don't type keys into the UI:

Variable	Example	Notes
LLM_PROVIDER	ollama	none | ollama | openai | anthropic
LLM_BASE_URL	http://ollama-host:11434	for ollama / openai-compatible
LLM_API_KEY	sk-…	openai / anthropic
LLM_MODEL	llama3.2	default model
LLM_TIMEOUT / LLM_LONG_TIMEOUT	120 / 600	seconds
NTFY_ENABLED	true
NTFY_SERVER / NTFY_TOPIC / NTFY_TOKEN	https://ntfy.sh / my-topic / —	notifications
MONITOR_ALERT_MINUTES	5	service-down grace
MONITOR_QUIET_ENABLED / MONITOR_QUIET_START / MONITOR_QUIET_END	true / 22:00 / 07:00	quiet hours
STATUSPAGE_ENABLED / STATUSPAGE_URL / STATUSPAGE_TOKEN	true / http://…:12102 / —	status page push

Example:

    environment:
      LLM_PROVIDER: ollama
      LLM_BASE_URL: http://ollama-host:11434
      LLM_MODEL: llama3.2

---

Backup, restore & factory reset

• Backup / Restore — sidebar buttons (bottom-left). Backup downloads a ZIP of boltarr.db + config.yaml. After a restore, restart Boltarr (e.g. docker restart boltarr) so it re-opens the restored database.
• Factory reset — Settings → 🗄 Data → ↺ Factory reset. Wipes all network data; tick Keep settings to preserve ntfy/status-page/timezone/AI, or untick for a full reset. Type DELETE to confirm.