feat(local-models): add documentation for connecting local model providers

surfsense_backend/app/services/provider_registry.py

@@ -88,7 +88,7 @@ REGISTRY: dict[str, ProviderSpec] = {
         Transport.OLLAMA,
         "ollama_chat",
         "ollama",
-        "http://ollama:11434",
+        "http://host.docker.internal:11434",
         True,
         "none",
         "Ollama",

surfsense_web/content/docs/how-to/meta.json

@@ -1,6 +1,6 @@
 {
 	"title": "How to",
-	"pages": ["zero-sync", "realtime-collaboration", "web-search", "ollama"],
+	"pages": ["zero-sync", "realtime-collaboration", "web-search"],
 	"icon": "Compass",
 	"defaultOpen": false
 }

surfsense_web/content/docs/how-to/ollama.mdx

@@ -1,90 +0,0 @@
----
-title: Connect Ollama
-description: Simple setup guide for using Ollama with SurfSense across local, Docker, remote, and cloud setups
----
-
-# Connect Ollama
-
-Use this page to choose the correct **API Base URL** when adding an Ollama provider in SurfSense.
-
-## 1) Pick your API Base URL
-
-| Ollama location | SurfSense location | API Base URL |
-|---|---|---|
-| Same machine | No Docker | `http://localhost:11434` |
-| Host machine (macOS/Windows) | Docker Desktop | `http://host.docker.internal:11434` |
-| Host machine (Linux) | Docker Compose | `http://host.docker.internal:11434` |
-| Same Docker Compose stack | Docker Compose | `http://ollama:11434` |
-| Another machine in your network | Any | `http://<lan-ip>:11434` |
-| Public Ollama endpoint / proxy / cloud | Any | `http(s)://<your-domain-or-endpoint>` |
-
-If SurfSense runs in Docker, do not use `localhost` unless Ollama is in the same container.
-
-## 2) Add Ollama in SurfSense
-
-Go to **Search Space Settings -> Models -> Add Model** and set:
-
-- Provider: `OLLAMA`
-- Model name: your model tag, for example `llama3.2` or `qwen3:8b`
-- API Base URL: from the table above
-- API key:
-  - local/self-hosted Ollama: any non-empty value
-  - Ollama cloud/proxied auth: real key or token required by that endpoint
-
-Save. SurfSense validates the connection immediately.
-
-## 3) Common setups
-
-### A) SurfSense in Docker Desktop, Ollama on your host
-
-Use:
-
-```text
-http://host.docker.internal:11434
-```
-
-### B) Ollama as a service in the same Compose
-
-Use API Base URL:
-
-```text
-http://ollama:11434
-```
-
-Minimal service example:
-
-```yaml
-ollama:
-  image: ollama/ollama:latest
-  volumes:
-    - ollama_data:/root/.ollama
-  ports:
-    - "11434:11434"
-```
-
-### C) Ollama on another machine
-
-Ollama binds to `127.0.0.1` by default. Make it reachable on the network:
-
-- Set `OLLAMA_HOST=0.0.0.0:11434` on the machine/service running Ollama
-- Open firewall port `11434`
-- Use `http://<lan-ip>:11434` in SurfSense's API Base URL
-
-## 4) Quick troubleshooting
-
-| Error | Cause | Fix |
-|---|---|---|
-| `Cannot connect to host localhost:11434` | Wrong URL from Dockerized backend | Use `host.docker.internal` or `ollama` |
-| `Cannot connect to host <lan-ip>:11434` | Ollama not exposed on network or firewall blocked | Set `OLLAMA_HOST=0.0.0.0:11434`, allow port 11434 |
-| URL starts with `/%20http://...` | Leading space in URL | Re-enter API Base URL without spaces |
-| `model not found` | Model not pulled on Ollama | Run `ollama pull <model>` |
-
-If needed, test from the backend container using the same host you put in **API Base URL**:
-
-```bash
-docker compose exec backend curl -v <YOUR_API_BASE_URL>/api/tags
-```
-
-## See also
-
-- [Docker Installation](/docs/docker-installation/docker-compose)

surfsense_web/content/docs/index.mdx

@@ -5,7 +5,7 @@ icon: BookOpen
 ---
 
 import { Card, Cards } from 'fumadocs-ui/components/card';
-import { ClipboardCheck, Download, Container, Wrench, Cable, BookOpen, FlaskConical, Heart, MessageCircle } from 'lucide-react';
+import { ClipboardCheck, Download, Container, Wrench, Cable, BookOpen, FlaskConical, Heart, MessageCircle, Cpu } from 'lucide-react';
 
 Welcome to **SurfSense's Documentation!** Here, you'll find everything you need to get the most out of SurfSense. Dive in to explore how SurfSense can be your AI-powered research companion.
 
@@ -34,6 +34,12 @@ Welcome to **SurfSense's Documentation!** Here, you'll find everything you need
     description="Set up SurfSense manually from source"
     href="/docs/manual-installation"
   />
+  <Card
+    icon={<Cpu />}
+    title="Local Models"
+    description="Connect local model servers"
+    href="/docs/local-models"
+  />
   <Card
     icon={<Cable />}
     title="Connectors"

surfsense_web/content/docs/local-models/index.mdx

@@ -0,0 +1,30 @@
+---
+title: Local Models
+description: Connect local model servers to SurfSense
+---
+
+import { Card, Cards } from 'fumadocs-ui/components/card';
+
+# Local Models
+
+SurfSense can use local model servers such as Ollama and LM Studio.
+
+The API Base URL is read by the SurfSense backend. If SurfSense runs in Docker, use an address the backend container can reach.
+
+<Cards>
+  <Card
+    title="Ollama"
+    description="Connect an Ollama server and discover local model tags"
+    href="/docs/local-models/ollama"
+  />
+  <Card
+    title="LM Studio"
+    description="Connect an LM Studio local server"
+    href="/docs/local-models/lm-studio"
+  />
+  <Card
+    title="Other Local Servers"
+    description="Connect llama.cpp, vLLM, LocalAI, LiteLLM Proxy, and more"
+    href="/docs/local-models/other-local-servers"
+  />
+</Cards>

surfsense_web/content/docs/local-models/lm-studio.mdx

@@ -0,0 +1,92 @@
+---
+title: LM Studio
+description: Connect LM Studio to SurfSense
+---
+
+# Connect LM Studio
+
+Connect to your LM Studio local server. Add it from
+**Search Space Settings > Models**.
+
+## Base URL
+
+LM Studio uses an OpenAI compatible server.
+
+### SurfSense Runs in Docker
+
+Use this when SurfSense is running from Docker and LM Studio is running on your computer.
+
+```text
+http://host.docker.internal:1234/v1
+```
+
+<Callout type="info">
+This is the default in SurfSense.
+</Callout>
+
+### SurfSense Runs Without Docker
+
+Use this when SurfSense and LM Studio both run directly on the same computer.
+
+```text
+http://localhost:1234/v1
+```
+
+### LM Studio Runs on Another Computer
+
+Use this when LM Studio is running on another machine in your network.
+
+```text
+http://<host>:1234/v1
+```
+
+Replace `<host>` with the LAN IP or domain for that machine.
+
+## LM Studio Setup
+
+1. Open LM Studio.
+2. Load a model.
+3. Start the local server.
+4. Confirm the server listens on port `1234`.
+
+## Add the Connection
+
+1. Open Search Space Settings.
+2. Go to Models.
+3. Select LM Studio.
+4. Set API Base URL.
+5. Leave API Key empty unless your server requires one.
+6. Select the models you want to enable.
+7. Save the connection.
+
+SurfSense discovers models from `/v1/models`. If you enter the URL without `/v1`, SurfSense adds it for requests.
+
+## Verify
+
+From the host:
+
+```bash
+curl http://localhost:1234/v1/models
+```
+
+From the SurfSense backend container:
+
+```bash
+docker compose exec backend curl http://host.docker.internal:1234/v1/models
+```
+
+## Troubleshooting
+
+### Connection refused
+
+LM Studio is not reachable from the backend.
+
+Start the LM Studio server and confirm that port `1234` is open.
+
+### No models found
+
+Load a model in LM Studio, then refresh model discovery in SurfSense.
+
+### Endpoint returned 404
+
+Use an OpenAI compatible server URL. The models endpoint must be available at `/v1/models`.

surfsense_web/content/docs/local-models/meta.json

@@ -0,0 +1,6 @@
+{
+	"title": "Local Models",
+	"pages": ["ollama", "lm-studio", "other-local-servers"],
+	"icon": "Cpu",
+	"defaultOpen": false
+}

surfsense_web/content/docs/local-models/ollama.mdx

@@ -0,0 +1,102 @@
+---
+title: Ollama
+description: Connect Ollama to SurfSense
+---
+
+# Connect Ollama
+
+Connect to your Ollama local server. Add it from
+**Search Space Settings > Models**.
+
+## Base URL
+
+Choose the URL from where the SurfSense backend runs.
+
+### SurfSense Runs in Docker
+
+Use this when SurfSense is running from Docker and Ollama is running on your computer.
+
+```text
+http://host.docker.internal:11434
+```
+
+<Callout type="info">
+This is the default in SurfSense.
+</Callout>
+
+### Ollama Runs in Docker
+
+Use this only when Ollama is a service in the same Compose stack as SurfSense.
+
+```text
+http://ollama:11434
+```
+
+### SurfSense Runs Without Docker
+
+Use this when SurfSense and Ollama both run directly on the same computer.
+
+```text
+http://localhost:11434
+```
+
+### Ollama Runs on Another Computer
+
+Use this when Ollama is running on another machine in your network.
+
+```text
+http://<host>:11434
+```
+
+Replace `<host>` with the LAN IP or domain for that machine.
+
+## Add the Connection
+
+1. Open Search Space Settings.
+2. Go to Models.
+3. Select Ollama.
+4. Set API Base URL.
+5. Leave API Key empty unless your endpoint needs one.
+6. Select the models you want to enable.
+7. Save the connection.
+
+Do not add `/v1` to the URL. SurfSense uses Ollama native routes such as `/api/version` and `/api/tags`.
+
+## Verify
+
+From the host:
+
+```bash
+curl http://localhost:11434/api/version
+```
+
+From the SurfSense backend container:
+
+```bash
+docker compose exec backend curl http://host.docker.internal:11434/api/version
+docker compose exec backend curl http://host.docker.internal:11434/api/tags
+```
+
+## Troubleshooting
+
+### Name or service not known
+
+The backend cannot resolve the host name.
+
+Use `http://host.docker.internal:11434` unless you run Ollama as a Compose service named `ollama`.
+
+### Connection refused
+
+Ollama is not reachable from the backend.
+
+Start Ollama and confirm that port `11434` is open.
+
+### No models found
+
+Pull at least one model:
+
+```bash
+ollama pull llama3.2
+```
+
+Then refresh model discovery in SurfSense.

surfsense_web/content/docs/local-models/other-local-servers.mdx

@@ -0,0 +1,109 @@
+---
+title: Other Local Servers
+description: Connect local OpenAI compatible model servers
+---
+
+# Connect Other Local Servers
+
+Connect to llama.cpp, vLLM, LocalAI, LiteLLM Proxy, and other servers
+that expose OpenAI compatible routes.
+
+SurfSense discovers models from:
+
+```text
+/v1/models
+```
+
+Chat requests use the same `/v1` base URL.
+
+## Pick Your Setup
+
+Use one of these URL patterns.
+
+### SurfSense Runs in Docker
+
+Use this when SurfSense is running from Docker and the model server is running on your computer.
+
+```text
+http://host.docker.internal:<port>/v1
+```
+
+Common ports:
+
+| Server | Port |
+|---|---|
+| llama.cpp | `10000` |
+| vLLM | `8000` |
+| LocalAI | `8080` |
+| LiteLLM Proxy | `4000` |
+| text-generation-webui | `5000` |
+
+### SurfSense Runs Without Docker
+
+Use this when SurfSense and the model server both run directly on the same computer.
+
+```text
+http://localhost:<port>/v1
+```
+
+### Model Server Runs on Another Computer
+
+Use this when the model server is running on another machine in your network.
+
+```text
+http://<host>:<port>/v1
+```
+
+## Add the Connection
+
+1. Open Search Space Settings.
+2. Go to Models.
+3. Select OpenAI Compatible.
+4. Set API Base URL.
+5. Add an API Key only if your server requires one.
+6. Select the models you want to enable.
+7. Save the connection.
+
+If you enter the URL without `/v1`, SurfSense adds `/v1` for requests.
+
+## Verify
+
+From the host:
+
+```bash
+curl http://localhost:<port>/v1/models
+```
+
+From the SurfSense backend container:
+
+```bash
+docker compose exec backend curl http://host.docker.internal:<port>/v1/models
+```
+
+A working server returns JSON with a `data` array.
+
+## When Not to Use This
+
+Use the Ollama provider for Ollama. It uses native routes such as `/api/tags`.
+
+Use the LM Studio provider for LM Studio. Its default URL is already set.
+
+## Troubleshooting
+
+### Endpoint returned 404
+
+The server does not expose `/v1/models`.
+
+Enable the server's OpenAI compatible mode.
+
+### Connection refused
+
+The backend cannot reach the server.
+
+Check that the server is running and that the port is open.
+
+### No models found
+
+The server returned an empty model list.
+
+Load or serve a model, then refresh model discovery in SurfSense.

surfsense_web/content/docs/meta.json

@@ -9,6 +9,7 @@
 		"installation",
 		"manual-installation",
 		"docker-installation",
+		"local-models",
 		"messaging-channels",
 		"connectors",
 		"how-to",

surfsense_web/lib/source.ts

@@ -4,6 +4,7 @@ import {
 	ClipboardCheck,
 	Compass,
 	Container,
+	Cpu,
 	Download,
 	FlaskConical,
 	Heart,
@@ -25,6 +26,7 @@ const DOCS_ICONS: Record<string, React.ComponentType> = {
 	ClipboardCheck,
 	Compass,
 	Container,
+	Cpu,
 	Download,
 	FlaskConical,
 	Heart,