Overview
Text namespaces need an embedding provider to turn documents and search queries into vectors. Moorcheh On-Prem supports three providers, configured once and stored in ~/.moorcheh/config.json.
| Provider | API key | Ollama / Docker | Best for |
|---|
| Ollama | Not required | Optional host install or bundled moorcheh-ollama | Fully local, no cloud |
| OpenAI | Required | Server container only | Hosted embeddings, familiar models |
| Cohere | Required | Server container only | Multilingual and v4 models |
moorcheh up runs the same interactive wizard before starting Docker.
Saved settings:
| File | Contents |
|---|
~/.moorcheh/config.json | provider, model, api_key (cloud only), base_url |
~/.moorcheh/data/ | Namespaces and items (unchanged) |
moorcheh configure --force
After you change settings
| Action | When |
|---|
moorcheh down then moorcheh up | Whenever you change embedding or LLM in config.json (including after moorcheh configure --force) while the stack was already running. Configure alone does not restart Docker. |
| Re-upload text documents | When you change embedding provider or model and you already have text namespaces under ~/.moorcheh/data. Old vectors no longer match the new model. |
Existing data: If ~/.moorcheh/data already contains namespaces or uploaded items, switching embedding provider or model can make text search and RAG answers unreliable for those namespaces until you re-upload with the new embeddings. moorcheh configure warns and asks for confirmation when it detects stored data. Vector namespaces (you supplied vectors) are unaffected by embedding config, but dimension must still match what you uploaded.
Configuration file
Path (all platforms):
On Windows this resolves to C:\Users\<you>\.moorcheh\config.json.
moorcheh configure and moorcheh up write this file. Every moorcheh up reads it to set EMBEDDING_* and LLM_* environment variables on the server container. Your namespaces and items stay in ~/.moorcheh/data/ — that folder is separate from config. Changing config does not migrate or re-embed existing text data automatically.
Schema
Settings live under the embedding object:
{
"embedding": {
"provider": "openai",
"model": "text-embedding-3-small",
"api_key": "sk-...",
"base_url": "https://api.openai.com/v1"
}
}
| Field | Required | Description |
|---|
provider | Yes | ollama, openai, or cohere |
model | Yes | Model id from the tables below |
api_key | For openai / cohere | Omitted for ollama |
base_url | No (defaults applied) | Override API endpoint (proxy, custom host) |
api_key):
{
"embedding": {
"provider": "ollama",
"model": "nomic-embed-text",
"base_url": "http://host.docker.internal:11434"
}
}
base_url in the file is a template default; moorcheh up still passes the runtime URL (host.docker.internal vs http://ollama:11434) into the container based on host vs bundled Ollama.
Editing and security
- Prefer
moorcheh configure --force to change provider or model safely (with a warning if data already exists).
- You may edit
config.json by hand to tweak base_url or rotate an API key, then run moorcheh down and moorcheh up so the running container picks up changes.
- On Linux and macOS, the file is created with mode
600 (owner read/write only).
- Do not commit
config.json to git or share it in tickets — it can contain provider API keys.
- Back up
~/.moorcheh/data for your indexes; treat config.json as secrets if it includes api_key.
If provider is empty or invalid, moorcheh up fails. Run moorcheh configure --force to fix a broken file.
Supported models and dimensions
Use the same model for all text namespaces on one server. When creating a vector namespace, set vector_dimension to match your embedding model output (text namespaces infer dimension from the first embed).
Ollama (local)
| Model ID | Dimensions | Notes |
|---|
nomic-embed-text | 768 | Smaller, faster |
mxbai-embed-large | 1024 | Recommended default |
all-minilm | 384 | Smallest footprint |
moorcheh up when Ollama is reachable (host or bundled). You do not need a separate ollama pull unless you skipped pull with --skip-ollama-model-pull.
OpenAI
| Model ID | Dimensions | Notes |
|---|
text-embedding-3-small | 1536 (default) | Recommended |
text-embedding-3-large | 3072 (default) | Higher quality |
text-embedding-ada-002 | 1536 | Legacy |
config.json (file mode 600 on Unix). The server calls OpenAI from inside the container; outbound HTTPS is required.
Cohere
| Model ID | Dimensions | Notes |
|---|
embed-v4.0 | 1536 (fixed in Moorcheh) | Recommended; multimodal-capable API |
embed-english-v3.0 | 1024 | English-optimized |
embed-multilingual-v3.0 | 1024 | 100+ languages |
https://api.cohere.com/v2.
Do not mix embedding models across text namespaces on the same instance. Existing namespaces were built with one vector size; changing the model without re-uploading will break search quality and dimension checks.
What moorcheh up does by provider
| Provider | Containers started | Embedding model pull |
|---|
| openai / cohere | moorcheh-onprem-server | N/A (cloud) |
| ollama (host running) | Server only | Auto-pull if missing |
| ollama (host down) | Server + moorcheh-ollama | Auto-pull after Ollama is ready |
--embedding-provider, --embedding-model, --embedding-api-key, --bundled-ollama, --use-host-ollama. See moorcheh up.
Health check
GET /health and moorcheh status return:
{
"status": "ok",
"embedding_provider": "ollama",
"model": "nomic-embed-text",
"items": 0,
"max_items": 100000,
"remaining": 100000
}
