Skip to content

Configuration reference

Every configuration field of the daemon, generated from the same field list that GET /api/v1/config/schema serves and the English help texts the Web UI shows beneath each field. How the layers combine, which environment variables override which key, and how secrets are stored is explained in Configuration.

  • Key — the dotted YAML path. centrals.* keys belong to one entry of the centrals: list.
  • Type — the Go type the value decodes into; *bool is a tri-state switch (true, false or unset).
  • Default — the explicit default the schema carries for fields whose zero value would mislead. An empty cell means the schema carries none.
  • Class — basic, expert or secret; secret values are masked in GET /api/v1/config.
  • Restart — yes when a change only takes effect after a restart.

Fields edited through dedicated surfaces (the bootstrap listener, users and API tokens, navigation profiles) are not part of this list.

addon_update

Key Type Default Class Restart Description
addon_update.check_interval time.Duration expert yes How often the daemon checks GitHub for a new add-on release in the background, plus a random jitter of up to 1 hour so a fleet doesn't poll all at once. Zero falls back to the default of 24 h; use the enabled toggle to turn background checking off.
addon_update.enabled *bool expert yes Check GitHub for new add-on releases in the background (boot check plus the recurring interval); default on. The manual "Check for updates" button and installing stay available when disabled.
addon_update.include_prereleases bool expert no Also offer pre-releases (beta versions, tagged X.Y.Z-beta.N) as add-on updates; default off, final releases only. Takes effect at the next check without a restart. A final release is offered either way once it is newer than an installed beta.

alarm

Key Type Default Class Restart Description
alarm.default_siren_seconds int 180 basic yes Default acoustic activation duration in seconds, used when an alarm output does not configure its own siren duration.
alarm.duress_visibility string expert yes Where a duress-code use or a silent panic trigger may appear. 'hidden' reaches the webhook and nothing else — with no webhook configured, nobody is told at all. 'notify_only' (default) additionally sends the notification event, so a phone is reached, but never writes it to retained state or the local screens. 'full' treats it like any other alarm. The threat is not an insecure Home Assistant — it is that whoever stands next to you sees the same screen. Whether Home Assistant shows the notification as a lock-screen banner is outside this setting; use a notify channel without preview if that matters.
alarm.enabled *bool basic yes Master switch for the alarm engine. With no zones configured yet the engine stays inert either way. Takes effect after a daemon restart.
alarm.journal_retention_days int 90 basic yes How many days alarm-journal entries are kept before being pruned. Zero disables retention (entries are kept forever).
alarm.max_acoustic_per_incident_seconds int 900 expert yes Cumulative acoustic budget in seconds for one incident across all re-triggers and restarts, so a stuck sensor cannot sound a siren indefinitely.
alarm.restart_loop_breaker int 3 expert yes Caps how many times a restore-driven output may re-fire within one incident before the engine degrades to optical signalling and notifications only.
alarm.stop_verify_seconds int 120 expert yes How long, in seconds, an unverified siren-stop command is retried before it is escalated to a health incident.

backup

Key Type Default Class Restart Description
backup.dir string expert yes Where downloaded CCU archives are stored. Empty means <data directory>/backups. On a CCU add-on install the data directory sits inside the tree the CCU backs up itself, so pointing this at external storage keeps the CCU's own backups from growing with every archive. Takes effect after a daemon restart.
backup.keep_last int expert yes Bounds how many scheduled backups are retained per CCU: after each successful backup the oldest beyond this count are deleted. Zero keeps all.
backup.schedule time.Duration expert yes How often each configured CCU is backed up automatically (e.g. 24h). Zero disables scheduled backups; manual backups via the Backups view still work. The first automatic backup runs one interval after start, not immediately.

callback

Key Type Default Class Restart Description
callback.bin_port int expert yes BIN-RPC callback listener port (CUxD). 0 resolves to the 8129 default, not an OS-assigned port — unlike the XML-RPC port above, this listener has no port-range escape valve, so two daemons on one host each need an explicit, distinct value here.
callback.host string expert yes Local interface the XML-RPC + BIN-RPC callback listeners bind to. Lock down via firewall, not via bind address.
callback.max_connections int expert yes Cap on simultaneous connections per callback listener (XML-RPC and BIN-RPC). Bounds memory/goroutine use if an untrusted LAN host floods the socket. 0 uses the default (64).
callback.port int expert yes XML-RPC callback listener port. 0 lets the OS pick an ephemeral port; the daemon re-advertises it on every CCU reconnect.
callback.port_range string expert yes Optional port range <lo>-<hi>; the callback listener binds the first free port in it. Takes precedence over the XML-RPC port above. Use when the daemon sits behind a narrow firewall range.
callback.public_host string expert yes Hostname the daemon announces to the CCU in every init() call. Set when running behind NAT.
callback.restrict_source_ips bool expert yes Only accept callbacks from the configured CCU IPs plus loopback. Adds a source-IP allowlist on top of the connection cap. Off by default; enable when no legitimate host other than your CCUs reaches the callback ports.

