feat(gallery): default to index.localai.io with GitHub as a mirror (#11409)

The primary is a caching mirror of the same two files, so an install
resolves its gallery from infrastructure the project controls. The GitHub
URI stays as a mirror, so behaviour is unchanged whenever the primary is
unreachable.

Docs and agent guides that either state the shipped defaults or hand out a
copy-pasteable gallery list are updated to match, so following them no
longer silently demotes an install off the new primary.

Assisted-by: Claude:claude-opus-5 [go vet] [go test] [golangci-lint]

Co-authored-by: Ettore Di Giacinto <mudler@localai.io>

.agents/backend-signing.md

@@ -67,7 +67,9 @@ entry (`backend/index.yaml`):
 
 ```yaml
 - name: localai
-  url: github:mudler/LocalAI/backend/index.yaml@master
+  url: https://index.localai.io/backends
+  mirrors:
+    - github:mudler/LocalAI/backend/index.yaml@master
   verification:
     issuer: "https://token.actions.githubusercontent.com"
     identity_regex: "^https://github\\.com/mudler/LocalAI/\\.github/workflows/backend_merge\\.yml@refs/(heads/master|tags/.+)$"

.agents/ci-caching.md

@@ -198,7 +198,7 @@ Two properties this relies on:
 
 The same reasoning applies to master pushes, and the volume is larger there: on 2026-07-30, **12 of the 23 queued `image.yml` runs** were commits like "add 1 new model to gallery" or a docs fix, each rebuilding all 18 container images.
 
-`image.yml` now has a `changes` job that decides once whether the push can affect any image; the other 11 jobs carry `needs: changes` plus an `if:` on its output. Verified against the shipped `Dockerfile`: the final stage copies only `entrypoint.sh`, `healthcheck.sh` and the `local-ai` binary, there is no `go:embed` of `gallery/` or `docs/`, and the gallery is fetched at runtime from `github:mudler/LocalAI/gallery/index.yaml@master`. A gallery-only commit therefore produces byte-identical images, and the gallery change reaches users through GitHub immediately whether or not an image is rebuilt.
+`image.yml` now has a `changes` job that decides once whether the push can affect any image; the other 11 jobs carry `needs: changes` plus an `if:` on its output. Verified against the shipped `Dockerfile`: the final stage copies only `entrypoint.sh`, `healthcheck.sh` and the `local-ai` binary, there is no `go:embed` of `gallery/` or `docs/`, and the gallery is fetched at runtime from `https://index.localai.io/models` (a caching mirror of `gallery/index.yaml` on master, with `github:mudler/LocalAI/gallery/index.yaml@master` as the fallback mirror). A gallery-only commit therefore produces byte-identical images, and the gallery change reaches users over the network immediately whether or not an image is rebuilt.
 
 Two properties to preserve if you touch it:
 

core/config/runtime_settings_startup.go

@@ -12,8 +12,13 @@ import (
 // the "${galleries}" / "${backends}" vars, and DefaultRuntimeBaseline uses
 // them to tell "kong default" apart from "user-configured" at settings-load
 // time - they must stay the single source for both.
-const DefaultGalleriesJSON = `[{"name":"localai", "url":"github:mudler/LocalAI/gallery/index.yaml@master"}]`
-const DefaultBackendGalleriesJSON = `[{"name":"localai", "url":"github:mudler/LocalAI/backend/index.yaml@master"}]`
+//
+// The primary is served by index-server (github.com/localai-org/index-server),
+// a caching mirror of the files below. The GitHub URI stays as a mirror so an
+// install still resolves its gallery unchanged whenever the primary is
+// unreachable - see the fallback chain in core/gallery/gallery_mirrors.go.
+const DefaultGalleriesJSON = `[{"name":"localai", "url":"https://index.localai.io/models", "mirrors":["github:mudler/LocalAI/gallery/index.yaml@master"]}]`
+const DefaultBackendGalleriesJSON = `[{"name":"localai", "url":"https://index.localai.io/backends", "mirrors":["github:mudler/LocalAI/backend/index.yaml@master"]}]`
 
 func mustGalleries(jsonList string) []Gallery {
 	var g []Gallery

core/config/runtime_settings_startup_test.go

@@ -0,0 +1,83 @@
+package config_test
+
+import (
+	"encoding/json"
+
+	"github.com/mudler/LocalAI/core/config"
+
+	. "github.com/onsi/ginkgo/v2"
+	. "github.com/onsi/gomega"
+)
+
+var _ = Describe("default galleries", func() {
+	It("serves the model gallery from index.localai.io with GitHub as a mirror", func() {
+		var galleries []config.Gallery
+		Expect(json.Unmarshal([]byte(config.DefaultGalleriesJSON), &galleries)).To(Succeed())
+		Expect(galleries).To(HaveLen(1))
+		Expect(galleries[0].Name).To(Equal("localai"))
+		Expect(galleries[0].URL).To(Equal("https://index.localai.io/models"))
+		Expect(galleries[0].Mirrors).To(Equal([]string{"github:mudler/LocalAI/gallery/index.yaml@master"}))
+	})
+
+	It("serves the backend gallery from index.localai.io with GitHub as a mirror", func() {
+		var galleries []config.Gallery
+		Expect(json.Unmarshal([]byte(config.DefaultBackendGalleriesJSON), &galleries)).To(Succeed())
+		Expect(galleries).To(HaveLen(1))
+		Expect(galleries[0].Name).To(Equal("localai"))
+		Expect(galleries[0].URL).To(Equal("https://index.localai.io/backends"))
+		Expect(galleries[0].Mirrors).To(Equal([]string{"github:mudler/LocalAI/backend/index.yaml@master"}))
+	})
+
+	// The mirror is the whole reason this default is safe to ship: if
+	// index.localai.io is unreachable, an install must still resolve its
+	// gallery from GitHub exactly as it did before.
+	It("always leaves a reachable fallback behind the primary", func() {
+		for _, raw := range []string{config.DefaultGalleriesJSON, config.DefaultBackendGalleriesJSON} {
+			var galleries []config.Gallery
+			Expect(json.Unmarshal([]byte(raw), &galleries)).To(Succeed())
+			for _, g := range galleries {
+				Expect(g.Mirrors).ToNot(BeEmpty(), "default %q has no mirror", g.Name)
+			}
+		}
+	})
+
+	// mustGalleries panics on malformed JSON, and these constants are also
+	// fed to kong as defaults, so a typo would be a startup crash rather
+	// than a config error.
+	It("parses through the same path startup uses", func() {
+		baseline := config.DefaultRuntimeBaseline()
+		Expect(baseline.Galleries).To(HaveLen(1))
+		Expect(baseline.BackendGalleries).To(HaveLen(1))
+		Expect(baseline.Galleries[0].URL).To(Equal("https://index.localai.io/models"))
+		Expect(baseline.BackendGalleries[0].URL).To(Equal("https://index.localai.io/backends"))
+	})
+
+	// The baseline decides "kong default" vs "user-configured", and since
+	// the defaults grew a Mirrors slice that comparison runs through
+	// GalleriesEqual rather than ==. A default install must still let the
+	// persisted file apply, and any override - including one that differs
+	// from the default only by its mirrors - must still be seen as env-set.
+	Context("as the option-less startup baseline", func() {
+		It("treats an untouched default list as not env-set, so the file applies", func() {
+			o := config.DefaultRuntimeBaseline()
+			saved := []config.Gallery{{Name: "mine", URL: "https://example.com/index.yaml"}}
+			savedBackends := []config.Gallery{{Name: "mine-backends", URL: "https://example.com/backends.yaml"}}
+			o.ApplyRuntimeSettingsAtStartup(&config.RuntimeSettings{
+				Galleries:        &saved,
+				BackendGalleries: &savedBackends,
+			})
+			Expect(o.Galleries).To(Equal(saved))
+			Expect(o.BackendGalleries).To(Equal(savedBackends))
+		})
+
+		It("treats LOCALAI_GALLERIES as env-set even when it only drops the mirror", func() {
+			o := config.DefaultRuntimeBaseline()
+			// Same primary as the default, mirror removed: env-set.
+			o.Galleries = []config.Gallery{{Name: "localai", URL: "https://index.localai.io/models"}}
+			saved := []config.Gallery{{Name: "file", URL: "https://file.example/index.yaml"}}
+			o.ApplyRuntimeSettingsAtStartup(&config.RuntimeSettings{Galleries: &saved})
+			Expect(o.Galleries[0].Name).To(Equal("localai"),
+				"an env list differing only by mirrors must still win over the file")
+		})
+	})
+})

docs/content/features/backends.md

@@ -79,7 +79,7 @@ they provide. Add a `verification` policy to the gallery configuration, then
 enable strict integrity mode:
 
 ```bash
-export LOCALAI_BACKEND_GALLERIES='[{"name":"localai","url":"github:mudler/LocalAI/backend/index.yaml@master","verification":{"issuer":"https://token.actions.githubusercontent.com","identity_regex":"^https://github\\.com/mudler/LocalAI/\\.github/workflows/backend_merge\\.yml@refs/(heads/master|tags/.+)$"}}]'
+export LOCALAI_BACKEND_GALLERIES='[{"name":"localai","url":"https://index.localai.io/backends","mirrors":["github:mudler/LocalAI/backend/index.yaml@master"],"verification":{"issuer":"https://token.actions.githubusercontent.com","identity_regex":"^https://github\\.com/mudler/LocalAI/\\.github/workflows/backend_merge\\.yml@refs/(heads/master|tags/.+)$"}}]'
 export LOCALAI_REQUIRE_BACKEND_INTEGRITY=1
 local-ai run
 ```

docs/content/features/model-gallery.md

@@ -100,13 +100,13 @@ To use additional repositories you need to start `local-ai` with the `GALLERIES`
 GALLERIES=[{"name":"<GALLERY_NAME>", "url":"<GALLERY_URL"}]
 ```
 
-For example, to enable the default `localai` repository, you can start `local-ai` with:
+For example, to spell out the default `localai` repository, you can start `local-ai` with:
 
 ```
-GALLERIES=[{"name":"localai", "url":"github:mudler/localai/gallery/index.yaml"}]
+GALLERIES=[{"name":"localai", "url":"https://index.localai.io/models", "mirrors":["github:mudler/LocalAI/gallery/index.yaml@master"]}]
 ```
 
-where `github:mudler/localai/gallery/index.yaml` will be expanded automatically to `https://raw.githubusercontent.com/mudler/LocalAI/main/index.yaml`.
+`https://index.localai.io/models` is a caching mirror of the same index file, and the `github:` entry is the fallback used whenever it cannot be reached. `github:mudler/LocalAI/gallery/index.yaml@master` is expanded automatically to `https://raw.githubusercontent.com/mudler/LocalAI/master/gallery/index.yaml`.
 
 Note: the url are expanded automatically for `github` and `huggingface`, however `https://` and `http://` prefix works as well.
 

docs/content/features/runtime-settings.md

@@ -148,13 +148,15 @@ The `runtime_settings.json` file follows this structure:
   "federated": false,
   "galleries": [
     {
-      "url": "github:mudler/LocalAI/gallery/index.yaml@master",
+      "url": "https://index.localai.io/models",
+      "mirrors": ["github:mudler/LocalAI/gallery/index.yaml@master"],
       "name": "localai"
     }
   ],
   "backend_galleries": [
     {
-      "url": "github:mudler/LocalAI/backend/index.yaml@master",
+      "url": "https://index.localai.io/backends",
+      "mirrors": ["github:mudler/LocalAI/backend/index.yaml@master"],
       "name": "localai"
     }
   ],