docs(providers): add llama.cpp / LM Studio guide

docs/docs.json

@@ -177,6 +177,7 @@
                     "providers/opencode-go",
                     "providers/sglang",
                     "providers/vllm",
+                    "providers/llamacpp",
                     "providers/llmd",
                     "providers/multiple-ollama",
                     "providers/kimicode",

docs/providers/llamacpp.mdx

@@ -0,0 +1,98 @@
+---
+title: "llama.cpp"
+description: "Route OpenAI-compatible GoModel requests to a llama.cpp llama-server instance (the same recipe works for LM Studio)."
+icon: "server"
+keywords: ["llama.cpp", "llama-server", "LM Studio", "local models", "self-hosted", "OpenAI-compatible server"]
+---
+
+llama.cpp's `llama-server` speaks the OpenAI API directly, so GoModel needs no
+dedicated provider type for it: register the server as a **vLLM-type provider**.
+That type fits llama.cpp exactly — the API key is optional (llama-server
+usually runs keyless), and slash-shaped model IDs work. Do **not** register it
+as an
+`ollama` provider: that type speaks Ollama's native API, which llama.cpp does
+not implement.
+
+The same recipe applies to LM Studio and any other plain OpenAI-compatible
+local server.
+
+Start llama-server first. Without `--alias`, the model ID in `/v1/models` is
+the model file's path — set an alias so requests can use a clean name:
+
+```bash
+llama-server -hf ggml-org/gemma-3-4b-it-GGUF --alias gemma-3-4b-it --port 8081
+# add --api-key token-abc123 if you want llama-server to require bearer auth
+```
+
+## Configure
+
+```bash
+VLLM_BASE_URL=http://host.docker.internal:8081/v1   # include /v1
+# VLLM_API_KEY=token-abc123                         # only if llama-server was started with --api-key
+GOMODEL_MASTER_KEY=change-me
+```
+
+<Note>
+  These examples assume GoModel runs in Docker and llama-server is on the host
+  at `localhost:8081` — hence `host.docker.internal`. If GoModel runs on the
+  host directly, use `http://localhost:8081/v1`. Already using `VLLM_BASE_URL`
+  for a real vLLM server? Register llama.cpp under a suffixed instance instead:
+  `VLLM_LLAMACPP_BASE_URL=...` creates provider `vllm-llamacpp`.
+</Note>
+
+## Verify
+
+```bash
+curl -s http://localhost:8080/v1/chat/completions \
+  -H "Authorization: Bearer change-me" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "model": "vllm/gemma-3-4b-it",
+    "messages": [{"role": "user", "content": "Reply with exactly ok."}]
+  }'
+```
+
+`GET /v1/models` returns llama-server's model IDs prefixed by provider name.
+
+## Embeddings
+
+`/v1/embeddings` works through GoModel as long as llama-server can serve it:
+the loaded model must use a pooling type other than `none`. Dedicated embedding
+GGUFs usually declare pooling in their metadata; otherwise pass `--pooling mean`
+(or `cls`/`last`). The `--embeddings` flag is optional — it restricts the
+server to embeddings only:
+
+```bash
+llama-server -hf nomic-ai/nomic-embed-text-v1.5-GGUF --embeddings --alias nomic-embed-text-v1.5 --port 8081
+```
+
+```bash
+curl -s http://localhost:8080/v1/embeddings \
+  -H "Authorization: Bearer change-me" \
+  -H "Content-Type: application/json" \
+  -d '{"model": "vllm/nomic-embed-text-v1.5", "input": "hello"}'
+```
+
+## Model classification
+
+llama-server's `/v1/models` listing carries no capability metadata, so GoModel
+classifies its models by ID: names containing `embed` or matching well-known
+embedding families (`bge`, `e5`, `gte`, `minilm`) are categorized as embedding
+models, and names containing `rerank` as reranking models — namespaced IDs are
+checked by their final path segment. For anything that stays unclassified,
+declare `modes` (and context window or pricing) under the provider's model
+metadata — see [Model metadata](/advanced/model-metadata). Categories only
+affect dashboard grouping and failover suggestions; `/v1/embeddings` routes to
+any model the provider serves regardless of category.
+
+## Beyond chat and embeddings
+
+- **Multimodal input** — image and audio *input* in chat messages works with
+  multimodal models when llama-server is started with a projector
+  (`--mmproj`, auto-loaded with `-hf` when available). These requests flow
+  through `/v1/chat/completions` normally.
+- **Reranking** — llama-server serves `/v1/rerank` (start with a reranker
+  model and `--rerank --embedding --pooling rank`), but GoModel has no rerank
+  endpoint; reach it through [passthrough](/features/passthrough-api):
+  `POST /p/vllm/v1/rerank` (use the instance name, e.g.
+  `/p/vllm-llamacpp/v1/rerank`, for a suffixed setup).

docs/providers/overview.mdx

@@ -65,6 +65,7 @@ support, not every individual model capability exposed by an upstream provider.
 | Ollama | `OLLAMA_BASE_URL` | `llama3.2` | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ | [Ollama](/providers/multiple-ollama) |
 | SGLang | `SGLANG_BASE_URL` (`SGLANG_API_KEY` optional) | `Qwen/Qwen2.5-0.5B-Instruct` | ✅ | ✅ | ✅ | ❌ | ❌ | ✅ | [SGLang](/providers/sglang) |
 | vLLM | `VLLM_BASE_URL` (`VLLM_API_KEY` optional) | `meta-llama/Llama-3.1-8B-Instruct` | ✅ | ✅ | ✅ | ❌ | ❌ | ✅ | [vLLM](/providers/vllm) |
+| llama.cpp / LM Studio (as vLLM type) | `VLLM_BASE_URL` (`VLLM_API_KEY` optional) | `gemma-3-4b-it` | ✅ | ✅ | ✅ | ❌ | ❌ | ✅ | [llama.cpp](/providers/llamacpp) |
 | llm-d | `LLMD_BASE_URL` (`LLMD_API_KEY` optional) | `Qwen/Qwen2.5-0.5B-Instruct` | ✅ | ✅ | ✅ | ❌ | ❌ | ✅ | [llm-d](/providers/llmd) |
 | Amazon Bedrock | `BEDROCK_BASE_URL` (region or endpoint) + AWS credentials | `anthropic.claude-3-5-haiku-20241022-v1:0` | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ | [Amazon Bedrock](/providers/bedrock) |
 | Amazon Bedrock Mantle | `BEDROCK_MANTLE_API_KEY` or AWS credentials | `openai.gpt-5.6-sol` | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ | [Bedrock Mantle](/providers/bedrock-mantle) |
@@ -155,6 +156,10 @@ support, not every individual model capability exposed by an upstream provider.
   routes to any model the provider serves regardless of category.
 - **vLLM** — set `VLLM_API_KEY` only if the upstream server was started with
   `--api-key`.
+- **llama.cpp / LM Studio** — no dedicated provider type; register the server
+  as a vLLM-type provider (`VLLM_BASE_URL` or a suffixed instance), not as
+  `ollama`, which speaks Ollama's native API. See
+  [llama.cpp](/providers/llamacpp).
 - **llm-d** — `LLMD_BASE_URL` is required. `LLMD_API_KEY` is optional and is
   sent only when the Gateway in front of the Router requires bearer auth.
 - **SGLang** — set `SGLANG_API_KEY` only if the upstream server was started