ccu_data

Key Type Default Class Restart Description
ccu_data.easymode_path string expert yes Filesystem path to the OCCU easymode ZIP. Defaults to the embedded archive; override only when testing a custom extract.
ccu_data.translations_path string expert yes Filesystem path to the OCCU translations ZIP. Defaults to the embedded archive bundled with the binary; override only when testing a custom extract.

centrals

Key Type Default Class Restart Description
centrals []config.CentralConfig basic yes All configured CCUs. Manage them in the dedicated CCUs tab — entries set here in config.yaml act as bootstrap seeds.
centrals.api_token string secret no The occulited API token (olt_…) an openccu-lite system is accessed with. Managed in the CCUs tab.
centrals.api_token_file string expert no Path of a file holding the API token, read on every request — rotation-safe for the add-on token occulited mints at each start, and for container secret mounts. Mutually exclusive with a stored token.
centrals.behavior.delay_new_device_creation *bool basic no Hold a newly-paired device until you accept it under New devices (it is then built and can be named and configured) and release it (it then reaches MQTT / Home Assistant, Matter and webhooks). Devices already known are never held. Switching it off publishes new devices immediately under their factory name. Default: on.
centrals.behavior.enable_device_firmware_check *bool expert no Surface a firmware-update entity for every device that reports available firmware; default true.
centrals.behavior.enable_program_scan *bool expert no Fetch CCU programs and expose them as hub entities; disable to skip program discovery entirely (default true).
centrals.behavior.enable_sysvar_scan *bool expert no Fetch CCU system variables and expose them as hub entities; disable to skip sysvar discovery entirely (default true).
centrals.behavior.include_internal_programs *bool expert no Include CCU-internal programs (those not intended for user control) in the hub entity surface; default false.
centrals.behavior.include_internal_sysvars *bool expert no Include CCU-internal system variables in the hub entity surface; default true.
centrals.behavior.light_last_brightness *bool expert no When turning a light on, restore the last non-zero brightness the CCU reported rather than switching to full (100%); default true.
centrals.behavior.program_markers []hmenum.DescriptionMarker expert no Tokens the CCU description of a program may carry. As for system variables, markers decide only how a program arrives, not whether it is imported: marker-matched programs arrive enabled in Home Assistant, everything else disabled. HX is a free marker for your own filtering, and INTERNAL additionally includes the CCU's internal programs — which matters because the CCU flags most ordinary programs as internal. HAHM has no effect here; it makes system variables writable and programs have no value to write. Empty: everything is imported, everything disabled.
centrals.behavior.sysvar_markers []hmenum.DescriptionMarker expert no Tokens the CCU description of a system variable may carry. Markers do not decide whether a variable is imported — everything is imported — only how it arrives: marker-matched variables arrive enabled in Home Assistant, everything else arrives disabled for you to switch on per entity. HAHM makes a variable writable (switch, select, number, text instead of a read-only sensor). HX is a free marker for your own filtering. INTERNAL additionally includes the CCU's internal variables. Empty: everything is imported, everything disabled.
centrals.behavior.sysvar_scan_interval time.Duration expert no How often the daemon refreshes system variables from the CCU. Zero uses the compiled-in default of 30 seconds; below 3 seconds is rejected, because each cycle costs the CCU a script run on a single-threaded interpreter.
centrals.behavior.use_group_channel_for_cover_state *bool expert no Report a cover's position from its group-channel LEVEL rather than from its own channel; default true.
centrals.check_connection_interval time.Duration expert no How often the daemon pings the CCU in the background; zero uses the compiled-in default of 30 s, negative disables the check entirely.
centrals.host string basic no Managed in the CCUs tab.
centrals.interfaces []config.InterfaceSpec basic no Managed in the CCUs tab.
centrals.interfaces.name string basic no Managed in the CCUs tab.
centrals.interfaces.port int expert no Managed in the CCUs tab.
centrals.interfaces.remote_path string expert no URL path this interface's XML-RPC requests are sent to. Leave empty for the CCU default (/RPC2, or /groups for VirtualDevices); set an absolute path only when a reverse proxy re-routes the interface.
centrals.interfaces.rpc_type string expert no Transport of this interface. It follows the interface name — CUxD speaks BIN-RPC, every other interface XML-RPC — so this only confirms that derivation; a contradicting value is rejected when the configuration is loaded.
centrals.json_rpc_port int expert no Port of the system's web server (JSON-RPC on a CCU, the occulited API on openccu-lite); 0 means 80 or 443. Managed in the CCUs tab.
centrals.name string basic no Managed in the CCUs tab.
centrals.password string secret no Managed in the CCUs tab.
centrals.port int expert no Managed in the CCUs tab.
centrals.ports map[string]int expert no Managed in the CCUs tab.
centrals.primary_interface string expert no Managed in the CCUs tab.
centrals.system_type hmenum.SystemType basic no ccu for a CCU, OpenCCU or RaspberryMatic; openccu-lite for a system managed by occulited; auto detects it on first connect. Managed in the CCUs tab.
centrals.tls bool basic no Managed in the CCUs tab.
centrals.tls_fingerprint string expert no SHA-256 of an openccu-lite system's certificate; when set, exactly this certificate is trusted. Managed in the CCUs tab.
centrals.tls_insecure_skip_verify bool expert no Managed in the CCUs tab.
centrals.username string basic no Managed in the CCUs tab.
centrals.visibility.un_ignore []string expert no Managed in the CCUs tab.

