docs(guides): add multiple Ollama setup guide

docs/advanced/config-yaml.mdx

@@ -0,0 +1,82 @@
+---
+title: "config.yaml"
+description: "When to use config.yaml, when not to, and how it interacts with environment variables and Docker."
+---
+
+The goal in GoModel is to make `config.yaml` optional as much as possible.
+Prefer environment variables for normal deployments, CI, containers, and secret
+injection.
+
+Use `config.yaml` when you need structure that env vars cannot express cleanly,
+especially:
+
+- multiple providers with the same type
+- custom provider instance names such as `ollama-a`, `ollama-b`, or `my-openai`
+- larger nested config that is easier to review in one file
+
+## Priority Order
+
+Effective precedence is:
+
+1. environment variables
+2. optional `config/config.yaml` or `config.yaml`
+3. built-in defaults from code
+
+`.env` is not a separate priority layer. It is just a convenient way to load
+environment variables before startup.
+
+## When `config.yaml` Is Better
+
+YAML is the current way to define multiple providers of the same type with
+flexible names:
+
+```yaml
+providers:
+  ollama-a:
+    type: ollama
+    base_url: "http://host.docker.internal:11434/v1"
+
+  ollama-b:
+    type: ollama
+    base_url: "http://host.docker.internal:11435/v1"
+```
+
+That gives you provider-qualified model IDs such as `ollama-a/llama3.2` and
+`ollama-b/llama3.2`.
+
+## Current Schema
+
+The current source of truth lives in the main codebase:
+
+- [config/config.go](https://github.com/ENTERPILOT/GoModel/blob/main/config/config.go)
+- [config/config.example.yaml](https://github.com/ENTERPILOT/GoModel/blob/main/config/config.example.yaml)
+
+## Docker
+
+GoModel reads `config/config.yaml` first, then `config.yaml`.
+
+With `docker run`, you can keep a host file named `config.yml` and mount it to
+the in-container path GoModel expects:
+
+```bash
+docker run --rm -p 8080:8080 \
+  -v "$PWD/config.yml:/app/config/config.yaml:ro" \
+  enterpilot/gomodel:latest
+```
+
+With Docker Compose:
+
+```yaml
+services:
+  gomodel:
+    image: enterpilot/gomodel:latest
+    ports:
+      - "8080:8080"
+    volumes:
+      - ./config.yml:/app/config/config.yaml:ro
+```
+
+<Tip>
+  If env vars and YAML both define the same setting, the environment variable
+  wins.
+</Tip>

docs/advanced/configuration.mdx

@@ -175,6 +175,9 @@ For more complex setups, you can use an optional YAML configuration file. GOMode
 1. `config/config.yaml`
 2. `config.yaml`
 
+If you are deciding whether you need YAML at all, see
+[config.yaml](/advanced/config-yaml).
+
 To get started, copy the example:
 
 ```bash

docs/docs.json

@@ -24,14 +24,15 @@
                 "pages": [
                     "guides/openclaw",
                     "guides/oracle",
+                    "guides/multiple-ollama",
                     "guides/claude-code",
                     "guides/codex",
                     "guides/opencode-and-other-agents"
                 ]
             },
             {
                 "group": "Advanced",
-                "pages": ["advanced/configuration", "advanced/guardrails", "advanced/admin-endpoints"]
+                "pages": ["advanced/configuration", "advanced/config-yaml", "advanced/guardrails", "advanced/admin-endpoints"]
             },
             {
                 "group": "About",

docs/guides/multiple-ollama.mdx

@@ -0,0 +1,85 @@
+---
+title: "Running Multiple Ollama Backends"
+description: "Use one GoModel instance with multiple Ollama providers by mounting a YAML config and selecting provider-qualified model IDs."
+---
+
+GoModel can register multiple Ollama providers when each one has its own key in
+the top-level `providers:` map.
+
+Flow:
+
+`Client -> GoModel -> ollama-a / ollama-b`
+
+## 1. Create a host-side `config.yml`
+
+```yaml
+providers:
+  ollama-a:
+    type: ollama
+    base_url: "http://host.docker.internal:11434/v1"
+
+  ollama-b:
+    type: ollama
+    base_url: "http://host.docker.internal:11435/v1"
+```
+
+Use different ports or hostnames for each Ollama instance.
+
+## 2. Run GoModel and mount the config
+
+```bash
+docker run --rm --name gomodel \
+  -p 8080:8080 \
+  -e GOMODEL_MASTER_KEY="change-me" \
+  -v "$PWD/config.yml:/app/config/config.yaml:ro" \
+  enterpilot/gomodel:latest
+```
+
+<Note>
+  The file can be named `config.yml` on the host. The important part is the
+  bind mount target: GoModel reads `/app/config/config.yaml` inside the
+  container.
+</Note>
+
+<Tip>
+  On Linux, you may need to add
+  `--add-host=host.docker.internal:host-gateway` so the container can reach
+  Ollama running on the host.
+</Tip>
+
+## 3. Verify the model registry
+
+```bash
+curl -s http://localhost:8080/v1/models \
+  -H "Authorization: Bearer change-me"
+```
+
+Expected model IDs will be provider-qualified, for example:
+
+- `ollama-a/llama3.2`
+- `ollama-b/llama3.2`
+
+## 4. Route to a specific Ollama backend
+
+```bash
+curl -s http://localhost:8080/v1/chat/completions \
+  -H "Authorization: Bearer change-me" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "model": "ollama-a/llama3.2",
+    "messages": [{"role": "user", "content": "Reply with exactly ok."}]
+  }'
+```
+
+If you send only the bare model name such as `llama3.2` and both providers
+expose it, GoModel will route the request to one provider based on provider
+registration order. To choose a specific Ollama backend, use the qualified form
+such as `ollama-a/llama3.2` or `ollama-b/llama3.2`.
+
+## Validated on April 6, 2026
+
+This guide was validated with:
+
+- `enterpilot/gomodel:latest`
+- a bind-mounted host `config.yml`
+- two Ollama-compatible upstream endpoints exposed as separate provider names