ombi: reach sonarr, radarr and lidarr through the mesh

ombi keeps its Servarr connections in its own database, so the mesh has no file to write them into. A run-once step reads the three bindings and pair credentials and writes host, port, TLS, base path and key into ombi through ombi's own API - only when they differ, and nothing else ombi keeps. Until the operator accepts an app's key for this pair the mesh delivers a value it minted, which no Servarr app accepts. The step tries the key against the app first and, refused, writes nothing and fails naming the secret accept that fixes it, so the old working key in ombi is never replaced by a dead one. Declared last so its failing gates nothing else of ombi (ADR 0136), and restart-on its six inputs so it runs again when a provider moves (ADR 0099).
sonarr, radarr, lidarr: provide their API to the mesh
2026-09-30 00:39:19 +02:00 · 2026-09-30 00:39:19 +02:00 · 2026-09-30 00:25:55 +02:00 · 2026-09-29 23:50:19 +02:00 · 2026-09-29 23:38:56 +02:00 · 2026-09-29 20:45:13 +00:00
57 changed files with 814 additions and 77 deletions
@@ -14,7 +14,7 @@
    },
    "route": {
      "label": "baserow",
-      "port": 80
+      "endpoint": "web"
    }
  },
  "binds": {
@@ -30,6 +30,7 @@
  },
  "listens": [
    {
+      "name": "web",
      "port": 80,
      "protocol": "tcp",
      "from": "mesh",
@@ -13,6 +13,7 @@
  },
  "listens": [
    {
+      "name": "web",
      "port": 6767,
      "protocol": "tcp",
      "from": "mesh",
@@ -93,7 +94,7 @@
      ],
      "env": {
        "MESH_BROKER_FILE": "/run/secrets/broker",
-        "MESH_BAZARR_URL": "http://127.0.0.1:6767",
+        "MESH_BAZARR_URL": "http://127.0.0.1:${port:6767}",
        "MESH_BAZARR_API_KEY_FILE": "/run/secrets/api-key",
        "MESH_BAZARR_CONFIG_FILE": "/run/config/config.json",
        "MESH_BAZARR_CONFIG_DIR": "/var/lib/bazarr/config"
@@ -110,7 +111,7 @@
  "contributes": {
    "route": {
      "label": "subs",
-      "port": 6767
+      "endpoint": "web"
    }
  },
  "binds": {
@@ -15,6 +15,7 @@
  },
  "listens": [
    {
+      "name": "web",
      "port": 8787,
      "protocol": "tcp",
      "from": "mesh",
@@ -75,7 +76,7 @@
      ],
      "env": {
        "MESH_BROKER_FILE": "/run/secrets/broker",
-        "MESH_BOOKSHELF_URL": "http://127.0.0.1:8787",
+        "MESH_BOOKSHELF_URL": "http://127.0.0.1:${port:8787}",
        "MESH_BOOKSHELF_CONFIG_DIR": "/var/lib/bookshelf/config"
      },
      "artifact": "runtime"
@@ -87,7 +88,7 @@
  "contributes": {
    "route": {
      "label": "books",
-      "port": 8787
+      "endpoint": "web"
    }
  },
  "binds": {
@@ -0,0 +1,56 @@
+{
+  "module": "ca-trust",
+  "version": "1",
+  "slug": "catrust",
+  "capabilities": [
+    "service-manager"
+  ],
+  "requires": [
+    "internal-acme-ca"
+  ],
+  "seats": [
+    {
+      "name": "the-mesh-trust-anchor",
+      "scope": "node"
+    }
+  ],
+  "claims": [
+    {
+      "name": "the-mesh-trust-anchor",
+      "scope": "node"
+    }
+  ],
+  "resources": [
+    {
+      "id": "state",
+      "type": "directory",
+      "mode": "0700",
+      "place": "."
+    },
+    {
+      "id": "anchor",
+      "type": "file",
+      "path": "${dir:state}/anchor",
+      "mode": "0755",
+      "content": "#!/bin/sh\n# The mesh's internal certificate authority, trusted by this machine.\n#\n# Written by the mesh from the ca-trust module's manifest (novox/hq ADR 0147).\n# Editing it here lasts until the next apply.\n#\n# There is no prior trust to verify the fetch against \u2014 this is the thing that\n# establishes it \u2014 so it is made over the mesh's own private network, which is\n# what authenticates it (novox/hq ADR 0098, the same reasoning that lets the\n# route proxy fetch this root for itself). What comes back is checked here: a\n# body that is not a certificate is refused now, rather than believed and then\n# failed by whatever reads the trust store next.\nset -eu\n\nROOTS='https://${bound:internal-acme-ca:at}:${bound:internal-acme-ca:port}${bound:internal-acme-ca:roots}'\nANCHORS=/etc/ca-certificates/trust-source/anchors\nANCHOR=\"$ANCHORS/mesh-internal-ca.crt\"\n\n# Arch's layout, said out loud rather than assumed: a machine that keeps its\n# anchors elsewhere fails here, visibly, instead of writing a file nothing\n# reads. That failure is the signal that this belongs in the host, where one\n# operating system's difference lives (novox/hq ADR 0147, option 2).\n[ -d \"$ANCHORS\" ] || {\n\techo \"this machine keeps no trust anchors in $ANCHORS; ca-trust is written for that layout\" >&2\n\texit 1\n}\n\ncase \"${1:-}\" in\ninstall)\n\ttmp=$(mktemp)\n\ttrap 'rm -f \"$tmp\"' EXIT\n\t# The authority may still be starting, or this machine may have come up\n\t# before it: two minutes of asking, then an honest failure.\n\tn=0\n\twhile [ \"$n\" -lt 60 ]; do\n\t\tif curl --fail --silent --show-error --insecure --max-time 10 \\\n\t\t\t--output \"$tmp\" \"$ROOTS\" &&\n\t\t\tgrep -q 'BEGIN CERTIFICATE' \"$tmp\"; then\n\t\t\tinstall -m 0644 \"$tmp\" \"$ANCHOR\"\n\t\t\tupdate-ca-trust\n\t\t\texit 0\n\t\tfi\n\t\tn=$((n + 1))\n\t\tsleep 2\n\tdone\n\techo \"the authority at $ROOTS did not serve a certificate within two minutes\" >&2\n\texit 1\n\t;;\nremove)\n\t# What stopping the unit does, and therefore what being unassigned does.\n\trm -f \"$ANCHOR\"\n\tupdate-ca-trust\n\t;;\n*)\n\techo \"usage: $(basename \"$0\") install|remove\" >&2\n\texit 2\n\t;;\nesac\n"
+    },
+    {
+      "id": "unit",
+      "type": "file",
+      "path": "/etc/systemd/system/mesh-ca-trust.service",
+      "mode": "0644",
+      "content": "[Unit]\nDescription=The mesh's internal certificate authority, trusted by this machine\n# novox/hq ADR 0147. Starting this unit places the mesh's root among this\n# machine's trust anchors; stopping it takes the root away again, which is what\n# the host does when the module is no longer assigned here.\nWants=network-online.target\nAfter=network-online.target\n\n[Service]\nType=oneshot\nRemainAfterExit=yes\nExecStart=${dir:state}/anchor install\nExecStop=${dir:state}/anchor remove\n\n[Install]\nWantedBy=multi-user.target\n"
+    },
+    {
+      "id": "trust",
+      "type": "service",
+      "unit": "mesh-ca-trust.service",
+      "state": "running",
+      "boot": "enabled",
+      "restart-on": [
+        "anchor",
+        "unit"
+      ]
+    }
+  ]
+}
@@ -11,7 +11,7 @@
  "contributes": {
    "route": {
      "label": "de-spiegel",
-      "port": 35621
+      "endpoint": "web"
    }
  },
  "binds": {
@@ -23,6 +23,7 @@
  },
  "listens": [
    {
+      "name": "web",
      "port": 35621,
      "protocol": "tcp",
      "from": "mesh",
@@ -29,6 +29,7 @@
  },
  "listens": [
    {
+      "name": "registry",
      "port": 5000,
      "protocol": "tcp",
      "from": "mesh",
@@ -22,6 +22,7 @@
  ],
  "listens": [
    {
+      "name": "dns-udp",
      "port": 53,
      "protocol": "udp",
      "from": "mesh",
@@ -29,6 +30,7 @@
      "fixed": true
    },
    {
+      "name": "dns-tcp",
      "port": 53,
      "protocol": "tcp",
      "from": "mesh",
@@ -13,7 +13,7 @@
    "route": {
      "web": {
        "label": "git",
-        "port": 3000
+        "endpoint": "web"
      },
      "internal-api-refused": {
        "label": "git",
@@ -44,12 +44,14 @@
  ],
  "listens": [
    {
+      "name": "web",
      "port": 3000,
      "protocol": "tcp",
      "from": "mesh",
      "why": "the forge, over http"
    },
    {
+      "name": "ssh",
      "port": 22,
      "protocol": "tcp",
      "from": "mesh",
@@ -13,6 +13,7 @@
  ],
  "listens": [
    {
+      "name": "web",
      "port": 3000,
      "protocol": "tcp",
      "from": "mesh",
@@ -96,7 +97,7 @@
  "contributes": {
    "route": {
      "label": "grafana",
-      "port": 3000
+      "endpoint": "web"
    }
  },
  "binds": {
@@ -11,7 +11,7 @@
  "contributes": {
    "route": {
      "label": "hello",
-      "port": 8080
+      "endpoint": "web"
    }
  },
  "binds": {
@@ -19,6 +19,7 @@
  },
  "listens": [
    {
+      "name": "web",
      "port": 8080,
      "protocol": "tcp",
      "from": "mesh",
@@ -14,6 +14,7 @@
  },
  "listens": [
    {
+      "name": "web",
      "port": 8123,
      "protocol": "tcp",
      "from": "mesh",
@@ -85,7 +86,7 @@
  "contributes": {
    "route": {
      "label": "home-assistant",
-      "port": 8123
+      "endpoint": "web"
    }
  },
  "binds": {
@@ -13,6 +13,7 @@
  },
  "listens": [
    {
+      "name": "stream",
      "port": 8000,
      "protocol": "tcp",
      "from": "mesh",
@@ -9,6 +9,7 @@
  },
  "listens": [
    {
+      "name": "api",
      "port": 8086,
      "protocol": "tcp",
      "from": "mesh",
@@ -17,11 +17,11 @@
    "route": {
      "site": {
        "label": "invoicing",
-        "port": 80
+        "endpoint": "web"
      },
      "api": {
        "label": "invoicing-api",
-        "port": 9000
+        "endpoint": "api"
      }
    }
  },
@@ -36,12 +36,14 @@
  },
  "listens": [
    {
+      "name": "web",
      "port": 80,
      "protocol": "tcp",
      "from": "mesh",
      "why": "the invoicing web frontend; a public name is a route grant later"
    },
    {
+      "name": "api",
      "port": 9000,
      "protocol": "tcp",
      "from": "mesh",
@@ -6,6 +6,7 @@
  ],
  "listens": [
    {
+      "name": "web",
      "port": 9117,
      "protocol": "tcp",
      "from": "mesh",
@@ -82,7 +83,7 @@
  "contributes": {
    "route": {
      "label": "indexers",
-      "port": 9117
+      "endpoint": "web"
    }
  },
  "binds": {
@@ -11,7 +11,7 @@
    },
    "route": {
      "label": "keycloak",
-      "port": 8080
+      "endpoint": "web"
    }
  },
  "binds": {
@@ -34,6 +34,7 @@
  ],
  "listens": [
    {
+      "name": "web",
      "port": 8080,
      "protocol": "tcp",
      "from": "mesh",
@@ -24,6 +24,7 @@
  },
  "listens": [
    {
+      "name": "web",
      "port": 8283,
      "protocol": "tcp",
      "from": "mesh",
@@ -1,6 +1,19 @@
 {
  "module": "lidarr",
  "version": "1",
+  "provides": [
+    {
+      "name": "lidarr-api",
+      "scope": "mesh"
+    }
+  ],
+  "serves": {
+    "lidarr-api": {
+      "scheme": "http",
+      "port": 8686,
+      "url-base": ""
+    }
+  },
  "capabilities": [
    "container-runtime"
  ],
@@ -14,6 +27,7 @@
  },
  "listens": [
    {
+      "name": "web",
      "port": 8686,
      "protocol": "tcp",
      "from": "mesh",
@@ -74,7 +88,7 @@
      ],
      "env": {
        "MESH_BROKER_FILE": "/run/secrets/broker",
-        "MESH_LIDARR_URL": "http://127.0.0.1:8686",
+        "MESH_LIDARR_URL": "http://127.0.0.1:${port:8686}",
        "MESH_LIDARR_CONFIG_DIR": "/var/lib/lidarr/config"
      },
      "artifact": "runtime"
@@ -86,7 +100,7 @@
  "contributes": {
    "route": {
      "label": "lidarr",
-      "port": 8686
+      "endpoint": "web"
    }
  },
  "binds": {
@@ -16,27 +16,27 @@
    "route": {
      "web": {
        "label": "mail",
-        "port": 7443,
+        "endpoint": "web-tls",
        "scheme": "https",
        "insecure": true
      },
      "acme": {
        "label": "mail",
        "path": "/.well-known/acme-challenge",
-        "port": 7080,
+        "endpoint": "web",
        "priority": 100
      },
      "autoconfig": {
        "label": "autoconfig",
-        "port": 4243
+        "endpoint": "autoconfig"
      },
      "autodiscover": {
        "label": "autodiscover",
-        "port": 4243
+        "endpoint": "autoconfig"
      },
      "automx": {
        "label": "automx",
-        "port": 4243
+        "endpoint": "autoconfig"
      }
    }
  },
@@ -60,6 +60,7 @@
  ],
  "listens": [
    {
+      "name": "smtp",
      "port": 25,
      "protocol": "tcp",
      "from": "anywhere",
@@ -67,6 +68,7 @@
      "fixed": true
    },
    {
+      "name": "pop3",
      "port": 110,
      "protocol": "tcp",
      "from": "anywhere",
@@ -74,6 +76,7 @@
      "fixed": true
    },
    {
+      "name": "imap",
      "port": 143,
      "protocol": "tcp",
      "from": "anywhere",
@@ -81,6 +84,7 @@
      "fixed": true
    },
    {
+      "name": "smtps",
      "port": 465,
      "protocol": "tcp",
      "from": "anywhere",
@@ -88,6 +92,7 @@
      "fixed": true
    },
    {
+      "name": "submission",
      "port": 587,
      "protocol": "tcp",
      "from": "anywhere",
@@ -95,6 +100,7 @@
      "fixed": true
    },
    {
+      "name": "imaps",
      "port": 993,
      "protocol": "tcp",
      "from": "anywhere",
@@ -102,6 +108,7 @@
      "fixed": true
    },
    {
+      "name": "pop3s",
      "port": 995,
      "protocol": "tcp",
      "from": "anywhere",
@@ -109,18 +116,21 @@
      "fixed": true
    },
    {
+      "name": "web",
      "port": 7080,
      "protocol": "tcp",
      "from": "mesh",
      "why": "the web front over http; only the ACME HTTP-01 passthrough is routed here \u2014 everything else 301s to https and would loop a proxy"
    },
    {
+      "name": "web-tls",
      "port": 7443,
      "protocol": "tcp",
      "from": "mesh",
      "why": "the web front over its own TLS (admin, webmail, API); the public name mail.novox.be is a route grant reaching it here"
    },
    {
+      "name": "autoconfig",
      "port": 4243,
      "protocol": "tcp",
      "from": "mesh",
@@ -6,6 +6,7 @@
  ],
  "listens": [
    {
+      "name": "api",
      "port": 59125,
      "protocol": "tcp",
      "from": "mesh",
@@ -14,11 +14,11 @@
    "route": {
      "api": {
        "label": "files-api",
-        "port": 9000
+        "endpoint": "s3"
      },
      "console": {
        "label": "files",
-        "port": 9001
+        "endpoint": "console"
      }
    }
  },
@@ -31,12 +31,14 @@
  ],
  "listens": [
    {
+      "name": "s3",
      "port": 9000,
      "protocol": "tcp",
      "from": "mesh",
      "why": "the S3 endpoint"
    },
    {
+      "name": "console",
      "port": 9001,
      "protocol": "tcp",
      "from": "mesh",
@@ -20,6 +20,7 @@
  ],
  "listens": [
    {
+      "name": "database",
      "port": 27017,
      "protocol": "tcp",
      "from": "mesh",
@@ -34,12 +34,14 @@
  },
  "listens": [
    {
+      "name": "mqtt",
      "port": 1883,
      "protocol": "tcp",
      "from": "mesh",
      "why": "modules on any machine that were granted a topic namespace"
    },
    {
+      "name": "mqtt-websockets",
      "port": 8081,
      "protocol": "tcp",
      "from": "mesh",
@@ -20,6 +20,7 @@
  ],
  "listens": [
    {
+      "name": "database",
      "port": 4848,
      "protocol": "tcp",
      "from": "mesh",
@@ -14,7 +14,7 @@
    },
    "route": {
      "label": "n8n",
-      "port": 5682
+      "endpoint": "web"
    }
  },
  "binds": {
@@ -29,6 +29,7 @@
  },
  "listens": [
    {
+      "name": "web",
      "port": 5682,
      "protocol": "tcp",
      "from": "mesh",
@@ -21,6 +21,7 @@
  "consumes": [],
  "listens": [
    {
+      "name": "bus",
      "port": 4222,
      "protocol": "tcp",
      "from": "mesh",
@@ -13,7 +13,7 @@
    },
    "route": {
      "label": "drive",
-      "port": 80
+      "endpoint": "web"
    }
  },
  "binds": {
@@ -38,6 +38,7 @@
  ],
  "listens": [
    {
+      "name": "web",
      "port": 80,
      "protocol": "tcp",
      "from": "mesh",
@@ -12,6 +12,7 @@
  ],
  "listens": [
    {
+      "name": "web",
      "port": 1880,
      "protocol": "tcp",
      "from": "mesh",
@@ -81,7 +82,7 @@
  "contributes": {
    "route": {
      "label": "nodered",
-      "port": 1880
+      "endpoint": "web"
    }
  },
  "binds": {
@@ -10,7 +10,7 @@
  "contributes": {
    "route": {
      "label": "@",
-      "port": 4000
+      "endpoint": "web"
    }
  },
  "binds": {
@@ -18,6 +18,7 @@
  },
  "listens": [
    {
+      "name": "web",
      "port": 4000,
      "protocol": "tcp",
      "from": "mesh",
@@ -15,6 +15,7 @@
  },
  "listens": [
    {
+      "name": "web",
      "port": 6789,
      "protocol": "tcp",
      "from": "mesh",
@@ -80,7 +81,7 @@
      ],
      "env": {
        "MESH_BROKER_FILE": "/run/secrets/broker",
-        "MESH_NZBGET_URL": "http://127.0.0.1:6789",
+        "MESH_NZBGET_URL": "http://127.0.0.1:${port:6789}",
        "MESH_NZBGET_PASSWORD_FILE": "/run/secrets/password",
        "MESH_NZBGET_CONFIG_FILE": "/run/config/config.json",
        "MESH_NZBGET_CONFIG_DIR": "/var/lib/nzbget/config"
@@ -12,6 +12,7 @@
  ],
  "listens": [
    {
+      "name": "api",
      "port": 11434,
      "protocol": "tcp",
      "from": "machine",
@@ -13,7 +13,7 @@ ARG RUNTIME_BASE
 FROM ${BUILD_BASE} AS build
 WORKDIR /app/modules/ombi
 COPY . .
-RUN node /app/node_modules/typescript/bin/tsc client.ts index.ts tools/index.ts \
+RUN node /app/node_modules/typescript/bin/tsc client.ts index.ts tools/index.ts servarr/settings.ts servarr/index.ts \
      --module NodeNext --moduleResolution NodeNext --target ES2022 --outDir dist

 FROM ${RUNTIME_BASE}
@@ -22,3 +22,6 @@ COPY --from=build /app/modules/ombi/dist /app/modules/ombi/dist
 # provider's provisioner runs its reconcile loop in the same process, with the broker connected —
 # the convention novox/hq issues 060/061 settled.
 ENV MESH_TOOL_MODULES=/app/modules/ombi/dist/index.js,/app/modules/ombi/dist/tools/index.js
+# NOT dist/servarr/index.js: that is a step the host runs to completion, named by the `servarr`
+# container's args as `mesh-tools run …` (novox/hq ADR 0052). Listed here it would run inside the
+# serving sidecar too, and exit it.
@@ -14,6 +14,7 @@
  },
  "listens": [
    {
+      "name": "web",
      "port": 3579,
      "protocol": "tcp",
      "from": "mesh",
@@ -27,10 +28,15 @@
      "path": "/var/lib/mesh/ombi",
      "mode": "0700"
    },
+    {
+      "id": "state",
+      "type": "directory",
+      "mode": "0700",
+      "place": "."
+    },
    {
      "id": "config",
      "type": "directory",
-      "path": "/services/ombi/config",
      "mode": "0700",
      "owner": "1000:1000"
    },
@@ -38,7 +44,7 @@
      "id": "server",
      "type": "container",
      "name": "ombi",
-      "image": "lscr.io/linuxserver/ombi@sha256:a6f76ac521ba01eee2e9f0c23a3fed22e56630d97a04d5eeaeaa36c1e681640d",
+      "image": "lscr.io/linuxserver/ombi@sha256:22d6ebadbaaa728571353e74dc2173719e0fb02d4eaec551a7e9d2ee99ef68ac",
      "env": {
        "PUID": "1000",
        "PGID": "1000",
@@ -48,7 +54,7 @@
        "3579"
      ],
      "volumes": [
-        "/services/ombi/config:/config"
+        "${dir:config}:/config"
      ]
    },
    {
@@ -67,33 +73,76 @@
      "volumes": [
        "/var/lib/mesh/ombi/broker:/run/secrets/broker:ro",
        "/var/lib/mesh/ombi/api-key:/run/secrets/api-key:ro",
-        "/var/lib/mesh/ombi/config.json:/run/config/config.json:ro",
-        "/services/ombi/config:/var/lib/ombi/config:ro"
+        "/var/lib/mesh/ombi/config.json:/run/config/config.json:ro"
      ],
      "env": {
        "MESH_BROKER_FILE": "/run/secrets/broker",
-        "MESH_OMBI_URL": "http://127.0.0.1:3579",
+        "MESH_OMBI_URL": "http://127.0.0.1:${port:3579}",
        "MESH_OMBI_API_KEY_FILE": "/run/secrets/api-key",
-        "MESH_OMBI_CONFIG_FILE": "/run/config/config.json",
-        "MESH_OMBI_CONFIG_DIR": "/var/lib/ombi/config"
+        "MESH_OMBI_CONFIG_FILE": "/run/config/config.json"
      },
      "restart-on": [
        "runtime-config"
      ],
      "artifact": "runtime"
+    },
+    {
+      "id": "servarr",
+      "type": "container",
+      "name": "mesh-ombi-servarr",
+      "network": "host",
+      "run-once": true,
+      "volumes": [
+        "/var/lib/mesh/ombi/api-key:/run/secrets/api-key:ro",
+        "${dir:state}/sonarr-api.json:/run/servarr/sonarr-api.json:ro",
+        "${dir:state}/sonarr-api.secret:/run/servarr/sonarr-api.secret:ro",
+        "${dir:state}/radarr-api.json:/run/servarr/radarr-api.json:ro",
+        "${dir:state}/radarr-api.secret:/run/servarr/radarr-api.secret:ro",
+        "${dir:state}/lidarr-api.json:/run/servarr/lidarr-api.json:ro",
+        "${dir:state}/lidarr-api.secret:/run/servarr/lidarr-api.secret:ro"
+      ],
+      "env": {
+        "MESH_OMBI_URL": "http://127.0.0.1:${port:3579}",
+        "MESH_OMBI_API_KEY_FILE": "/run/secrets/api-key",
+        "MESH_SERVARR_DIR": "/run/servarr"
+      },
+      "args": [
+        "run",
+        "/app/modules/ombi/dist/servarr/index.js"
+      ],
+      "restart-on": [
+        "bound-sonarr-api",
+        "secret-sonarr-api",
+        "bound-radarr-api",
+        "secret-radarr-api",
+        "bound-lidarr-api",
+        "secret-lidarr-api"
+      ],
+      "artifact": "runtime"
    }
  ],
  "requires": [
-    "route"
+    "lidarr-api",
+    "radarr-api",
+    "route",
+    "sonarr-api"
  ],
  "contributes": {
    "route": {
      "label": "ombi",
-      "port": 3579
+      "endpoint": "web"
    }
  },
  "binds": {
-    "route": "/var/lib/mesh/ombi/route.json"
+    "route": "${dir:state}/route.json",
+    "sonarr-api": "${dir:state}/sonarr-api.json",
+    "radarr-api": "${dir:state}/radarr-api.json",
+    "lidarr-api": "${dir:state}/lidarr-api.json"
+  },
+  "secrets": {
+    "sonarr-api": "${dir:state}/sonarr-api.secret",
+    "radarr-api": "${dir:state}/radarr-api.secret",
+    "lidarr-api": "${dir:state}/lidarr-api.secret"
  },
  "build": {
    "on": [
@@ -4,6 +4,11 @@
  "description": "ombi — media requests. Its API client, tools and events live here (novox/hq ADR 0039).",
  "type": "module",
  "private": true,
+  "scripts": {
+    "build": "tsc client.ts index.ts tools/index.ts servarr/settings.ts servarr/index.ts --module NodeNext --moduleResolution NodeNext --target ES2022 --outDir dist",
+    "typecheck": "tsc -p tsconfig.json",
+    "test": "node --test --experimental-strip-types 'test/*.test.ts'"
+  },
  "dependencies": {
    "@novox/mesh-sdk": "^0.1.0"
  },
@@ -0,0 +1,59 @@
+// ombi's Servarr step — run once by the host after ombi's server starts, and run again whenever a
+// binding or pair credential it reads changes (the container's `restart-on`, novox/hq ADR 0099).
+//
+// **A step, not a loop**, for the reason route-adapter gives: everything it does is a function of
+// files the mesh writes, and the host already knows when they change. It connects to no broker.
+//
+// Exits non-zero when any app could not be put right — a refused credential, an unreachable app, an
+// ombi that cannot reach it — so the node reports the step failed and the host runs it again on the
+// next apply. It is declared last in the manifest, so its failing gates nothing else of ombi's
+// (novox/hq ADR 0136).
+//
+// Reads, per app, `<dir>/<provision>.json` (the binding) and `<dir>/<provision>.secret` (the pair
+// credential), where <dir> is MESH_SERVARR_DIR. Never prints a key.
+
+import { join } from "node:path";
+
+import { APPS, ombiReady, readBinding, readIfThere, reconcileApp, type Http } from "./settings.js";
+
+const dir = process.env.MESH_SERVARR_DIR ?? "/run/servarr";
+const url = process.env.MESH_OMBI_URL ?? "http://127.0.0.1:3579";
+const apiKey = (await readIfThere(process.env.MESH_OMBI_API_KEY_FILE))?.trim() ?? process.env.MESH_OMBI_API_KEY ?? "";
+const waitSeconds = Number(process.env.MESH_OMBI_WAIT_SECONDS ?? "180");
+
+const http: Http = { fetch: (u, init) => fetch(u, init) };
+
+if (!apiKey) {
+  console.error("[ombi-servarr] no ombi API key — ombi's own `api-key` secret has not been accepted");
+  process.exit(1);
+}
+const ombi = { url, apiKey };
+
+if (!(await ombiReady(http, ombi, waitSeconds * 1000))) {
+  console.error(`[ombi-servarr] ombi did not answer at ${url} within ${waitSeconds}s`);
+  process.exit(1);
+}
+
+let failed = 0;
+for (const spec of APPS) {
+  const outcome = await reconcileApp(
+    http,
+    ombi,
+    spec,
+    await readBinding(join(dir, `${spec.provision}.json`)),
+    await readIfThere(join(dir, `${spec.provision}.secret`)),
+  );
+  switch (outcome.result) {
+    case "unchanged":
+      console.log(`[ombi-servarr] ${outcome.app}: already as the mesh says; connection tested`);
+      break;
+    case "written":
+      console.log(`[ombi-servarr] ${outcome.app}: wrote ${outcome.fields.join(", ")}; connection tested`);
+      break;
+    case "refused":
+      failed++;
+      console.error(`[ombi-servarr] ${outcome.app}: ${outcome.problem}`);
+      break;
+  }
+}
+process.exitCode = failed > 0 ? 1 : 0;
@@ -0,0 +1,304 @@
+// Where ombi reaches Sonarr, Radarr and Lidarr — decided by the mesh, written into ombi by ombi's
+// own API.
+//
+// **Why this exists.** ombi keeps its connection to each Servarr app in its own database
+// (OmbiSettings.db), not in a file, so the mesh has nowhere to write `${bound:sonarr-api:at}` for it.
+// ombi requires `sonarr-api`, `radarr-api` and `lidarr-api`; the mesh delivers, for each, a binding
+// (where the app is: `at`, and what it serves: `port`, `scheme`, `url-base`) and a pair credential
+// (the app's API key, accepted by the operator — a Servarr app has exactly one key and the mesh
+// cannot mint it). This step reads those files and makes ombi's settings say the same thing.
+//
+// **Only the connection, and only when it differs.** Host, port, TLS, base path and API key. The
+// quality profile, root folder, language profile, tags, "enabled" and every other choice an operator
+// made in ombi's settings screen are left exactly as they are: the mesh knows where the app is, not
+// what ombi should do with it. Radarr's 4K instance is a different Radarr and is not touched.
+//
+// **A credential the app refuses is never written.** Until the operator accepts the app's API key
+// for this pair, the mesh delivers a value it minted itself, which no Servarr app will ever accept
+// (novox/hq ADR 0092). Writing it would replace a working key in ombi with a dead one. So the key is
+// tried against the app first; refused, nothing for that app is written and the step fails naming
+// the `secret accept` that fixes it.
+//
+// Pure logic and a small HTTP seam, so it is tested against fake servers (test/servarr.test.ts).
+
+import { readFile } from "node:fs/promises";
+
+/** One Servarr app ombi connects to, and the shape of that connection in ombi's API. */
+export interface ServarrApp {
+  /** The app, as ombi's API names it: /Settings/<app>, /Tester/<app>. */
+  app: "sonarr" | "radarr" | "lidarr";
+  /** The provision it is required as — the manifest's `requires`, `binds` and `secrets` key. */
+  provision: string;
+  /** The app's own status endpoint, which answers 401 to a wrong key. */
+  statusPath: string;
+  /**
+   * Where the one connection sits in ombi's settings document. Radarr's is `{radarr, radarr4K}`
+   * (two Radarr instances); only `radarr` is this provision's.
+   */
+  within?: string;
+}
+
+export const APPS: readonly ServarrApp[] = [
+  { app: "sonarr", provision: "sonarr-api", statusPath: "/api/v3/system/status" },
+  { app: "radarr", provision: "radarr-api", statusPath: "/api/v3/system/status", within: "radarr" },
+  { app: "lidarr", provision: "lidarr-api", statusPath: "/api/v1/system/status" },
+];
+
+/** The connection fields ombi keeps for an app — the only ones this step ever writes. */
+export interface Connection {
+  ip: string;
+  port: number;
+  ssl: boolean;
+  /** ombi's name for the app's URL base; null when the app is served at the root. */
+  subDir: string | null;
+  apiKey: string;
+}
+
+/** What the mesh wrote at `binds.<provision>`: the binding document (controller's boundFile). */
+export interface Binding {
+  provision?: string;
+  from?: string;
+  at?: string;
+  as?: string;
+  serves?: Record<string, unknown>;
+}
+
+export type Wanted = { ok: true; connection: Connection; from: string } | { ok: false; problem: string };
+
+/**
+ * The connection the mesh says ombi should use, from the binding and the pair credential.
+ *
+ * Refused rather than guessed when the binding cannot be dialled from ombi's own container: a
+ * loopback `at` — what the mesh hands a machine that is not on the private network — is ombi's
+ * container itself, not the app.
+ */
+export function wanted(spec: ServarrApp, binding: Binding | undefined, credential: string | undefined): Wanted {
+  if (!binding) {
+    return { ok: false, problem: `no binding for ${spec.provision} was delivered — the mesh writes it before this step runs` };
+  }
+  const at = typeof binding.at === "string" ? binding.at.trim() : "";
+  const serves = binding.serves ?? {};
+  const port = Number(serves.port);
+  if (!at) {
+    return { ok: false, problem: `the ${spec.provision} binding names no host (at)` };
+  }
+  if (isLoopback(at)) {
+    return {
+      ok: false,
+      problem:
+        `the ${spec.provision} binding says ${spec.app} is at ${at}, which from ombi's own container is ` +
+        `ombi itself. The mesh hands loopback to a machine that is not on the private network; put it ` +
+        `on the private network so ${spec.app} has an address ombi can dial`,
+    };
+  }
+  if (!Number.isInteger(port) || port <= 0 || port > 65535) {
+    return { ok: false, problem: `the ${spec.provision} binding serves no usable port (${String(serves.port)})` };
+  }
+  const scheme = typeof serves.scheme === "string" && serves.scheme ? serves.scheme : "http";
+  if (scheme !== "http" && scheme !== "https") {
+    return { ok: false, problem: `the ${spec.provision} binding serves scheme ${scheme}, which ombi cannot dial` };
+  }
+  const key = (credential ?? "").trim();
+  if (!key) {
+    return { ok: false, problem: `the ${spec.provision} credential is empty or was not delivered` };
+  }
+  return {
+    ok: true,
+    from: typeof binding.from === "string" ? binding.from : "",
+    connection: { ip: at, port, ssl: scheme === "https", subDir: subDirOf(serves["url-base"]), apiKey: key },
+  };
+}
+
+/** ombi's `subDir`: the URL base with its slashes trimmed, null when there is none. */
+export function subDirOf(urlBase: unknown): string | null {
+  const trimmed = typeof urlBase === "string" ? urlBase.trim().replace(/^\/+|\/+$/g, "") : "";
+  return trimmed === "" ? null : trimmed;
+}
+
+function isLoopback(host: string): boolean {
+  const h = host.toLowerCase();
+  return h === "localhost" || h === "::1" || h === "[::1]" || /^127\./.test(h);
+}
+
+/** Which connection fields differ between what ombi holds and what the mesh says. Names only. */
+export function differing(current: Record<string, unknown> | undefined, want: Connection): (keyof Connection)[] {
+  const now = current ?? {};
+  const out: (keyof Connection)[] = [];
+  if (String(now.ip ?? "") !== want.ip) out.push("ip");
+  if (Number(now.port ?? 0) !== want.port) out.push("port");
+  if (Boolean(now.ssl) !== want.ssl) out.push("ssl");
+  if (subDirOf(now.subDir) !== want.subDir) out.push("subDir");
+  if (String(now.apiKey ?? "") !== want.apiKey) out.push("apiKey");
+  return out;
+}
+
+/** ombi's settings for the app with the connection laid over them and nothing else changed. */
+export function withConnection(current: Record<string, unknown> | undefined, want: Connection): Record<string, unknown> {
+  return { ...(current ?? {}), ip: want.ip, port: want.port, ssl: want.ssl, subDir: want.subDir, apiKey: want.apiKey };
+}
+
+/** The app's base URL as the step dials it — the same host and port ombi will be given. */
+export function appUrl(want: Connection): string {
+  const scheme = want.ssl ? "https" : "http";
+  const host = want.ip.includes(":") && !want.ip.startsWith("[") ? `[${want.ip}]` : want.ip;
+  return `${scheme}://${host}:${want.port}${want.subDir ? `/${want.subDir}` : ""}`;
+}
+
+/** How one app came out. */
+export type Outcome =
+  | { app: string; result: "unchanged" }
+  | { app: string; result: "written"; fields: string[] }
+  | { app: string; result: "refused"; problem: string };
+
+/** The HTTP the step needs, so a test can stand fakes in for ombi and the apps. */
+export interface Http {
+  fetch(url: string, init?: { method?: string; headers?: Record<string, string>; body?: string }): Promise<{
+    status: number;
+    text(): Promise<string>;
+  }>;
+}
+
+export interface Ombi {
+  url: string;
+  apiKey: string;
+}
+
+async function ombiCall(http: Http, ombi: Ombi, method: string, path: string, body?: unknown): Promise<unknown> {
+  const res = await http.fetch(`${ombi.url.replace(/\/$/, "")}/api/v1${path}`, {
+    method,
+    headers: {
+      ApiKey: ombi.apiKey,
+      Accept: "application/json",
+      ...(body !== undefined ? { "Content-Type": "application/json" } : {}),
+    },
+    body: body !== undefined ? JSON.stringify(body) : undefined,
+  });
+  const text = await res.text();
+  if (res.status < 200 || res.status >= 300) {
+    // The body is ombi's error, never a request echo, so it carries no key.
+    throw new Error(`ombi ${method} ${path} answered ${res.status}${text ? `: ${text.slice(0, 200)}` : ""}`);
+  }
+  return text ? (JSON.parse(text) as unknown) : undefined;
+}
+
+/**
+ * Does the app take this key? `true` it does, `false` it refused it (401/403), and a thrown error
+ * when it could not be asked — unreachable, or answering something that is neither.
+ */
+export async function appTakes(http: Http, spec: ServarrApp, want: Connection): Promise<boolean> {
+  const res = await http.fetch(`${appUrl(want)}${spec.statusPath}`, {
+    method: "GET",
+    headers: { "X-Api-Key": want.apiKey, Accept: "application/json" },
+  });
+  if (res.status === 401 || res.status === 403) return false;
+  if (res.status >= 200 && res.status < 300) return true;
+  throw new Error(`${spec.app} answered ${res.status} at ${spec.statusPath}`);
+}
+
+/** The remedy for a refused key, in the controller's own words (ADR 0092). */
+export function acceptRemedy(spec: ServarrApp, from: string): string {
+  return (
+    `${spec.app} refuses the ${spec.provision} credential the mesh delivered, so it was not written ` +
+    `into ombi. A Servarr app has one API key and the mesh cannot make it: accept ${spec.app}'s own ` +
+    `key for this pair — \`secret accept <this node> ombi ${spec.provision} --provider ${from || "<its node>"} ` +
+    `--from <file holding ${spec.app}'s ApiKey>\``
+  );
+}
+
+/**
+ * Bring ombi's connection to one app in line with the mesh: check the key against the app, compare,
+ * write only the connection fields when they differ, then have ombi test the connection from its own
+ * container. Never throws: every failure is an outcome with a reason.
+ */
+export async function reconcileApp(
+  http: Http,
+  ombi: Ombi,
+  spec: ServarrApp,
+  binding: Binding | undefined,
+  credential: string | undefined,
+): Promise<Outcome> {
+  const w = wanted(spec, binding, credential);
+  // `in`, not `!w.ok`: the Dockerfile compiles without strict, where a boolean discriminant does not
+  // narrow.
+  if ("problem" in w) return { app: spec.app, result: "refused", problem: w.problem };
+  const want = w.connection;
+
+  try {
+    if (!(await appTakes(http, spec, want))) {
+      return { app: spec.app, result: "refused", problem: acceptRemedy(spec, w.from) };
+    }
+  } catch (err) {
+    return {
+      app: spec.app,
+      result: "refused",
+      problem: `${spec.app} could not be asked whether it takes the key at ${want.ip}:${want.port}: ${message(err)}`,
+    };
+  }
+
+  try {
+    const document = (await ombiCall(http, ombi, "GET", `/Settings/${spec.app}`)) as Record<string, unknown> | undefined;
+    const current = spec.within ? (document?.[spec.within] as Record<string, unknown> | undefined) : document;
+    const fields = differing(current, want);
+    if (fields.length > 0) {
+      const next = withConnection(current, want);
+      const body = spec.within ? { ...(document ?? {}), [spec.within]: next } : next;
+      const saved = await ombiCall(http, ombi, "POST", `/Settings/${spec.app}`, body);
+      if (saved === false) {
+        return { app: spec.app, result: "refused", problem: `ombi declined to save its ${spec.app} settings` };
+      }
+    }
+    // ombi's own test, from ombi's own container — the path the step's check above did not take.
+    const tested = (await ombiCall(http, ombi, "POST", `/Tester/${spec.app}`, withConnection(current, want))) as
+      | { isValid?: boolean; expectedSubDir?: string | null }
+      | undefined;
+    if (!tested?.isValid) {
+      const hint = tested?.expectedSubDir ? ` (ombi expected the base path ${tested.expectedSubDir})` : "";
+      return {
+        app: spec.app,
+        result: "refused",
+        problem:
+          `ombi cannot reach ${spec.app} at ${want.ip}:${want.port} from its own container${hint}` +
+          (fields.length > 0 ? `; its settings were written (${fields.join(", ")})` : ""),
+      };
+    }
+    return fields.length > 0 ? { app: spec.app, result: "written", fields } : { app: spec.app, result: "unchanged" };
+  } catch (err) {
+    return { app: spec.app, result: "refused", problem: message(err) };
+  }
+}
+
+/** Wait for ombi to answer, because the step runs right after its container starts. */
+export async function ombiReady(http: Http, ombi: Ombi, waitMs: number, pauseMs = 2000): Promise<boolean> {
+  const until = Date.now() + waitMs;
+  for (;;) {
+    try {
+      const res = await http.fetch(`${ombi.url.replace(/\/$/, "")}/api/v1/Status`, { method: "GET" });
+      if (res.status === 200) return true;
+    } catch {
+      // not listening yet
+    }
+    if (Date.now() >= until) return false;
+    await new Promise((r) => setTimeout(r, pauseMs));
+  }
+}
+
+/** A file the mesh wrote, or undefined when it is not there. */
+export async function readIfThere(path: string | undefined): Promise<string | undefined> {
+  if (!path) return undefined;
+  return readFile(path, "utf8").catch(() => undefined);
+}
+
+/** A binding file parsed, or undefined when absent or not JSON. */
+export async function readBinding(path: string | undefined): Promise<Binding | undefined> {
+  const raw = await readIfThere(path);
+  if (raw === undefined) return undefined;
+  try {
+    return JSON.parse(raw) as Binding;
+  } catch {
+    return undefined;
+  }
+}
+
+function message(err: unknown): string {
+  return err instanceof Error ? err.message : String(err);
+}
@@ -0,0 +1,147 @@
+// What holds ombi's Servarr step (servarr/settings.ts): the connection ombi keeps for each app is
+// made to say what the mesh bound — host, port, TLS, base path, key — and nothing else it keeps is
+// touched; nothing is written when nothing differs; Radarr's 4K instance is left alone; and a key the
+// app refuses (the mesh's own minted value, before the operator accepts the app's key) is never
+// written, with the `secret accept` that fixes it named.
+//
+// ombi and the apps are fakes: the routes the step touches, answering as the real ones do (checked
+// against lscr.io/linuxserver/ombi 4.53.10 and the catalogue's pinned sonarr/radarr/lidarr).
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+
+import { APPS, differing, reconcileApp, subDirOf, wanted, type Binding, type Http, type ServarrApp } from "../servarr/settings.ts";
+
+const SONARR = APPS.find((a) => a.app === "sonarr") as ServarrApp;
+const RADARR = APPS.find((a) => a.app === "radarr") as ServarrApp;
+const LIDARR = APPS.find((a) => a.app === "lidarr") as ServarrApp;
+const THE_KEY = "the-apps-own-key";
+
+function binding(provision: string, port: number, at = "ace.internal"): Binding {
+  return { binding: 1, provision, from: "ace", at, as: "mesh_ace_ombi", serves: { scheme: "http", port, "url-base": "" } } as Binding;
+}
+
+interface Call {
+  method: string;
+  url: string;
+  body?: unknown;
+}
+
+/** ombi's settings store and the apps' key check, behind one fetch. */
+function fakes(settings: Record<string, unknown>, opts: { appKey?: string; reachable?: boolean } = {}) {
+  const calls: Call[] = [];
+  const appKey = opts.appKey ?? THE_KEY;
+  const http: Http = {
+    async fetch(url, init) {
+      const method = init?.method ?? "GET";
+      const body = init?.body ? (JSON.parse(init.body) as unknown) : undefined;
+      calls.push({ method, url, body });
+      const reply = (status: number, value?: unknown) => ({
+        status,
+        text: async () => (value === undefined ? "" : JSON.stringify(value)),
+      });
+      const u = new URL(url);
+      if (u.pathname.endsWith("/system/status")) {
+        if (opts.reachable === false) throw new Error("connect ECONNREFUSED");
+        return init?.headers?.["X-Api-Key"] === appKey ? reply(200, { version: "4" }) : reply(401);
+      }
+      if (init?.headers?.ApiKey !== "ombi-key") return reply(401);
+      const m = u.pathname.match(/^\/api\/v1\/(Settings|Tester)\/(\w+)$/);
+      if (!m) return reply(404);
+      const [, kind, app] = m;
+      if (kind === "Settings" && method === "GET") return reply(200, settings[app]);
+      if (kind === "Settings" && method === "POST") {
+        settings[app] = body;
+        return reply(200, true);
+      }
+      const tried = body as { apiKey?: string };
+      return reply(200, { isValid: tried.apiKey === appKey, expectedSubDir: null });
+    },
+  };
+  return { http, calls, settings };
+}
+
+const OMBI = { url: "http://127.0.0.1:3579", apiKey: "ombi-key" };
+
+const operatorSonarr = () => ({
+  enabled: true, apiKey: "old-key", qualityProfile: "3", seasonFolders: true, rootPath: "10",
+  qualityProfileAnime: "7", rootPathAnime: "9", languageProfile: 1, ssl: false, subDir: null,
+  ip: "sonarr", port: 8989, id: 5,
+});
+
+test("it writes the connection the mesh bound, and keeps every other setting ombi had", async () => {
+  const f = fakes({ sonarr: operatorSonarr() });
+  const out = await reconcileApp(f.http, OMBI, SONARR, binding("sonarr-api", 20101), `${THE_KEY}\n`);
+  assert.deepEqual(out, { app: "sonarr", result: "written", fields: ["ip", "port", "apiKey"] });
+  assert.deepEqual(f.settings.sonarr, {
+    ...operatorSonarr(), ip: "ace.internal", port: 20101, apiKey: THE_KEY, ssl: false, subDir: null,
+  });
+  // Checked against the app itself, at the bound address, before anything was written.
+  assert.equal(f.calls[0].url, "http://ace.internal:20101/api/v3/system/status");
+});
+
+test("nothing is written when ombi already says what the mesh says", async () => {
+  const f = fakes({ sonarr: { ...operatorSonarr(), ip: "ace.internal", port: 20101, apiKey: THE_KEY } });
+  const out = await reconcileApp(f.http, OMBI, SONARR, binding("sonarr-api", 20101), THE_KEY);
+  assert.deepEqual(out, { app: "sonarr", result: "unchanged" });
+  assert.equal(f.calls.filter((c) => c.method === "POST" && c.url.includes("/Settings/")).length, 0);
+});
+
+test("a key the app refuses is never written, and the accept that fixes it is named", async () => {
+  const f = fakes({ sonarr: operatorSonarr() });
+  const out = await reconcileApp(f.http, OMBI, SONARR, binding("sonarr-api", 20101), "a-value-the-mesh-minted");
+  assert.equal(out.result, "refused");
+  assert.match((out as { problem: string }).problem, /secret accept <this node> ombi sonarr-api --provider ace/);
+  assert.doesNotMatch((out as { problem: string }).problem, /a-value-the-mesh-minted/);
+  assert.deepEqual(f.settings.sonarr, operatorSonarr(), "ombi's working settings were left alone");
+  assert.equal(f.calls.some((c) => c.url.includes("/api/v1/")), false, "ombi was not even asked");
+});
+
+test("an app it cannot reach is reported, and ombi is left alone", async () => {
+  const f = fakes({ sonarr: operatorSonarr() }, { reachable: false });
+  const out = await reconcileApp(f.http, OMBI, SONARR, binding("sonarr-api", 20101), THE_KEY);
+  assert.equal(out.result, "refused");
+  assert.match((out as { problem: string }).problem, /could not be asked.*ECONNREFUSED/);
+  assert.deepEqual(f.settings.sonarr, operatorSonarr());
+});
+
+test("radarr's connection is written inside its combined document, and the 4K instance is untouched", async () => {
+  const fourK = { enabled: true, apiKey: "4k-key", ip: "radarr4k", port: 7879, defaultQualityProfile: "9", id: 7 };
+  const f = fakes({ radarr: { radarr: { enabled: true, apiKey: "old", ip: "radarr", port: 7878, defaultRootPath: "/movies", id: 6 }, radarr4K: fourK } });
+  const out = await reconcileApp(f.http, OMBI, RADARR, binding("radarr-api", 20102), THE_KEY);
+  assert.equal(out.result, "written");
+  const doc = f.settings.radarr as { radarr: Record<string, unknown>; radarr4K: unknown };
+  assert.deepEqual(doc.radarr4K, fourK);
+  assert.equal(doc.radarr.ip, "ace.internal");
+  assert.equal(doc.radarr.port, 20102);
+  assert.equal(doc.radarr.defaultRootPath, "/movies");
+});
+
+test("lidarr is checked on its own API version", async () => {
+  const f = fakes({ lidarr: { enabled: true, apiKey: null, ip: null, port: 0, id: 0 } });
+  const out = await reconcileApp(f.http, OMBI, LIDARR, binding("lidarr-api", 20103), THE_KEY);
+  assert.equal(out.result, "written");
+  assert.equal(f.calls[0].url, "http://ace.internal:20103/api/v1/system/status");
+});
+
+test("a loopback binding is refused: from ombi's container it is ombi itself", () => {
+  const w = wanted(SONARR, binding("sonarr-api", 20101, "127.0.0.1"), THE_KEY);
+  assert.equal(w.ok, false);
+  assert.match((w as { problem: string }).problem, /private network/);
+});
+
+test("the base path is ombi's subDir, slashes trimmed; empty is none", () => {
+  assert.equal(subDirOf(""), null);
+  assert.equal(subDirOf("/sonarr/"), "sonarr");
+  assert.deepEqual(
+    differing({ ip: "h", port: 1, ssl: false, subDir: "", apiKey: "k" }, { ip: "h", port: 1, ssl: false, subDir: null, apiKey: "k" }),
+    [],
+  );
+});
+
+test("an https binding sets ombi's ssl flag", () => {
+  const b = binding("sonarr-api", 443);
+  (b.serves as Record<string, unknown>).scheme = "https";
+  const w = wanted(SONARR, b, THE_KEY);
+  assert.equal(w.ok && w.connection.ssl, true);
+});
@@ -8,5 +8,5 @@
    "skipLibCheck": true,
    "noEmit": true
  },
-  "include": ["client.ts", "index.ts", "tools/index.ts"]
+  "include": ["client.ts", "index.ts", "tools/index.ts", "servarr/settings.ts", "servarr/index.ts"]
 }
@@ -11,7 +11,7 @@
  "contributes": {
    "route": {
      "label": "office",
-      "port": 9070
+      "endpoint": "web"
    }
  },
  "binds": {
@@ -22,6 +22,7 @@
  },
  "listens": [
    {
+      "name": "web",
      "port": 9070,
      "protocol": "tcp",
      "from": "mesh",
@@ -11,7 +11,7 @@
  "contributes": {
    "route": {
      "label": "eef",
-      "port": 4012
+      "endpoint": "web"
    }
  },
  "binds": {
@@ -19,6 +19,7 @@
  },
  "listens": [
    {
+      "name": "web",
      "port": 4012,
      "protocol": "tcp",
      "from": "mesh",
@@ -11,7 +11,7 @@
  "contributes": {
    "route": {
      "label": "filip",
-      "port": 4013
+      "endpoint": "web"
    }
  },
  "binds": {
@@ -19,6 +19,7 @@
  },
  "listens": [
    {
+      "name": "web",
      "port": 4013,
      "protocol": "tcp",
      "from": "mesh",
@@ -18,7 +18,7 @@
    },
    "route": {
      "label": "photos",
-      "port": 4001
+      "endpoint": "web"
    }
  },
  "binds": {
@@ -32,12 +32,14 @@
  },
  "listens": [
    {
+      "name": "api",
      "port": 9000,
      "protocol": "tcp",
      "from": "mesh",
      "why": "the photos backend API; the client sites on the module network call it"
    },
    {
+      "name": "web",
      "port": 4001,
      "protocol": "tcp",
      "from": "mesh",
@@ -18,6 +18,7 @@
  },
  "listens": [
    {
+      "name": "stream",
      "port": 32400,
      "protocol": "tcp",
      "from": "mesh",
@@ -7,12 +7,14 @@
  ],
  "listens": [
    {
+      "name": "web",
      "port": 9090,
      "protocol": "tcp",
      "from": "mesh",
      "why": "the dashboard over http; portainer.novox.be is a route grant and the proxy reaches it here \u2014 the machine side of 9090:9000, the predecessor's number"
    },
    {
+      "name": "web-tls",
      "port": 9443,
      "protocol": "tcp",
      "from": "mesh",
@@ -103,7 +105,7 @@
  "contributes": {
    "route": {
      "label": "portainer",
-      "port": 9090
+      "endpoint": "web"
    }
  },
  "binds": {
@@ -26,6 +26,7 @@
  ],
  "listens": [
    {
+      "name": "database",
      "port": 5432,
      "protocol": "tcp",
      "from": "mesh",
@@ -16,6 +16,7 @@
  },
  "listens": [
    {
+      "name": "web",
      "port": 8080,
      "protocol": "tcp",
      "from": "mesh",
@@ -81,7 +82,7 @@
      ],
      "env": {
        "MESH_BROKER_FILE": "/run/secrets/broker",
-        "MESH_QBITTORRENT_URL": "http://127.0.0.1:8080",
+        "MESH_QBITTORRENT_URL": "http://127.0.0.1:${port:8080}",
        "MESH_QBITTORRENT_PASSWORD_FILE": "/run/secrets/password",
        "MESH_QBITTORRENT_CONFIG_FILE": "/run/config/config.json",
        "MESH_QBITTORRENT_CONFIG_DIR": "/var/lib/qbittorrent/config"
@@ -1,6 +1,19 @@
 {
  "module": "radarr",
  "version": "1",
+  "provides": [
+    {
+      "name": "radarr-api",
+      "scope": "mesh"
+    }
+  ],
+  "serves": {
+    "radarr-api": {
+      "scheme": "http",
+      "port": 7878,
+      "url-base": ""
+    }
+  },
  "capabilities": [
    "container-runtime"
  ],
@@ -14,6 +27,7 @@
  },
  "listens": [
    {
+      "name": "web",
      "port": 7878,
      "protocol": "tcp",
      "from": "mesh",
@@ -74,7 +88,7 @@
      ],
      "env": {
        "MESH_BROKER_FILE": "/run/secrets/broker",
-        "MESH_RADARR_URL": "http://127.0.0.1:7878",
+        "MESH_RADARR_URL": "http://127.0.0.1:${port:7878}",
        "MESH_RADARR_CONFIG_DIR": "/var/lib/radarr/config"
      },
      "artifact": "runtime"
@@ -86,7 +100,7 @@
  "contributes": {
    "route": {
      "label": "movies",
-      "port": 7878
+      "endpoint": "web"
    }
  },
  "binds": {
@@ -40,6 +40,7 @@
  },
  "listens": [
    {
+      "name": "cache",
      "port": 6379,
      "protocol": "tcp",
      "from": "mesh",
@@ -27,12 +27,14 @@
  },
  "listens": [
    {
+      "name": "http",
      "port": 80,
      "protocol": "tcp",
      "from": "anywhere",
      "why": "public HTTP, and the ACME HTTP-01 challenge answered at the name being certified"
    },
    {
+      "name": "https",
      "port": 443,
      "protocol": "tcp",
      "from": "anywhere",
@@ -5,11 +5,12 @@
    "container-runtime"
  ],
  "own-secrets": {
-    "secret": "/var/lib/searxng-module/secret.secret",
+    "secret": "/var/lib/mesh/searxng/secret",
    "broker": "/var/lib/mesh/searxng/broker"
  },
  "listens": [
    {
+      "name": "web",
      "port": 8080,
      "protocol": "tcp",
      "from": "mesh",
@@ -26,22 +27,14 @@
    {
      "id": "state",
      "type": "directory",
-      "path": "/var/lib/searxng-module",
-      "mode": "0700"
+      "mode": "0700",
+      "place": "."
    },
    {
      "id": "valkey-data",
      "type": "directory",
-      "path": "/var/lib/searxng-module/valkey-data",
      "mode": "0700"
    },
-    {
-      "id": "server-env",
-      "type": "file",
-      "path": "/var/lib/searxng-module/server.env",
-      "mode": "0600",
-      "content": "SEARXNG_SECRET=${secret:secret}\nSEARXNG_VALKEY_URL=valkey://valkey:6379/0\n"
-    },
    {
      "id": "net",
      "type": "network",
@@ -62,30 +55,39 @@
        "warning"
      ],
      "volumes": [
-        "/var/lib/searxng-module/valkey-data:/data"
+        "${dir:valkey-data}:/data"
      ]
    },
+    {
+      "id": "settings",
+      "type": "file",
+      "path": "${dir:state}/settings.yml",
+      "mode": "0600",
+      "merge": "json",
+      "content": "{\n  \"use_default_settings\": true,\n  \"server\": {\n    \"secret_key\": \"${secret:secret}\",\n    \"base_url\": false,\n    \"limiter\": false,\n    \"image_proxy\": false,\n    \"public_instance\": false\n  },\n  \"search\": {\n    \"formats\": [\"html\", \"json\"]\n  },\n  \"valkey\": {\n    \"url\": \"valkey://valkey:6379/0\"\n  }\n}\n"
+    },
    {
      "id": "server",
      "type": "container",
      "name": "searxng",
-      "image": "searxng/searxng@sha256:c7cc75852051bf6254afda6ed1b920dd1677d8efe4ab141bf558f02e582f4371",
+      "image": "searxng/searxng@sha256:cd8812607ab73730a0b1a0dc4990223fe1b9e383f6f35947114d0bef7f8bb441",
      "network": "searxng",
-      "env-file": [
-        "/var/lib/searxng-module/server.env"
-      ],
      "ports": [
        "8080"
      ],
-      "secrets-in-environment": "SEARXNG_SECRET is env-only, but settings.yml carries server.secret_key; convertible by mounting a generated settings.yml, not yet done"
+      "volumes": [
+        "${dir:state}/settings.yml:/etc/searxng/settings.yml:ro"
+      ],
+      "restart-on": [
+        "settings"
+      ]
    },
    {
      "id": "runtime-config",
      "type": "file",
      "path": "/var/lib/mesh/searxng/config.json",
      "mode": "0600",
-      "content": "{}\n",
-      "merge": "json"
+      "content": "{}\n"
    },
    {
      "id": "runtime",
@@ -98,7 +100,7 @@
      ],
      "env": {
        "MESH_BROKER_FILE": "/run/secrets/broker",
-        "MESH_SEARXNG_URL": "http://127.0.0.1:8080",
+        "MESH_SEARXNG_URL": "http://127.0.0.1:${port:8080}",
        "MESH_SEARXNG_CONFIG_FILE": "/run/config/config.json"
      },
      "restart-on": [
@@ -113,11 +115,11 @@
  "contributes": {
    "route": {
      "label": "searxng",
-      "port": 8080
+      "endpoint": "web"
    }
  },
  "binds": {
-    "route": "/var/lib/searxng-module/route.json"
+    "route": "${dir:state}/route.json"
  },
  "build": {
    "on": [
@@ -43,6 +43,7 @@
  ],
  "listens": [
    {
+      "name": "web",
      "port": 8080,
      "protocol": "tcp",
      "from": "mesh",
@@ -1,6 +1,19 @@
 {
  "module": "sonarr",
  "version": "1",
+  "provides": [
+    {
+      "name": "sonarr-api",
+      "scope": "mesh"
+    }
+  ],
+  "serves": {
+    "sonarr-api": {
+      "scheme": "http",
+      "port": 8989,
+      "url-base": ""
+    }
+  },
  "capabilities": [
    "container-runtime"
  ],
@@ -14,6 +27,7 @@
  },
  "listens": [
    {
+      "name": "web",
      "port": 8989,
      "protocol": "tcp",
      "from": "mesh",
@@ -79,7 +93,7 @@
      ],
      "env": {
        "MESH_BROKER_FILE": "/run/secrets/broker",
-        "MESH_SONARR_URL": "http://127.0.0.1:8989",
+        "MESH_SONARR_URL": "http://127.0.0.1:${port:8989}",
        "MESH_SONARR_CONFIG_DIR": "/var/lib/sonarr/config"
      },
      "artifact": "runtime"
@@ -91,7 +105,7 @@
  "contributes": {
    "route": {
      "label": "series",
-      "port": 8989
+      "endpoint": "web"
    }
  },
  "binds": {
@@ -7,6 +7,7 @@
  ],
  "listens": [
    {
+      "name": "ssh",
      "port": 22,
      "protocol": "tcp",
      "from": "anywhere",
@@ -26,6 +26,7 @@
  },
  "listens": [
    {
+      "name": "acme",
      "port": 9000,
      "protocol": "tcp",
      "from": "mesh",
@@ -12,6 +12,7 @@
  ],
  "listens": [
    {
+      "name": "web",
      "port": 8181,
      "protocol": "tcp",
      "from": "mesh",
@@ -85,7 +86,7 @@
  "contributes": {
    "route": {
      "label": "tautulli",
-      "port": 8181
+      "endpoint": "web"
    }
  },
  "binds": {
@@ -15,7 +15,7 @@
    },
    "route": {
      "label": "umami",
-      "port": 3000
+      "endpoint": "web"
    }
  },
  "binds": {
@@ -49,10 +49,11 @@
  },
  "listens": [
    {
+      "name": "web",
      "port": 3000,
      "protocol": "tcp",
-      "from": "anywhere",
-      "why": "one port serves two surfaces: the dashboard (the proxy gates it to the mesh) and the public collection endpoint that the browsers of every tracked site POST to \u2014 so the port itself must be reachable from anywhere"
+      "from": "mesh",
+      "why": "one port serves two surfaces \u2014 the dashboard and the collection endpoint that the browsers of every tracked site POST to. Both are reached through the proxy, by name, so the port is how the proxy reaches this module and nothing else (novox/hq ADR 0045). It said \"anywhere\" and gave the reason that the collection endpoint must be public, which is true of the name and not of the port: opened, the machine-side port served the dashboard over plain HTTP to the internet, bypassing every rule the proxy applies by path"
    }
  ],
  "resources": [
@@ -6,54 +6,63 @@
  ],
  "listens": [
    {
+      "name": "web",
      "port": 8443,
      "protocol": "tcp",
      "from": "mesh",
      "why": "the controller web UI, over its own self-signed tls; reaching it from outside is a route grant later"
    },
    {
+      "name": "inform",
      "port": 8080,
      "protocol": "tcp",
      "from": "mesh",
      "why": "device inform \u2014 how APs and switches check in and are adopted"
    },
    {
+      "name": "stun",
      "port": 3478,
      "protocol": "udp",
      "from": "mesh",
      "why": "STUN, so managed devices can find the controller through NAT"
    },
    {
+      "name": "discovery",
      "port": 10001,
      "protocol": "udp",
      "from": "mesh",
      "why": "device discovery \u2014 the controller finds unadopted devices on the network"
    },
    {
+      "name": "discovery-l2",
      "port": 1902,
      "protocol": "udp",
      "from": "mesh",
      "why": "layer-2 (UBNT) discovery broadcasts; published on 1902, the container listens on 1900"
    },
    {
+      "name": "portal-tls",
      "port": 8843,
      "protocol": "tcp",
      "from": "mesh",
      "why": "the guest captive portal over https"
    },
    {
+      "name": "portal",
      "port": 8880,
      "protocol": "tcp",
      "from": "mesh",
      "why": "the guest captive portal over http"
    },
    {
+      "name": "speedtest",
      "port": 6789,
      "protocol": "tcp",
      "from": "mesh",
      "why": "mobile-app speed-test throughput measurement"
    },
    {
+      "name": "syslog",
      "port": 5514,
      "protocol": "udp",
      "from": "mesh",
Author	SHA1	Message	Date
jschoubben	f14c763463	ombi: reach sonarr, radarr and lidarr through the mesh ombi keeps its Servarr connections in its own database, so the mesh has no file to write them into. A run-once step reads the three bindings and pair credentials and writes host, port, TLS, base path and key into ombi through ombi's own API - only when they differ, and nothing else ombi keeps. Until the operator accepts an app's key for this pair the mesh delivers a value it minted, which no Servarr app accepts. The step tries the key against the app first and, refused, writes nothing and fails naming the secret accept that fixes it, so the old working key in ombi is never replaced by a dead one. Declared last so its failing gates nothing else of ombi (ADR 0136), and restart-on its six inputs so it runs again when a provider moves (ADR 0099).	2026-09-30 00:39:19 +02:00
jschoubben	ab44ff02e1	sonarr, radarr, lidarr: provide their API to the mesh A consumer on another machine (ombi first; jackett, bazarr and home-assistant later) reached these by container name on HAL's shared network, which the mesh does not have. Each app now provides <app>-api at mesh scope and serves the software port, so the mesh tells a consumer where it is and redirects the port to where the machine published it. Named per app, not one servarr-api: a requirement is matched by name and answered by exactly one provider per node, so a consumer cannot require one name from three providers - and ombi's code is written against each app's own API version (ADR 0027). No grants and no provisioner: a Servarr instance has one API key, which the mesh cannot mint. The operator accepts it as the pair credential for each consumer (ADR 0092).	2026-09-30 00:39:19 +02:00
jschoubben	c4c44efb1b	Merge remote-tracking branch 'origin/fix/sidecars-dial-the-port-they-were-given' into feat/servarr-api-provision	2026-09-30 00:25:55 +02:00
jschoubben	5cc6258326	Sidecars dial the port they were given, not the software's A host-network sidecar reaches its service over the machine's loopback, and the mesh publishes that service on a machine port it assigns (ADR 0038) — so dialling the software's port reaches whatever else holds it. On ace, searxng's sidecar dialled 127.0.0.1:8080 and got unifi's inform port. The same shape in bazarr, bookshelf, lidarr, nzbget, qbittorrent, radarr and sonarr; each now asks with ${port:N} (hq 088). Found in review of ace's module preparation.	2026-09-29 23:50:19 +02:00
jschoubben	21f5301268	ombi: its config is placed, its image is the one ace runs ombi's definition named /services/ombi/config (a HAL machine path) in three places and pinned an image older than the one ace runs. Ombi migrates its own SQLite schema, so a take onto the older pin (v4.53.10-ls267) would start it on a database the newer build (ls269) already touched. - config is a pathless placed directory, mounted as ${dir:config} - a state directory placed at the assignment root carries route.json - image pinned to the digest ace runs today (v4.53.10-ls269) - the sidecar reaches ombi on the machine port the mesh assigns (${port:3579}) rather than assuming 3579 is free - the sidecar no longer mounts ombi's data directory: MESH_OMBI_CONFIG_DIR is read by no code, and the mount exposed the databases for nothing Verified: catalogue tests (MESH_CATALOGUE set, 6 pass, none skipped); the pinned image starts as PUID 1000 in a 0700 dir and answers /api/v1/Status 200; data owned 1001:2000 (ace's media ids) under a 1000:1000 dir is re-owned by the image's init and serves 200; a minted ApiKey is refused (401) - the api-key secret must be accepted from ombi's own settings.	2026-09-29 23:38:56 +02:00
mesh-admin	8064e5da8f	Merge pull request 'searxng: its settings are a file the mesh writes, not the image's defaults' (#143 ) from feat/searxng-settings-as-a-file into main	2026-09-29 20:45:13 +00:00
jschoubben	63a255c5cb	searxng: bind its route where its state now lives The route binding still named /var/lib/searxng-module, the directory the previous commit placed elsewhere — the host would have written it into a directory nothing declares. Same shape as gitea and nextcloud.	2026-09-29 22:41:56 +02:00
jschoubben	7ad1fbd5c6	searxng: its settings are a file the mesh writes, not the image's defaults The module ran searxng on the image's built-in settings, which serve html only — so the module's own search tool (format=json) was refused by the software it fronts. And there was no way to configure it per machine: the only file settings reach was the sidecar's. settings.yml is now the module's one mergeable file (JSON is YAML): generic defaults in the manifest (json format on, limiter and image proxy off, valkey wired), and whatever differs per machine — base_url, method, autocomplete, suspended times — set as the assignment's settings. The secret key is filled on the machine through ${secret:secret}, so the secrets-in-environment exception and the env file go. Directories are placed. Image pinned to 2026.9.20, what ace runs today (the old pin was older, 2026.9.1). The sidecar's config.json is no longer mergeable: settings merge into every mergeable file of a module, and the sidecar would have received searxng's keys. It only ever read an optional url, which its env already carries. Verified on ace: the pinned image serves html and json from a read-only, root-owned 0600 JSON settings.yml.	2026-09-29 22:33:38 +02:00
jschoubben	67f5f4cffd	Merge pull request 'ca-trust: a machine trusts the mesh's authority because a module put its root there' (#142 ) from feat/ca-trust into main	2026-09-29 14:06:36 +00:00
jschoubben	8797335fbc	ca-trust: a machine trusts the mesh's authority because a module put its root there novox/hq ADR 0147, issue 129. Every internal HTTPS name fails verification on every machine: the certificates are genuine and nothing on a machine has ever been told what issued them. The proxy's fetch answers for the proxy and for nothing else — a browser, git over HTTPS and every module calling another by an internal name read the machine's own trust store. The module requires internal-acme-ca, fetches the root over the mesh's own network (no prior trust to have; that is what this establishes), installs it among the machine's anchors and refreshes the extracted bundles. Being unassigned stops the unit, and stopping it takes the anchor away and refreshes them again. Arch's layout is named out loud: a machine that keeps anchors elsewhere fails visibly rather than writing a file nothing reads.	2026-09-29 15:07:40 +02:00
mesh-admin	53dc108603	Merge pull request 'Remove the network-checker module: it does not do what was decided' (#141 ) from chore/remove-the-network-checker-module into main	2026-09-29 12:43:34 +00:00
jschoubben	ebf5ba2d4c	Remove the network-checker module: it does not do what was decided What was in the catalogue was the first thing I built, not the thing ADR 0146 describes. It dialled raw ports on machine addresses from one hosting form and emitted nothing, so findings would have sat in a file on the machine — the exact thing issue 145 is about. It was never registered, never assigned, and never ran. 0146 says names per hosting form, fetched over TLS with the certificate verified, and machines discovered over the bus. That shares nothing with this but the word checker, so it goes rather than being bent into shape. Recorded as work to be analysed and built deliberately. Connectivity is checked by hand in the meantime, against the services the mesh already runs.	2026-09-29 14:43:25 +02:00
mesh-admin	bbac08a7d2	Merge pull request 'A network-checker module: dial what the mesh claims, from where the callers are' (#140 ) from feat/a-network-checker-module into main	2026-09-29 11:44:37 +00:00
jschoubben	784a5a6514	A network-checker module: dial what the mesh claims, from where the callers are The mesh asserts three things are callable (ADR 0144) — what runs on the same machine, another machine's service exposed to the private network, and another machine's service exposed publicly — and has never checked any of them. The first was broken for eleven hours while the mesh reported every machine healthy. This runs on every machine, on the cadence the mesh already has, in its own container: the same position every other module calls from. Not the host and not the control plane, both of which reach these addresses by paths no ordinary caller uses and would have passed throughout that outage. Its probe is its own endpoint, and that is the point. Declared reachable over the private network like any other service, so it is admitted by exactly the rule that governs every internally-exposed service and fails when that rule is wrong. The tempting target is a service every machine has, and those are the ones never closed — ssh above all — which would have passed while the thing that actually broke was a service exposed to the private network. It resolves before it dials and says which failed, because a name that does not resolve and a port that does not answer have different owners. One failure is not a fault: a machine rebooting is ordinary, so a path is broken after consecutive runs and the count travels with the result. It reports and repairs nothing. novox/hq ADR 0145. Eight tests; the consecutive-failure logic proved by reverting it once. Not yet registered or assigned.	2026-09-29 13:44:16 +02:00
mesh-admin	0c31499fb0	Merge pull request 'Every module names its endpoints, and every route names the one it serves' (#139 ) from feat/modules-name-their-endpoints into main	2026-09-29 09:51:56 +00:00
jschoubben	f118344246	Every module names its endpoints, and every route names the one it serves 75 endpoints across 50 modules, named from what each one is for rather than by a rule: mail's seven protocol ports are smtp, imaps, submission and the rest; unifi's nine are inform, stun, discovery, the two portal ports and syslog; minio's two are s3 and console; the resolver's two are dns-udp and dns-tcp. And 35 route contributions name the endpoint they serve instead of repeating its port. A route and a listen both carried a port and nothing said they were the same thing; now one of them does. gitea's path-level deny rule names neither, because it is a rule about a name rather than an endpoint. novox/hq ADR 0138. The words shipped a release ahead in mesh-controller #138 and #139, and the control plane running today is built from that merge — checked before this was written, because an unknown manifest key is refused and a catalogue using one against an older control plane would stop resolving.	2026-09-29 11:51:39 +02:00
mesh-admin	822df220ab	Merge pull request 'A routed module listens from the mesh, not from anywhere' (#138 ) from fix/a-routed-module-listens-from-the-mesh into main	2026-09-29 00:58:39 +00:00
jschoubben	9eb1265bc8	A routed module listens from the mesh, not from anywhere umami declared its port reachable from anywhere, reasoning that the collection endpoint tracked browsers POST to must be public. That is true of the name and not of the port: both its surfaces are served through the proxy by name, so the port is how the proxy reaches it and nothing else (ADR 0045). Measured, which is how this was found: with the port open to the internet, the dashboard's login page was served over plain HTTP directly on the machine's port, bypassing every rule the proxy applies by path. The route stays exactly as it was, so the collection endpoint keeps working.	2026-09-29 02:54:10 +02:00
mesh-admin	41cfc70b53	Merge pull request 'The resolver declares both protocols it answers on' (#137 ) from fix/the-resolver-declares-both-protocols into main	2026-09-28 22:04:19 +00:00