feat(branding): admin-configurable instance name, tagline, and assets (mudler#9635)

Adds a whitelabeling feature so an operator can replace the LocalAI
instance name, tagline, square logo, horizontal logo, and favicon from
the admin Settings page. Defaults fall back to the bundled assets so
existing installs are unaffected.

The public GET /api/branding endpoint is reachable pre-auth so the
login screen can render the configured branding before sign-in.
Mutating routes (POST/DELETE /api/branding/asset/:kind) remain
admin-only. Text fields (instance_name, instance_tagline) ride the
existing /api/settings flow; binary assets get a dedicated multipart
upload route that persists files under DynamicConfigsDir/branding/.

To prevent the Settings page's stale local state from clobbering an
upload on save, UpdateSettingsEndpoint preserves whatever the on-disk
asset filename fields are regardless of the body — /api/branding/asset/*
are the sole writers for those fields.

The MCP catalog gains get_branding and set_branding tools (text fields
only; file upload stays UI-only) plus a configure_branding skill prompt.

While wiring this up, the same restart-loss class of bug surfaced for
several existing fields whose RuntimeSettings entries were never read
by the startup loader. Fix loadRuntimeSettingsFromFile() to load:

  - branding (instance_name, instance_tagline, *_file basenames)
  - auto_upgrade_backends, prefer_development_backends
  - localai_assistant_enabled
  - open_responses_store_ttl
  - the 7 existing AgentPool fields (enabled, default/embedding model,
    chunking sizes, enable_logs, collection_db_path)

Also exposes 3 new AgentPool runtime settings (vector_engine,
database_url, agent_hub_url) via /api/settings + the Settings UI, with
the same load-on-startup wiring. The file watcher's manual-edit path
is intentionally not changed — the in-process API endpoints already
update appConfig directly, so the watcher is redundant for supported
flows and a separate refactor for everything else.

15 TDD specs cover the loader behaviour (1 branding + 11 adjacent + 3
new agent-pool); 2 specs cover the persistence helpers and the
clobber-prevention contract.


Assisted-by: claude-code:claude-opus-4-7

Signed-off-by: Ettore Di Giacinto <mudler@localai.io>

Author: mudler

core/application/application_suite_test.go

@@ -0,0 +1,13 @@
+package application
+
+import (
+	"testing"
+
+	. "github.com/onsi/ginkgo/v2"
+	. "github.com/onsi/gomega"
+)
+
+func TestApplication(t *testing.T) {
+	RegisterFailHandler(Fail)
+	RunSpecs(t, "Application test suite")
+}

core/application/runtime_settings_branding_test.go

@@ -0,0 +1,171 @@
+package application
+
+import (
+	"os"
+	"path/filepath"
+	"time"
+
+	. "github.com/onsi/ginkgo/v2"
+	. "github.com/onsi/gomega"
+
+	"github.com/mudler/LocalAI/core/config"
+)
+
+// seedSettings writes the given JSON fragment to runtime_settings.json
+// under a fresh temp DynamicConfigsDir and returns the directory path.
+func seedSettings(json string) string {
+	dir := GinkgoT().TempDir()
+	Expect(os.WriteFile(filepath.Join(dir, "runtime_settings.json"), []byte(json), 0o600)).To(Succeed())
+	return dir
+}
+
+var _ = Describe("loadRuntimeSettingsFromFile", func() {
+	// Reproduces the "settings revert after restart" report: an admin
+	// sets a branding instance name + uploads a logo, the values are
+	// persisted to runtime_settings.json, but on the next startup
+	// loadRuntimeSettingsFromFile() did not read those fields back so
+	// appConfig.Branding stayed zero and the public /api/branding
+	// endpoint fell back to LocalAI defaults.
+	Describe("branding fields", func() {
+		It("loads instance name, tagline, and asset basenames", func() {
+			dir := seedSettings(`{
+                "instance_name": "Acme AI",
+                "instance_tagline": "Private inference",
+                "logo_file": "logo.png",
+                "logo_horizontal_file": "logo_horizontal.svg",
+                "favicon_file": "favicon.ico"
+            }`)
+
+			cfg := &config.ApplicationConfig{DynamicConfigsDir: dir}
+			loadRuntimeSettingsFromFile(cfg)
+
+			Expect(cfg.Branding).To(Equal(config.BrandingConfig{
+				InstanceName:       "Acme AI",
+				InstanceTagline:    "Private inference",
+				LogoFile:           "logo.png",
+				LogoHorizontalFile: "logo_horizontal.svg",
+				FaviconFile:        "favicon.ico",
+			}))
+		})
+	})
+
+	// Adjacent fields exercise the other classes of settings that
+	// previously silently reverted on restart. Each spec pairs a
+	// runtime_settings.json fragment with the expected ApplicationConfig
+	// state after the loader runs. A regression in any one means a
+	// UI-saved setting will not survive a process restart — same shape as
+	// the branding bug, different field.
+	//
+	// Where a field has a non-zero default (set by NewApplicationConfig),
+	// the spec seeds the post-AppOptions state the loader would observe
+	// at boot. Without that setup the "if at default" gate would either
+	// always pass or always fail and the spec wouldn't reflect the real
+	// call site.
+	Describe("adjacent restart-loss fields", func() {
+		It("loads auto_upgrade_backends", func() {
+			cfg := &config.ApplicationConfig{DynamicConfigsDir: seedSettings(`{"auto_upgrade_backends": true}`)}
+			loadRuntimeSettingsFromFile(cfg)
+			Expect(cfg.AutoUpgradeBackends).To(BeTrue())
+		})
+
+		It("loads prefer_development_backends", func() {
+			cfg := &config.ApplicationConfig{DynamicConfigsDir: seedSettings(`{"prefer_development_backends": true}`)}
+			loadRuntimeSettingsFromFile(cfg)
+			Expect(cfg.PreferDevelopmentBackends).To(BeTrue())
+		})
+
+		It("disables the LocalAI Assistant when localai_assistant_enabled=false", func() {
+			cfg := &config.ApplicationConfig{DynamicConfigsDir: seedSettings(`{"localai_assistant_enabled": false}`)}
+			loadRuntimeSettingsFromFile(cfg)
+			Expect(cfg.DisableLocalAIAssistant).To(BeTrue())
+		})
+
+		It("loads open_responses_store_ttl as a duration", func() {
+			cfg := &config.ApplicationConfig{DynamicConfigsDir: seedSettings(`{"open_responses_store_ttl": "1h"}`)}
+			loadRuntimeSettingsFromFile(cfg)
+			Expect(cfg.OpenResponsesStoreTTL).To(Equal(time.Hour))
+		})
+	})
+
+	// The Agent Pool block has a mix of zero and non-zero defaults
+	// (Enabled=true, EmbeddingModel="granite-...", MaxChunkingSize=400,
+	// VectorEngine="chromem", AgentHubURL="https://agenthub.localai.io").
+	// Each spec seeds the appropriate startup state so the loader's
+	// "at default" check observes what New() would.
+	Describe("agent pool fields", func() {
+		It("loads agent_pool_enabled=false against the default-true", func() {
+			cfg := &config.ApplicationConfig{
+				DynamicConfigsDir: seedSettings(`{"agent_pool_enabled": false}`),
+				AgentPool:         config.AgentPoolConfig{Enabled: true},
+			}
+			loadRuntimeSettingsFromFile(cfg)
+			Expect(cfg.AgentPool.Enabled).To(BeFalse())
+		})
+
+		It("loads agent_pool_default_model", func() {
+			cfg := &config.ApplicationConfig{DynamicConfigsDir: seedSettings(`{"agent_pool_default_model": "qwen2.5-7b"}`)}
+			loadRuntimeSettingsFromFile(cfg)
+			Expect(cfg.AgentPool.DefaultModel).To(Equal("qwen2.5-7b"))
+		})
+
+		It("overrides the granite embedding default", func() {
+			cfg := &config.ApplicationConfig{
+				DynamicConfigsDir: seedSettings(`{"agent_pool_embedding_model": "all-minilm"}`),
+				AgentPool:         config.AgentPoolConfig{EmbeddingModel: "granite-embedding-107m-multilingual"},
+			}
+			loadRuntimeSettingsFromFile(cfg)
+			Expect(cfg.AgentPool.EmbeddingModel).To(Equal("all-minilm"))
+		})
+
+		It("overrides the 400 max chunking size default", func() {
+			cfg := &config.ApplicationConfig{
+				DynamicConfigsDir: seedSettings(`{"agent_pool_max_chunking_size": 800}`),
+				AgentPool:         config.AgentPoolConfig{MaxChunkingSize: 400},
+			}
+			loadRuntimeSettingsFromFile(cfg)
+			Expect(cfg.AgentPool.MaxChunkingSize).To(Equal(800))
+		})
+
+		It("loads agent_pool_chunk_overlap", func() {
+			cfg := &config.ApplicationConfig{DynamicConfigsDir: seedSettings(`{"agent_pool_chunk_overlap": 50}`)}
+			loadRuntimeSettingsFromFile(cfg)
+			Expect(cfg.AgentPool.ChunkOverlap).To(Equal(50))
+		})
+
+		It("loads agent_pool_enable_logs", func() {
+			cfg := &config.ApplicationConfig{DynamicConfigsDir: seedSettings(`{"agent_pool_enable_logs": true}`)}
+			loadRuntimeSettingsFromFile(cfg)
+			Expect(cfg.AgentPool.EnableLogs).To(BeTrue())
+		})
+
+		It("loads agent_pool_collection_db_path", func() {
+			cfg := &config.ApplicationConfig{DynamicConfigsDir: seedSettings(`{"agent_pool_collection_db_path": "/var/lib/localai/collections.db"}`)}
+			loadRuntimeSettingsFromFile(cfg)
+			Expect(cfg.AgentPool.CollectionDBPath).To(Equal("/var/lib/localai/collections.db"))
+		})
+
+		It("overrides the chromem vector_engine default", func() {
+			cfg := &config.ApplicationConfig{
+				DynamicConfigsDir: seedSettings(`{"agent_pool_vector_engine": "postgres"}`),
+				AgentPool:         config.AgentPoolConfig{VectorEngine: "chromem"},
+			}
+			loadRuntimeSettingsFromFile(cfg)
+			Expect(cfg.AgentPool.VectorEngine).To(Equal("postgres"))
+		})
+
+		It("loads agent_pool_database_url", func() {
+			cfg := &config.ApplicationConfig{DynamicConfigsDir: seedSettings(`{"agent_pool_database_url": "postgres://user:pass@db:5432/localai"}`)}
+			loadRuntimeSettingsFromFile(cfg)
+			Expect(cfg.AgentPool.DatabaseURL).To(Equal("postgres://user:pass@db:5432/localai"))
+		})
+
+		It("overrides the agenthub.localai.io agent_hub_url default", func() {
+			cfg := &config.ApplicationConfig{
+				DynamicConfigsDir: seedSettings(`{"agent_pool_agent_hub_url": "https://hub.acme.io"}`),
+				AgentPool:         config.AgentPoolConfig{AgentHubURL: "https://agenthub.localai.io"},
+			}
+			loadRuntimeSettingsFromFile(cfg)
+			Expect(cfg.AgentPool.AgentHubURL).To(Equal("https://hub.acme.io"))
+		})
+	})
+})

core/application/startup.go

@@ -548,6 +548,109 @@ func loadRuntimeSettingsFromFile(options *config.ApplicationConfig) {
 		}
 	}
 
+	// Branding / whitelabeling. There are no env vars for these — the file is
+	// the only source — so apply unconditionally. Without this block a server
+	// restart silently drops the configured instance name, tagline, and asset
+	// filenames.
+	if settings.InstanceName != nil {
+		options.Branding.InstanceName = *settings.InstanceName
+	}
+	if settings.InstanceTagline != nil {
+		options.Branding.InstanceTagline = *settings.InstanceTagline
+	}
+	if settings.LogoFile != nil {
+		options.Branding.LogoFile = *settings.LogoFile
+	}
+	if settings.LogoHorizontalFile != nil {
+		options.Branding.LogoHorizontalFile = *settings.LogoHorizontalFile
+	}
+	if settings.FaviconFile != nil {
+		options.Branding.FaviconFile = *settings.FaviconFile
+	}
+
+	// Backend upgrade flags
+	if settings.AutoUpgradeBackends != nil {
+		if !options.AutoUpgradeBackends {
+			options.AutoUpgradeBackends = *settings.AutoUpgradeBackends
+		}
+	}
+	if settings.PreferDevelopmentBackends != nil {
+		if !options.PreferDevelopmentBackends {
+			options.PreferDevelopmentBackends = *settings.PreferDevelopmentBackends
+		}
+	}
+
+	// LocalAI Assistant — file-stored as the negation (LocalAIAssistantEnabled).
+	// Default is enabled (DisableLocalAIAssistant=false). Apply the file value
+	// unless env explicitly disabled the assistant (DisableLocalAIAssistant=true).
+	if settings.LocalAIAssistantEnabled != nil {
+		if !options.DisableLocalAIAssistant {
+			options.DisableLocalAIAssistant = !*settings.LocalAIAssistantEnabled
+		}
+	}
+
+	// Open Responses TTL. Default is 0 (no expiration). Treat the on-disk
+	// "0"/empty as "no expiration" — a no-op since options is already 0 —
+	// and parse anything else as a duration.
+	if settings.OpenResponsesStoreTTL != nil && options.OpenResponsesStoreTTL == 0 {
+		v := *settings.OpenResponsesStoreTTL
+		if v != "0" && v != "" {
+			if dur, err := time.ParseDuration(v); err == nil {
+				options.OpenResponsesStoreTTL = dur
+			} else {
+				xlog.Warn("invalid open_responses_store_ttl in runtime_settings.json", "error", err, "ttl", v)
+			}
+		}
+	}
+
+	// Agent Pool. NewApplicationConfig seeds non-zero defaults for some of
+	// these fields (Enabled=true, EmbeddingModel="granite-embedding-107m-
+	// multilingual", MaxChunkingSize=400). The "if at default, apply file"
+	// gate uses each field's actual default literal so file values can
+	// override the bootstrap default while still letting an env-set value
+	// (e.g. WithAgentPoolEmbeddingModel from a flag) win.
+	if settings.AgentPoolEnabled != nil && options.AgentPool.Enabled {
+		options.AgentPool.Enabled = *settings.AgentPoolEnabled
+	}
+	if settings.AgentPoolDefaultModel != nil && options.AgentPool.DefaultModel == "" {
+		options.AgentPool.DefaultModel = *settings.AgentPoolDefaultModel
+	}
+	if settings.AgentPoolEmbeddingModel != nil {
+		if options.AgentPool.EmbeddingModel == "" || options.AgentPool.EmbeddingModel == "granite-embedding-107m-multilingual" {
+			options.AgentPool.EmbeddingModel = *settings.AgentPoolEmbeddingModel
+		}
+	}
+	if settings.AgentPoolMaxChunkingSize != nil {
+		if options.AgentPool.MaxChunkingSize == 0 || options.AgentPool.MaxChunkingSize == 400 {
+			options.AgentPool.MaxChunkingSize = *settings.AgentPoolMaxChunkingSize
+		}
+	}
+	if settings.AgentPoolChunkOverlap != nil && options.AgentPool.ChunkOverlap == 0 {
+		options.AgentPool.ChunkOverlap = *settings.AgentPoolChunkOverlap
+	}
+	if settings.AgentPoolEnableLogs != nil && !options.AgentPool.EnableLogs {
+		options.AgentPool.EnableLogs = *settings.AgentPoolEnableLogs
+	}
+	if settings.AgentPoolCollectionDBPath != nil && options.AgentPool.CollectionDBPath == "" {
+		options.AgentPool.CollectionDBPath = *settings.AgentPoolCollectionDBPath
+	}
+	if settings.AgentPoolVectorEngine != nil {
+		// Default is "chromem"; treat both that and empty as "not env-set".
+		if options.AgentPool.VectorEngine == "" || options.AgentPool.VectorEngine == "chromem" {
+			options.AgentPool.VectorEngine = *settings.AgentPoolVectorEngine
+		}
+	}
+	if settings.AgentPoolDatabaseURL != nil && options.AgentPool.DatabaseURL == "" {
+		options.AgentPool.DatabaseURL = *settings.AgentPoolDatabaseURL
+	}
+	if settings.AgentPoolAgentHubURL != nil {
+		// Default is "https://agenthub.localai.io"; treat both that and empty
+		// as "not env-set".
+		if options.AgentPool.AgentHubURL == "" || options.AgentPool.AgentHubURL == "https://agenthub.localai.io" {
+			options.AgentPool.AgentHubURL = *settings.AgentPoolAgentHubURL
+		}
+	}
+
 	xlog.Debug("Runtime settings loaded from runtime_settings.json")
 }