Prerequisites

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

Vector-only workflows (precomputed vectors, no text upload/search) do not need any embedding provider or Ollama.

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

If ~/.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). The image is published for linux/amd64 and linux/arm64, so Docker Desktop on Apple Silicon Macs runs natively without emulation. 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

Default ports:

Port	Service
8080	Moorcheh API
11434	Ollama (only when using Ollama provider and bundled/host Ollama)

moorcheh up --server-port 8081

Network: Pull moorcheh/server from Docker Hub. The image supports Intel and Apple Silicon Macs, Windows, and Linux (linux/amd64 and linux/arm64). Cloud providers also need outbound HTTPS from the server container to OpenAI or Cohere.

Docker Desktop vs Docker Engine

Platform	Typical setup
macOS	Docker Desktop (recommended)
Windows	Docker Desktop or Docker Engine with WSL2
Linux	Docker Engine + Compose plugin

You only need a running Docker daemon (docker info succeeds). Docker Desktop is the most common way to get that on macOS and Windows, but it is not required on Linux.

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 model
moorcheh 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

API key from dashboard.cohere.com
Default base URL: https://api.cohere.com/v2

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

Expected: "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

Getting Started

Summary

How install and startup work

Python

Docker

Docker Desktop vs Docker Engine

Embedding provider

Ollama (optional)

Host vs bundled

Option A — Host Ollama

Option B — Bundled Ollama (no host install)

Vector-only

Cloud embedding providers

OpenAI

Cohere

Checklist before Quickstart

Troubleshooting

Next steps

​Summary

​How install and startup work

​Python

​Docker

​Docker Desktop vs Docker Engine

​Embedding provider

​Ollama (optional)

​Host vs bundled

​Option A — Host Ollama

​Option B — Bundled Ollama (no host install)

​Vector-only

​Cloud embedding providers

​OpenAI

​Cohere

​Checklist before Quickstart

​Troubleshooting

​Next steps

Summary

How install and startup work

Python

Docker

Docker Desktop vs Docker Engine

Embedding provider

Ollama (optional)

Host vs bundled

Option A — Host Ollama

Option B — Bundled Ollama (no host install)

Vector-only

Cloud embedding providers

OpenAI

Cohere

Checklist before Quickstart

Troubleshooting

Next steps