From c1d0b10b1484ce4fffab3255c2a687060aba0b45 Mon Sep 17 00:00:00 2001
From: Richard Palethorpe <io@richiejp.com>
Date: Fri, 6 Feb 2026 09:28:41 +0000
Subject: [PATCH] chore(docs): Document using a local model gallery (#8426)

Signed-off-by: Richard Palethorpe <io@richiejp.com>
---
 docs/content/features/model-gallery.md | 34 +++++++++++++++++++++++++-
 docs/content/getting-started/models.md |  6 ++++-
 2 files changed, 38 insertions(+), 2 deletions(-)

diff --git a/docs/content/features/model-gallery.md b/docs/content/features/model-gallery.md
index a7665952f..613781b41 100644
--- a/docs/content/features/model-gallery.md
+++ b/docs/content/features/model-gallery.md
@@ -73,6 +73,33 @@ where `github:mudler/localai/gallery/index.yaml` will be expanded automatically
 
 Note: the url are expanded automatically for `github` and `huggingface`, however `https://` and `http://` prefix works as well.
 
+#### Using Local Gallery Files
+
+You can also use local gallery index files by using the `file://` prefix. For security reasons, **local gallery files must be located within your models directory** (the directory specified by `MODELS_PATH` or the default `models/` directory).
+
+**Example:**
+
+```json
+GALLERIES=[{"name":"my-local-gallery", "url":"file:///path/to/models/my-gallery-index.yaml"}]
+```
+
+**Important notes:**
+- The `file://` prefix is required for local paths
+- The file path must be absolute (starting with `/` on Unix systems)
+- The resolved path must be within your models directory for security
+- If you try to access files outside the models directory, LocalAI will block the request
+
+**Valid example** (assuming `MODELS_PATH=/opt/localai/models`):
+```json
+GALLERIES=[{"name":"local", "url":"file:///opt/localai/models/galleries/my-gallery.yaml"}]
+```
+
+**Invalid example** (file outside models directory):
+```json
+GALLERIES=[{"name":"local", "url":"file:///home/user/my-gallery.yaml"}]
+```
+This will be rejected with a security error.
+
 {{% notice note %}}
 
 If you want to build your own gallery, there is no documentation yet. However you can find the source of the default gallery in the [LocalAI repository](https://github.com/mudler/LocalAI/tree/master/gallery).
@@ -438,7 +465,12 @@ curl http://localhost:8080/models/apply -H "Content-Type: application/json" -d '
 
 An optional, list of additional files can be specified to be downloaded within `files`. The `name` allows to override the model name. Finally it is possible to override the model config file with `override`.
 
-The `url` is a full URL, or a github url (`github:org/repo/file.yaml`), or a local file (`file:///path/to/file.yaml`).
+The `url` is a full URL, or a github url (`github:org/repo/file.yaml`), or a local file (`file:///path/to/file.yaml`). 
+
+{{% notice warning %}}
+**Local file security restriction:** When using `file://` URLs, the file path must be within your models directory (specified by `MODELS_PATH`). Files outside this directory will be rejected for security reasons.
+{{% /notice %}}
+
 The `id` is a string in the form `<GALLERY>@<MODEL_NAME>`, where `<GALLERY>` is the name of the gallery, and `<MODEL_NAME>` is the name of the model in the gallery. Galleries can be specified during startup with the `GALLERIES` environment variable.
 
 Returns an `uuid` and an `url` to follow up the state of the process:
diff --git a/docs/content/getting-started/models.md b/docs/content/getting-started/models.md
index 144c565bb..3382d723a 100644
--- a/docs/content/getting-started/models.md
+++ b/docs/content/getting-started/models.md
@@ -133,11 +133,15 @@ local-ai run oci://localai/phi-2:latest
 
 To run models via URI, specify a URI to a model file or a configuration file when starting LocalAI. Valid syntax includes:
 
-- `file://path/to/model`
+- `file://path/to/model` (absolute path to a file within your models directory)
 - `huggingface://repository_id/model_file` (e.g., `huggingface://TheBloke/phi-2-GGUF/phi-2.Q8_0.gguf`)
 - From OCIs: `oci://container_image:tag`, `ollama://model_id:tag`
 - From configuration files: `https://gist.githubusercontent.com/.../phi-2.yaml`
 
+{{% notice note %}}
+When using `file://` URLs, the path must point to a file within your models directory (specified by `MODELS_PATH`). Files outside this directory are rejected for security reasons.
+{{% /notice %}}
+
 Configuration files can be used to customize the model defaults and settings. For advanced configurations, refer to the [Customize Models section]({{% relref "getting-started/customize-model" %}}).
 
 ### Examples