data_dir

Key Type Default Class Restart Description
data_dir string basic yes Root for SQLite database, sessions, backups, logs. Must be writable; created on first start.

locale

Key Type Default Class Restart Description
locale string basic yes Default UI language for the very first SPA load. Operators can flip per-user via the Settings tab.

logging

Key Type Default Class Restart Description
logging.format string basic yes Handler shape. json for production / log shippers; text or text-color for terminal output.
logging.level string basic yes Filter threshold for the structured logger. debug exposes wire-level traces; info is the typical operator level.
logging.overrides map[string]string expert yes Per-subsystem level overrides keyed by dot-separated logger path. The most specific override wins.

north.discovery

Key Type Default Class Restart Description
north.discovery.mdns.enabled *bool true basic yes Advertise the daemon's REST listener via mDNS / Zeroconf so LAN clients (e.g. Home Assistant) can auto-discover it.
north.discovery.mdns.instance_name string basic yes Leftmost label of the mDNS SRV / TXT record. Empty falls back to the OS hostname.
north.discovery.ssdp.enabled *bool basic yes Periodically scan the LAN for Homematic / OpenCCU central units via SSDP/UPnP so they can be adopted with one click. Read-only — no data about the daemon leaves the LAN.
north.discovery.ssdp.interval time.Duration basic yes How often the discovery scan re-runs (e.g. 60s). Empty falls back to 60 seconds.

north.matter

