Summary
| Requirement | Required? | Why |
|---|
| Python 3.10+ | Yes | Installs moorcheh-client (CLI + SDK) |
| Docker Engine | Yes | Runs the Moorcheh server container via moorcheh up |
| Docker Desktop | No (but common) | One way to get Docker on Windows/macOS — not the only option |
| Embedding provider | Yes for text workflows | Embeds documents and text search queries |
| Ollama | Only if provider is Ollama | Local embeddings; host app or bundled container |
| OpenAI / Cohere API key | Only if provider is OpenAI or Cohere | Cloud embeddings; no Ollama needed |
How install and startup work
pip install moorcheh-client
moorcheh configure # optional; first moorcheh up can do this interactively
moorcheh up
| Step | What it does | What it does not do |
|---|
pip install moorcheh-client | Installs the moorcheh CLI, MoorchehClient SDK, and bundled docker-compose.yml | Does not start Docker or configure embeddings |
moorcheh configure | Saves embedding + LLM provider, model, and API keys to ~/.moorcheh/config.json | Does not start or restart containers |
moorcheh up | Starts Docker stack per provider; for Ollama, may start bundled Ollama and pull the model | Does not apply config changes to an already-running container — use moorcheh down then moorcheh up after reconfigure |
~/.moorcheh/data already has namespaces, changing embedding settings can break existing text search until you re-upload. The configure wizard warns when data is present.
On first moorcheh up, Docker pulls moorcheh/server:latest (if not cached). Ollama (ollama/ollama:latest) is pulled only when your config uses provider ollama and host Ollama is not already running.
You do not need to build Moorcheh from source or run docker compose manually.
Python
Version: Python 3.10 or newer
python --version
pip install moorcheh-client
Docker
Moorcheh on-prem runs the API server in Docker. moorcheh up runs compose and mounts ~/.moorcheh/data (index) and ~/.moorcheh/uploads → /uploads (read-only, for file upload).
| Component | Required |
|---|
Docker CLI + Compose V2 (docker compose) | Yes |
Running daemon (docker info succeeds) | Yes |
| Port | Service |
|---|
| 8080 | Moorcheh API |
| 11434 | Ollama (only when using Ollama provider and bundled/host Ollama) |
moorcheh up --server-port 8081
moorcheh/server from Docker Hub. Cloud providers also need outbound HTTPS from the server container to OpenAI or Cohere.
Embedding provider
Pick one provider for all text namespaces on this instance. Full model list and dimensions: Embedding providers.
| Provider | You need | Moorcheh starts |
|---|
| Ollama | Nothing extra, or host Ollama | Server; optionally moorcheh-ollama + auto model pull |
| OpenAI | API key | Server only |
| Cohere | API key | Server only |
moorcheh configure
# or
moorcheh up # interactive wizard if config.json is missing
Ollama (optional)
Required only when provider is ollama in ~/.moorcheh/config.json.
Ollama is used for:
- Uploading documents to text namespaces
- File upload chunk embedding (same provider as text upload)
- Text semantic search (query strings)
Host vs bundled
| Mode | Command |
|---|
| Auto (default) | moorcheh up |
| Force bundled | moorcheh up --bundled-ollama |
| Host only | moorcheh up --use-host-ollama |
Option A — Host Ollama
- Install from ollama.com
moorcheh configure → choose ollama and a modelmoorcheh up — reuses host Ollama; pulls model if missing
Option B — Bundled Ollama (no host install)
If host Ollama is not running, moorcheh up starts moorcheh-ollama and pulls your configured model (for example nomic-embed-text).
Vector-only
If you only use vector namespaces:
- No Ollama, OpenAI, or Cohere setup required
moorcheh up starts only the server when config uses a cloud provider- If config still says
ollama, switch with moorcheh configure --force or use OpenAI/Cohere
Cloud embedding providers
OpenAI
- API key from platform.openai.com
- Set during
moorcheh configure or moorcheh up --embedding-provider openai --embedding-api-key ...
- Default base URL:
https://api.openai.com/v1 (overridable in config.json)
Cohere
Checklist before Quickstart
python --version # 3.10+
docker info
docker compose version
pip install moorcheh-client
moorcheh configure # or rely on moorcheh up wizard
moorcheh up
moorcheh status
"status": "ok", "embedding_provider", and "model" matching your config.
Troubleshooting
| Symptom | Likely cause | What to try |
|---|
docker compose fails on up | Port in use, pull failed | Check 8080; docker pull moorcheh/server:latest |
| Text upload fails (Ollama) | Model not pulled / Ollama down | moorcheh up again or ollama pull <model> |
| Text upload fails (OpenAI/Cohere) | Invalid or missing API key | moorcheh configure --force |
| Bundled Ollama never needed | Wrong provider in config | moorcheh configure → openai or cohere |
Next steps
