config.yaml
One file says everything lanowl does. A new install has a short one, written by lanowl at its
first start, and the dashboard's gear changes it: Settings shows every
section as a form, from config.example.yaml, and keeps the file's comments. Or copy
config.example.yaml to config/config.yaml and edit it: the essentials come first, and
every optional feature starts switched off — except devwatch, which reads the devices'
ports and logs with the logins you give lanowl.
- No secrets here. Logins, tokens and lanowl's ssh key live in
secrets.yaml, so this file can be shared or kept in git. - Relative paths (the database, the log, the outbox) land in
/state, the container's volume. - Four settings can come from the environment instead, so one file serves several
machines:
LANOWL_MODEL_URL(model.url),LANOWL_HOST_IP(observer.host_ip),LANOWL_WEB_PORT(web.port) andTZ(timezone). The environment wins. - Changes need a restart (
docker compose restart lanowl), exceptsecrets.yaml, which is read again when it changes. lanowl --checkreads this file the way a start does, and says what is wrong.
The values below are the example's. Where leaving a key out gives something different, the last section says so.
network
network:
description: |
A home LAN 192.168.88.0/24 behind a MikroTik router (192.168.88.1), one fibre line to the
internet. IoT devices share the main LAN on purpose. Guests use their own Wi-Fi.
A few sentences about your network, in your own words. Every prompt the model reads includes them, marked as context, not instructions. Say what no inventory says: the links, the sites, what runs where, what matters, and what you chose on purpose (so the owl does not report it).
timezone
timezone: "Europe/Berlin"
Sunrise and sunset, the morning jobs and the router's log timestamps are read in it. The
first-run setup writes it from your browser. TZ in the environment wins; neither set, UTC.
model
The local model: where Ollama is, which model, and how it speaks. See The model.
telegram
telegram:
chat_id: "" # your chat with the bot
outbox_file: "tg_outbox.json" # what could not be sent during an outage
chat:
enabled: true # answer questions and /commands
allowed_chat_ids: [] # only these chats are answered (empty: chat_id)
poll_timeout_s: 50
answer_max_wall_s: 600 # the longest an answer may take
max_iters: 16 # the most tool calls in one answer
telegram.chat.allowed_user_ids lists who may press Approve and Reject; needed only when the
chat is a group. See Telegram.
webhook
webhook:
enabled: false # also send alerts to an HTTP address (works without Telegram)
format: "generic" # generic, apprise, ntfy, or template
template: {} # format template: your JSON, with {title} {message} ... in it
events: [down, recovery, wan, security, new_device, logs, diagnosis, proposal] # also: digest, maintenance, other
min_severity: "info"
headers: {} # extra headers that are not secret
verify_tls: true # false for a gateway with a self-signed certificate
queue_file: "webhook_queue.json" # what could not be delivered yet, tried again
Every alert also as a JSON POST to an address of your own. The address goes in secrets.yaml
(tokens.webhook_url, or LANOWL_WEBHOOK_URL), a bearer token beside it if the receiver wants
one. See Webhook.
web
web:
enabled: true
host: "0.0.0.0"
port: 80 # or LANOWL_WEB_PORT
allowed_hosts: []
password_hash: ""
login: true
The dashboard. It is closed until you log in with its password: password_hash, written by
the dashboard's first page (after the setup code) or made by lanowl --hash-password, or,
when that is empty, the one set with /password on Telegram. With neither, it asks for the
setup code. login: false switches the login off, for a
dashboard behind a login of your own. More: Logging in.
It answers on any address of the host. By default it accepts requests only
when the browser reached it by an IP address: that is what stops a hostile web page from
borrowing a DNS name that points at your network (DNS rebinding). To open it by name
(lanowl.lan, or behind a reverse proxy), list the names in allowed_hosts.
cadence
cadence:
sweep_interval_s: 60 # every device probed once a minute
debounce_fails: 2 # misses in a row before a device is down
recovery_oks: 1 # answers in a row before it is up again
llm_mode: "interval" # the owl's audit: "interval" or "times"
llm_interval_s: 3600
llm_times: ["08:00", "13:00", "20:00"]
llm_on_incident: true # a new critical: the owl diagnoses it at once
llm_incident_cooldown_s: 600
llm_when_unchanged: false # false: skip a scheduled audit when nothing changed
llm_max_wall_s: 900 # an audit is abandoned after this
digest_when_ok: false # no digest when there is nothing to say
The sweep and the model run on separate clocks: an audit never delays a sweep. With
llm_mode: times, the audit runs at the listed times instead of every llm_interval_s.
A scheduled audit is skipped when nothing the owl would be told has changed since the last
completed one (the issues, the devices down, asleep or paused, the internet, a new device, a
log finding, a waiting proposal) and that one is under a day old, so at least one full audit
runs every 24 hours. The digest's rules, the daily reminder included, run as if the audit had
found nothing new. "Audit now" and an incident always run one. llm_when_unchanged: true runs
every scheduled audit.
A device can carry its own debounce_fails in the inventory (a site behind a tunnel wants
more patience).
alerts
alerts:
recovery_confirm_s: 900 # clear this long before "RECOVERED"
cooldown_s: 3600 # the same problem stays quiet this long after it recovers
renotify_after_s: 0 # re-page a problem that never clears (0 = never)
digest_repeat_s: 86400 # re-state a still-open problem once a day
notify_recovery: true
recovery_min_severity: "info"
How these decide what reaches you: How alerts work.
probes
probes:
concurrency: 32
icmp_timeout_ms: 1500
tcp_timeout_ms: 1500
http_timeout_ms: 4000
snmp_timeout_s: 2
snmp_community: "public"
Defaults for every check. A check in the inventory can carry its own timeout_ms (and
count for ping), for a device on weak Wi-Fi.
wan
wan:
targets: ["8.8.8.8", "208.67.222.222", "1.0.0.1"]
watch:
enabled: true
interval_s: 15 # its own ping loop, faster than the sweep
fail_checks: 2
ok_checks: 1
min_outage_s: 90 # shorter blackouts are counted, not paged
state_messages: true
log_interval_s: 60
flap_hold_s: 60
flap_severity: "critical"
log_down_match: ""
log_up_match: ""
routine: []
log_triage: {enabled: true, cooldown_s: 900, timeout_s: 90, max_lines: 40,
notify_severities: ["critical", "warning"]}
path:
route_comment: ""
main: "main link"
backup: "backup link"
The internet is up when any of targets answers. Pick neutral public addresses from
different providers. The watcher's loop runs every 15 seconds: a blackout is confirmed in
about 30 seconds, and one shorter than min_outage_s is counted in the digest instead of
paging you.
path, log_down_match, log_up_match, routine and standby are for a second internet
line and a MikroTik's log: A backup internet line. log_triage lets the
owl read router-log lines that no rule explains.
mikrotik
The main router's REST address, its read-only login, and the kept API connection. See Your router.
discovery
discovery:
notify_new_devices: true # a Telegram line when a never-seen device joins
notify_address_changes: true # ...when DHCP moves a watched device
new_window_h: 24 # "new" on the dashboard for this long
guest_nets: [] # e.g. ["192.168.89.0/24"]: marked as guests
ignore_macs: []
ignore_ips: []
What the router's DHCP holds and nobody watches (needs a MikroTik). A watched device that
DHCP moves to another address is followed by its MAC (mac: in the inventory, or learned
from the lease). ignore_macs does by hand what the dashboard's Known button does.
sites
sites:
dhcp_every_min: 30
scan: {enabled: true, at: "05:00", seconds: 30}
list:
- {key: home, name: "Home", nets: ["192.168.88.0/24"]}
The networks lanowl looks after. home is the main one. See Remote sites.
site
site:
lat: 48.0 # rough is fine
lon: 11.0
sun_margin_min: 60
day_margin_min: 45
offline_grace_min: 30
Where the network is, for sunrise and sunset: a device with expect_offline: sun (solar
gear) is asleep from sunset to sunrise, widened by sun_margin_min; one with
expect_offline: day (a dusk-to-dawn light) the other way round, by day_margin_min. One
that dozes off a little early, or wakes late, stays asleep for offline_grace_min before it
counts as down. Without lat and lon, expect_offline does nothing.
observer
observer:
enabled: true
host_ip: "" # or LANOWL_HOST_IP; empty: the address it reaches the internet from
gateway_ip: "" # default: the router in mikrotik.dhcp_source
min_down_pct: 60
min_groups: 3
lanowl's own host. Everything is probed from one machine, so if that machine loses the
network, every device looks down. When the gateway is unreachable, at least min_down_pct
of the devices are down, and they span at least min_groups groups, lanowl sends one alert
saying it has probably lost the network itself, instead of forty.
mqtt
mqtt:
host: "" # empty: MQTT off
port: 1883
tls: false
credentials: "mqtt" # its login in secrets.yaml, if the broker wants one
base_topic: "lanowl"
subscribe: [] # e.g. ["shellies/#"]: last values the owl can read
See MQTT topics.
weekly
weekly: {enabled: true, day: "sun", time: "10:00"}
The week in review: the numbers, and the owl's note on top. The first one waits until lanowl
has watched for six days (/week asks for one at any time).
state and logging
state:
db_path: "lanowl_state.sqlite"
history_days: 30
logging:
level: "INFO"
file: "lanowl.log"
Both under /state. With logging.file set, docker logs stays empty: read the file
instead. See Logs and lanowl's own state.
The optional features
Each is off until you switch it on, and each acts only on the devices whose manage list
names it (Devices). lanowl --check shows the plan. One exception: devwatch
is on unless you switch it off, and reads the Ethernet ports of every device lanowl has a login
for, with no manage needed (its logs only with manage: [logs]).
| Section | What it does | Where it is explained |
|---|---|---|
profiles |
Device kinds of your own (default: config/profiles/) |
Profiles |
access |
Where secrets.yaml is, known hosts, Home Assistant's address |
Secrets |
actions |
What the owl may propose, and you approve | Actions |
devwatch |
Every device's Ethernet ports and its own log, hourly (on in the example) | Device kinds |
hostlog |
Linux auth logs, every two minutes, by lanowl's key | Security |
updates, cves |
Waiting updates every morning, a monthly scan | Security |
exposure |
The owl's daily review of what each machine exposes | Security |
drift, configwatch |
The owl's looks at what is slowly changing, and at config changes | Security |
fixes, scorecard |
A written fix for each finding; each diagnosis graded afterwards | Asking the owl |
backups |
Monthly backups of your machines onto a disk of yours | Security |
shell |
The owl's sandboxed shell | The model |
self_update
self_update:
check: true # ask GitHub once a day for lanowl's latest release (and on Check now)
auto: false # true: update by itself at `at` when a newer release is out (needs the updater)
at: "04:00" # an automatic update starts within two hours after this time
check: false makes lanowl ask GitHub nothing at all. auto needs the optional updater
container (Upgrading); what Settings shows and does
with them is in Settings.
Leaving a key out
A key left out of the file takes lanowl's own default. For most keys that is the example's value. These differ:
| Key | Left out |
|---|---|
web.enabled |
false: no dashboard |
web.port |
8088 |
telegram.chat.enabled |
false: questions and commands are not read |
weekly.enabled |
false |
discovery.notify_new_devices |
false |
model.num_ctx |
16384 |
model.keep_alive |
0: the model is unloaded after each call |
model.request_timeout_s |
240 |
model.max_tool_iters |
6 |
cadence.llm_max_wall_s |
600 |
telegram.chat.answer_max_wall_s |
420 |
probes.icmp_timeout_ms |
1000 |
Edit this page on GitHub.