Key Type Default Class Restart Description
north.matter.attestation.cd_path string expert yes Filesystem path to the CSA-signed Certification Declaration (a CMS / PKCS#7 message). The CD pins the vendor + product as a certified Matter device.
north.matter.attestation.dac_key_path string secret yes Filesystem path to the DAC's P-256 private key (PEM or DER, PKCS#8 or SEC1). MUST match the public key embedded in the DAC certificate; on a mismatch the bridge refuses new pairings.
north.matter.attestation.dac_path string expert yes Filesystem path to the vendor-supplied Device Attestation Certificate (PEM or DER). With all four attestation paths empty the bridge serves the CSA test chain (test PAA → PAI → DAC) for the configured vendor and product, which Apple Home, Google Home and chip-tool accept but which must not ship. Once any path is set, all four files must load and the key must match the DAC — otherwise the bridge keeps serving the controllers already paired but refuses every new pairing until the files are fixed and the daemon restarts.
north.matter.attestation.pai_path string expert yes Filesystem path to the Product Attestation Intermediate certificate. Provided by the CSA along with the DAC.
north.matter.case.fabric_id uint64 expert yes No effect: the fabric id is the one the commissioner's NOC carries. Kept for compatibility with existing configs.
north.matter.case.node_id uint64 expert yes No effect: the operational node id is the one each commissioner assigns in the NOC it installs, persisted per fabric. Kept for compatibility with existing configs.
north.matter.commissioning.concurrent_pairings bool expert yes No effect since the bridge runs on go-fabric's node facade: the PASE adapter is isolated per exchange always, so multiple commissioners can pair in parallel. Kept for compatibility with existing configs.
north.matter.commissioning.ephemeral_window bool basic yes Generate a fresh discriminator + passcode + verifier each time the SPA opens a commissioning window. Recommended for production: pairing codes auto-rotate and the static configured passcode acts only as the long-lived label-code fallback.
north.matter.commissioning.iterations int 1000 expert yes PBKDF2 iteration count (1000..100000 per Spec §3.10). Default 1000. Higher = more CPU at pairing time, harder to brute-force a captured transcript.
north.matter.commissioning.passcode uint32 secret yes 27-bit Matter setup code (Spec §5.1.6.4) — between 00000001 and 99999998. Required to accept commissioner pairings; 0 leaves the PASE acceptor dormant.
north.matter.commissioning.salt string secret yes PBKDF2 salt persisted with the passcode (16–32 bytes per Spec §3.10). Empty falls back to a fixed development salt — never ship the default to production.
north.matter.controller_profile string expert yes Empty by default. Name the controller the bridge is paired with (alexa, apple-home, google-home, home-assistant, smartthings). A profile leaves out what that controller has been reproduced failing on and logs a warning for what was only reported. No profile leaves anything out yet; apple-home warns about thermostat week programs. Takes effect after a restart.
north.matter.dev_rotate_unique_ids bool expert yes Development-only: mix a per-boot 16-byte random salt into every bridged endpoint's Matter UniqueID. Apple Home / Google Home need a STABLE UniqueID across restarts to recognise accessories — leave this off in production.
north.matter.discriminator uint16 3840 expert yes 12-bit Matter commissioning discriminator. Combined with the passcode to form the manual setup code.
north.matter.enable_time_sync *bool expert yes Mount the optional TimeSynchronization cluster (0x0038) on the Matter Root endpoint. Off by default — it is optional-only on a RootNode and some controllers (e.g. Apple Home) may reject the bridge at pairing when it appears. Enable only if a controller needs a time-sync surface, and re-pair afterwards.
north.matter.enabled bool basic yes Master switch for the Matter bridge. Off by default. When enabled the daemon stands up the UDP listener and mDNS records.
north.matter.expose_secondary_channels bool expert yes Off by default: a multi-channel device (switch, dimmer, cover, lock, siren, valve) projects a single Matter endpoint from its primary channel. Enable to also expose its secondary virtual-receiver actor channels as separate endpoints. Matter only — MQTT, HA-Discovery and REST always carry every channel.
north.matter.include_measurements bool expert yes Off by default: sensors the daemon calculates rather than reads — apparent temperature, dew point, dew-point spread, enthalpy, frost point, vapor concentration, operating-voltage level and derived binary state — are not sent to Matter. Enable to expose them as measurement endpoints alongside the device itself. The exposure list offers these data points either way, because it reports what the model can project; one you allowlisted while this was off starts appearing the moment you turn it on. Matter only — MQTT, HA-Discovery and REST always carry derived sensors.
north.matter.listen string :5540 expert yes UDP bind address for the Matter listener. :5540 is the IANA-assigned default; :0 lets the OS pick (useful in tests). Amazon Alexa can only commission bridges on port 5540.
north.matter.mdns_advertise string zeroconf expert yes mDNS advertiser implementation. Unset defaults to zeroconf, which publishes the operational + commissionable records on the network — required for pairing by QR code. noop keeps the records in-memory only (tests / out-of-band discovery); commissioners cannot discover the bridge in that mode.
north.matter.mdns_interfaces []string expert yes Empty by default: the bridge announces and answers mDNS on every multicast-capable interface. Name host interfaces (eth0, end0, …) to announce and answer on those alone, with their addresses — for a host on two networks behind an mDNS reflector, whose controllers would otherwise also cache the other network's address. Container bridges such as docker0 or hassio stay filtered even when named. A name the host does not have is accepted and shown as a finding on the Diagnostics tab of the Matter view. Takes effect after a restart.
north.matter.node_label string openccu-loom basic yes User-visible label for the bridge node, surfaced in commissioners (Apple Home, Google Home, …).
north.matter.prefer_ipv4 bool expert yes Force the Matter UDP socket to bind IPv4-only. Default false opens an IPv6 dual-stack socket that also accepts IPv4 traffic — the standard choice.
north.matter.product_id uint16 32768 expert yes Vendor-assigned product identifier. Defaults to 0x8000.
north.matter.spec_level string expert yes Empty by default: the bridge serves everything go-fabric supports. Set a Matter specification level (1.4, 1.4.1, 1.4.2, 1.5.1, 1.6.0, 1.6.1) to serve only what that level knows: optional features newer than the level are left out, and a device whose type the level does not know (for example a garage drive, a Closure since 1.5.1) is not exposed. Use it when your controller is known to work up to a level. Changing it changes what controllers see; Apple Home may need the bridge paired again. Takes effect after a restart.
north.matter.tcp string expert yes Matter TCP transport roles. off (default): UDP only. incoming: accept TCP connections on the Matter port. outgoing: open TCP connections to peers. both: incoming and outgoing. A controller that supports Matter TCP then moves large payloads (wildcard reads, OTA) off MRP onto the TCP connection.
north.matter.thermostat_hold_and_running_state bool expert yes Off by default. Enable to send two more things for every thermostat to Matter: whether it is heating right now, and whether it follows its week program (setpoint hold off = AUTO, on = manual; a controller can switch it). Experimental: Apple Home and Google Home are not verified with it. Switching it on or off can make Apple Home need the bridge paired again. Takes effect after a restart.
north.matter.thermostat_schedules bool expert yes Off by default. Enable to send every thermostat's week programs to Matter: a controller can read them, switch the active one and edit them, and an edit is written to the CCU. With this and the running state and hold on together, an Apple Home pairing has failed. Experimental: Apple Home and Google Home are not verified with it. Switching it on or off can make Apple Home need the bridge paired again. Takes effect after a restart.
north.matter.vendor_id uint16 65521 expert yes IANA-assigned vendor identifier. 0xFFF1 is the test / development vendor block — never ship that value to production.

north.mcp

Key Type Default Class Restart Description
north.mcp.allow_writes bool basic yes Enable write-capable MCP tools (e.g. set_datapoint). Off by default — the server alone is read-only; turn this on for agent-driven control. Takes effect after a daemon restart.
north.mcp.enabled bool basic yes Master switch for the MCP server, served over Streamable-HTTP on the REST listener. Off by default. Takes effect after a daemon restart.
north.mcp.path string /mcp expert yes HTTP mount path for the MCP transport on the REST listener. Empty defaults to /mcp. Takes effect after a daemon restart.

north.mqtt

Key Type Default Class Restart Description
north.mqtt.broker_url string basic no tcp://host:port (plain), tls://host:port (TLS), or mqtt:// / mqtts:// scheme aliases. Required when MQTT is enabled.
north.mqtt.client_id string basic no MQTT client identifier the daemon registers with. Must be unique per broker connection.
north.mqtt.discovery_bundles bool expert no Publish one retained document per device instead of one per entity. Your entities keep their IDs, history, areas and automations either way — Home Assistant keys them on the unique id, not on the topic. Switching this migrates every retained config on the broker, and switching it back migrates them again, so change it deliberately rather than in passing.
north.mqtt.discovery_enabled bool basic no Emit Home Assistant Discovery payloads so HA auto-registers the daemon's devices. Implies the raw plane — the payloads name its topics, so enabling this enables 'Publish raw plane' as well.
north.mqtt.discovery_retract_unscoped bool expert no One-time cleanup after the topic base became part of the discovery topic. Leave this OFF unless you are sure no other daemon on the DEFAULT topic base uses this broker: a leftover config looks exactly like the one such a daemon is publishing right now, so clearing it would delete that daemon's entities and device cards with no way back. If you are sure, switch it on, start once, then switch it off again.
north.mqtt.enabled bool basic no Master switch for the MQTT bridge. When off no broker connection is opened and no topics are emitted.
north.mqtt.maintenance.enabled *bool expert no Serve the mqtt-smarthome maintenance topics under <topic_base>/maintenance/: set the log level, restart the daemon (only when a supervisor restarts it) and publish process statistics. Anyone allowed to publish on the broker can use them — the broker's ACLs are the only gate, so switch this off on a broker you do not trust.
north.mqtt.maintenance.stats_interval_seconds *int expert no How often <topic_base>/maintenance/stats is republished, in seconds; empty means 60, 0 switches the statistics off.
north.mqtt.password string secret no Broker password — stored encrypted-at-rest by the OS, redacted from backups. Prefer setting via OPENCCU_LOOM_MQTT_PASSWORD env var.
north.mqtt.protocol_version string expert no MQTT wire dialect: "5" (default) or "3.1.1" for brokers without MQTT 5.0 support. No silent downgrade — a v5 connect against a v3-only broker fails with a named error.
north.mqtt.raw_enabled bool basic no Publish per-data-point state under <topic_base>/status/<central>/... — the raw topic plane non-HA consumers subscribe to. Discovery needs it: switching Discovery on turns this on too, since Discovery payloads only point at raw-plane topics.
north.mqtt.retain_cleanup_window_ms int expert no How long (in milliseconds) the daemon waits for the broker to deliver all retained messages before processing the retain-cleanup eviction list; zero falls back to 2000 ms.
north.mqtt.sub_devices_enabled bool basic no Split multi-channel-group devices into one HA device per channel group. Renders the parent + N children hierarchy in HA.
north.mqtt.tls_ca_file string expert no Absolute path of a PEM CA bundle the broker certificate is verified against instead of the system roots — for a broker whose certificate a private CA issued. Requires a tls://, ssl:// or mqtts:// broker URL; a missing or unusable file is refused on save.
north.mqtt.tls_insecure_skip_verify bool expert no Dangerous: do not verify the broker certificate at all, so anyone on the network path can impersonate the broker and read the credentials. Requires a TLS broker URL, cannot be combined with the CA file, and is logged as a warning. Prefer the CA file.
north.mqtt.topic_base string basic no Prefix every raw-plane and Discovery topic with this string. Change it when running multiple daemons against one broker.
north.mqtt.username string basic no Broker username for authenticated brokers. Leave empty for anonymous brokers.

north.rest

Key Type Default Class Restart Description
north.rest.auth.basic_enabled *bool true basic yes Accept HTTP Basic credentials on protected routes. Useful for curl + CI. Default on; set to false to reject Basic auth even when users are configured.
north.rest.auth.bearer_enabled *bool true basic yes Accept Bearer tokens via Authorization header. Use for automation. Default on; set to false to reject tokens even when they are configured.
north.rest.auth.ccu.central string basic yes Name of the configured central whose user database authenticates logins. Empty selects the first configured central.
north.rest.auth.ccu.enabled *bool basic yes Delegate login to the named CCU's user database. Users sign in with their CCU accounts; local users remain as a break-glass fallback. Restart required.
north.rest.auth.ccu.min_user_level int expert yes Reject CCU users below this UserLevel (8 admin, 2 operator, 1 guest; 0 is always denied). Default 1 admits any real user.
north.rest.auth.ccu.primary *bool basic yes When on, the CCU is tried first and local users are the break-glass fallback. Off makes local users primary and the CCU the last resort. Break-glass holds either way.
north.rest.auth.ccu.role_mapping map[string]string expert yes Override the default CCU UserLevel→Loom-role mapping. Keys are the UserLevel as a string ("8", "2", "1"); values are "admin" / "operator" / "viewer". Empty uses the defaults (≥8 admin, ≥2 operator, ≥1 viewer).
north.rest.auth.ha_ingress.enabled *bool basic yes Trust Home Assistant Ingress: a request proxied by the Supervisor counts as an authenticated admin — no login. Default (unset) = on in the HA add-on, off in a plain build; set On/Off to override. Safe only with the add-on's panel_admin: true (admins-only Ingress); real tokens/sessions still win. Restart required.
north.rest.auth.ha_ingress.role string expert yes Loom role granted to a trusted Ingress request: "admin" (default), "operator" or "viewer".
north.rest.auth.ha_ingress.trusted_proxy_cidr string expert yes Network the Ingress request's real peer must come from. Empty uses the HA Supervisor default 172.30.32.0/23. X-Forwarded-For is never trusted.
north.rest.auth.occulite_sso.enabled *bool basic yes Trust the openccu-lite box shell's session: a request the box gate passes on signs in as the box user (box admin = admin, box user = operator) — no login. A box API token the gate accepted signs in too: with the add-on's scope addon:openccu-loom as operator, with Full access as admin. Accepted only beside an openccu-lite box; every session is live-verified against the box, the header alone authenticates nothing. Default (unset) = on in the openccu-lite add-on, off in any other build; set On/Off to override. Real tokens/sessions still win. Restart required.
north.rest.auth.oidc.client_id string basic yes Public client identifier registered with the IdP. PKCE flow.
north.rest.auth.oidc.client_secret string secret yes Confidential client secret registered with the IdP. Leave empty for public clients (PKCE-only). Prefer setting via environment variable.
north.rest.auth.oidc.enabled bool basic yes Enable OpenID Connect single-sign-on. The login page surfaces an SSO button when configured.
north.rest.auth.oidc.issuer string basic yes Issuer URL (no trailing slash). The .well-known/openid-configuration document is fetched on daemon start.
north.rest.auth.oidc.redirect_url string basic yes Must match the URL registered with the IdP. Points at the daemon's OIDC callback handler.
north.rest.auth.oidc.role_claim string role expert yes JWT claim name the daemon reads to determine the user role (admin / user). Defaults to "role".
north.rest.auth.pairing.enabled *bool basic yes Lets a client on the local network ask for an API token by code pairing: you approve by typing the six-digit code it displays. Nothing is granted without that typed code. Off removes the unauthenticated pairing endpoints entirely (restart required).
north.rest.auth.session_idle_timeout time.Duration expert yes Log a session out after this much inactivity, even while its absolute lifetime is still running (e.g. 30m, 2h). 0 disables the idle check and leaves only the absolute session lifetime in charge.
north.rest.cors []string basic yes Whitelisted browser origins for cross-origin REST calls. Empty disables CORS entirely; use ["*"] only for development.
north.rest.csrf_enabled *bool basic yes Mount the double-submit cookie/header CSRF guard on mutating REST endpoints; enabled by default for browser-facing deployments — disable only for pure API-token setups where no session cookies are issued.
north.rest.csrf_secure bool basic yes Set the Secure flag on the CSRF cookie; enable when the daemon is behind an HTTPS / TLS terminator.
north.rest.enabled *bool true basic yes Master switch for the REST + WebSocket server. Disabling it leaves the daemon with no operator-facing surface.
north.rest.openapi_spec_path string expert yes Override path for the OpenAPI YAML. Defaults to the copy embedded in the binary at build time. Expert: set only when hot-patching the spec during development.
north.rest.openapi_validate *bool true expert yes Validate every incoming REST request against assets/openapi.yaml at runtime. Default true. Disable only on heavily degraded hardware where the ~1 ms overhead is measurable.
north.rest.public_url string basic yes Externally-reachable base URL of this daemon (scheme + host [+ port]), e.g. https://loom.example.com. Used to build absolute links such as the OIDC redirect URL and to derive secure-cookie behaviour. Leave empty to infer it per request — set it when running behind a reverse proxy or under a custom domain.
north.rest.rate_limit.burst int 30 expert yes Token-bucket size — maximum concurrent requests per identity before the limiter gates.
north.rest.rate_limit.enabled bool basic yes Enforce per-identity token-bucket rate limiting on REST requests. Excess returns HTTP 429.
north.rest.rate_limit.requests_per_second float64 10 expert yes Steady-state token-refill rate per identity. 10 is a sensible starting point.
north.rest.tls_cert_file string basic yes Path to the PEM certificate (chain). Set this together with the key file to serve the API + SPA over HTTPS on the same port; leave both empty for plain HTTP behind a TLS-terminating proxy. An uploaded certificate is written to this path and watched for hot-reload — the upload replaces the file's contents, it does not remove the need to pick a location.
north.rest.tls_key_file string basic yes Path to the PEM private key that matches the certificate file. Required together with the certificate to enable HTTPS; an uploaded key is written here and hot-reloaded on change.
north.rest.tracing.otlp_endpoint string expert yes Base URL of an OTLP/HTTP trace collector (e.g. http://jaeger:4318); empty (default) disables span export entirely.
north.rest.ws.replay_capacity int 1024 expert yes Ring-buffer depth for the subscribe-with-since WebSocket feature. Default 1024 events. Reduce on memory-constrained hosts; increase if late subscribers miss bursts.

north.ui

Key Type Default Class Restart Description
north.ui.embedded *bool basic no Turn on when Home Assistant owns this daemon's config surface — the Homematic(IP) Local integration runs against this daemon. Hides what HA already owns. Not derived from Ingress: the add-on is also used without the integration. Where the setting applies is a separate question — see “Scope of the embedded mode”.
north.ui.embedded_scope config.EmbeddedScope basic no Where the embedded mode applies. “Only in Home Assistant” (default) reduces the UI only for requests that arrive through Home Assistant, so anyone who opens this daemon's own address keeps the full UI — they chose Loom over the HA panel, and the reason for hiding (Home Assistant shows the same editor) does not apply to them. “Everywhere” reduces it on every path.
north.ui.enabled *bool true basic yes Bootstrap UI surface (login, /setup wizard, /health). The SPA itself lives on the REST listener.

north.webhook

Key Type Default Class Restart Description
north.webhook.centrals []string basic yes Allowlist of CCU names to deliver events for. Empty delivers events from all CCUs.
north.webhook.enabled bool basic yes Master switch for the outbound webhook. When on, the daemon POSTs a signed JSON payload to the configured URL on datapoint, system-status and incident events. Off by default. Takes effect after a daemon restart.
north.webhook.events []string basic yes Allowlist of event-type tags to deliver (e.g. datapoint.value_changed). Empty delivers all supported events.
north.webhook.inbound.enabled bool basic yes Master switch for the inbound webhook REST surface (POST /api/v1/webhook/value and /api/v1/webhook/program). Off by default. Routes are mounted only when enabled, so changing this takes effect after a daemon restart. Inbound requests are real device writes / program runs.
north.webhook.inbound.token string secret yes Optional bearer token accepted in addition to the normal auth chain, so a header-only caller (e.g. a doorbell) can POST without a session or user login. Sent as Authorization: Bearer <token>. Empty means only the normal auth chain applies.
north.webhook.parameter_glob string expert yes Optional glob (e.g. *TEMPERATURE*) restricting datapoint events to matching parameter names. Empty applies no parameter filter; other event types are unaffected.
north.webhook.secret string secret yes Shared key for the HMAC-SHA256 body signature sent in the X-OpenCCU-Signature header. Empty means no signature is sent (the receiver cannot verify authenticity).
north.webhook.timeout_ms int expert yes Per-delivery HTTP timeout in milliseconds. Zero or negative uses the 10000 ms default.
north.webhook.url string basic yes Absolute http(s) endpoint each event is POSTed to. Empty disables delivery even while enabled.

persistence

Key Type Default Class Restart Description
persistence.history.disabled_centrals []string expert yes Central names whose data points must not be recorded; empty (default) records all enabled centrals.
persistence.history.enabled *bool expert yes Master switch for the measurement-history recorder; off by default (opt-in) — when enabled the daemon opens history.db and starts the retention job.
persistence.history.energy_currency string basic yes Label for the amounts derived from the tariff (symbol or code, e.g. € or CHF). Defaults to the euro sign. Purely a label — no conversion happens.
persistence.history.energy_price_per_kwh float64 basic yes Price of one kilowatt-hour, used by the energy view to show costs next to consumption. Leave at 0 to show no costs at all — a tariff of 0 would render every amount as 0.00.
persistence.history.exclude []string expert yes Parameter-name globs to drop from recording; exclude always wins over include — empty (default) excludes nothing.
persistence.history.export.bucket string expert yes InfluxDB v2 bucket into which samples are written.
persistence.history.export.enabled *bool expert yes Turn on the push exporter that forwards each recorded sample to an external time-series store (InfluxDB by default); disabled by default.
persistence.history.export.endpoint string expert yes Base URL of the target time-series store, e.g. http://influx:8086.
persistence.history.export.kind string expert yes Exporter backend; empty or "influxdb" selects the InfluxDB v2 line-protocol writer (the only available backend today).
persistence.history.export.org string expert yes InfluxDB v2 organisation name that owns the target bucket.
persistence.history.export.token_env string expert yes Name of the environment variable that holds the InfluxDB write token; the token is never stored inline in config.
persistence.history.flush_interval time.Duration 5s expert yes How often the recorder flushes a batch of samples to history.db; zero falls back to the daemon default of 5 s.
persistence.history.include []string expert yes Parameter-name globs to record (e.g. TEMPERATURE, *POWER*); empty (default) records every numeric VALUES parameter.
persistence.history.retention time.Duration 720h0m0s expert yes How long raw samples are kept; zero falls back to 30 days (720 h), after which the retention job purges older rows.
persistence.history.retention_daily time.Duration expert yes How long the daily rollup tier is kept; zero (default) keeps daily rows forever since they are tiny (one row per data point per day).
persistence.history.retention_hourly time.Duration expert yes How long the hourly rollup tier is kept; zero falls back to 13 months. Hourly rows are folded into the daily tier before this cutoff removes them.
persistence.values_cache.disabled_centrals []string expert yes List of central names (one per line) whose data points are kept out of the cache. Useful for test rigs in a multi-CCU deployment.
persistence.values_cache.enabled *bool true expert yes Cache the most recent VALUES paramset of every data point locally so a daemon restart picks up where it left off without a full CCU re-read. Default: ON.
persistence.values_cache.flush_interval time.Duration 1m0s expert yes How often to flush queued cache writes to disk. Default 60 s — short enough to survive a crash with minimal loss, long enough to coalesce bursts.

reliability

Key Type Default Class Restart Description
reliability.command_retry_initial_delay time.Duration 2s expert yes First backoff delay after a transient CCU write failure (the retry-stack doubles on each step). Default 2 s (production-hardened); lower it for fast test rigs.
reliability.command_throttle_inter_command_delay time.Duration expert yes Minimum gap between two consecutive throttled commands per CCU interface. Default 0 (no pacing). Raise to ~50–500 ms on heavily-loaded BidCos-RF interfaces to reduce duty-cycle errors.