diff --git a/docs/advanced/config-yaml.mdx b/docs/advanced/config-yaml.mdx
new file mode 100644
index 00000000..0cbb5c83
--- /dev/null
+++ b/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
+```
+
+
+ If env vars and YAML both define the same setting, the environment variable
+ wins.
+
diff --git a/docs/advanced/configuration.mdx b/docs/advanced/configuration.mdx
index 7cdf0095..383865a6 100644
--- a/docs/advanced/configuration.mdx
+++ b/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
diff --git a/docs/docs.json b/docs/docs.json
index 8a202958..9223150b 100644
--- a/docs/docs.json
+++ b/docs/docs.json
@@ -24,6 +24,7 @@
"pages": [
"guides/openclaw",
"guides/oracle",
+ "guides/multiple-ollama",
"guides/claude-code",
"guides/codex",
"guides/opencode-and-other-agents"
@@ -31,7 +32,7 @@
},
{
"group": "Advanced",
- "pages": ["advanced/configuration", "advanced/guardrails", "advanced/admin-endpoints"]
+ "pages": ["advanced/configuration", "advanced/config-yaml", "advanced/guardrails", "advanced/admin-endpoints"]
},
{
"group": "About",
diff --git a/docs/guides/multiple-ollama.mdx b/docs/guides/multiple-ollama.mdx
new file mode 100644
index 00000000..d94cddb3
--- /dev/null
+++ b/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
+```
+
+
+ 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.
+
+
+
+ On Linux, you may need to add
+ `--add-host=host.docker.internal:host-gateway` so the container can reach
+ Ollama running on the host.
+
+
+## 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