Documentation Index
Fetch the complete documentation index at: https://docs.moorcheh.ai/llms.txt
Use this file to discover all available pages before exploring further.
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 |
| Ollama | Yes for text workflows | Embeds documents and text search queries |
| Ollama | Optional for vector-only | Precomputed vector upload/search does not call Ollama |
How install and startup work
You only run two commands yourself:
pip install moorcheh-client
moorcheh up
| Step | What it does | What it does not do |
|---|
pip install moorcheh-client | Installs the moorcheh CLI, MoorchehApiClient Python SDK, and a docker-compose.yml bundled inside the package | Does not start Docker, pull images, or run the server |
moorcheh up | Finds that bundled compose file automatically, runs docker compose, starts container(s), creates ~/.moorcheh/data | You do not need to locate or edit the compose file |
moorcheh up, Docker pulls moorcheh/server:latest from Docker Hub (if not cached). If host Ollama is not running, it also starts a moorcheh-ollama container.
You need a working Docker daemon and docker compose (Compose V2). You do not need Docker Desktop specifically if another Docker setup provides those.
You do not need to build Moorcheh from source or run docker compose manually. That happens inside moorcheh up.
Python
Version: Python 3.10 or newer
Check your version:
python --version
# or
python3 --version
pip install moorcheh-client
- The
moorcheh CLI — run moorcheh up, moorcheh search, etc.
MoorchehApiClient — call the API from Python- A compose file at
moorcheh/compose/docker-compose.yml inside the package (used automatically by moorcheh up; you never need to open it)
pip install alone does not start the server. Run moorcheh up after installing.
Use a virtual environment (python -m venv .venv) if you prefer isolated Python installs. Moorcheh does not require Node.js, Rust, or a local Moorcheh source checkout.
Docker
What Docker is used for
Moorcheh on-prem runs the API server inside a Docker container. The Python package is a launcher — it does not include the Rust server binary itself.
When you run moorcheh up, it:
- Locates the compose file bundled in the installed package
- Runs
docker compose up -d to start the server (and optionally Ollama)
- Mounts
~/.moorcheh/data so your namespaces and items persist on disk
You never need to find the compose file path or run docker compose yourself unless you are debugging.
On first start, Docker pulls moorcheh/server:latest from Docker Hub. No manual docker pull is required unless you want to pre-fetch the image.
What you must have installed
| Component | Required | Notes |
|---|
Docker CLI (docker) | Yes | Must be on your PATH |
Docker Compose V2 (docker compose) | Yes | Integrated plugin — not the legacy standalone docker-compose binary |
| Running Docker daemon | Yes | docker info should succeed without errors |
docker --version
docker compose version
docker info
docker info fails, the daemon is not running or your user lacks permission to access it.
Docker Desktop vs Docker Engine
Docker Desktop is not strictly required. It is the most common way to get Docker on Windows and macOS, but any setup that provides docker + docker compose + a running daemon works.
| Platform | Typical setup | Notes |
|---|
| Windows | Docker Desktop | Uses WSL 2 backend; recommended for most users |
| macOS | Docker Desktop | Apple Silicon and Intel builds available |
| Linux | Docker Engine + Compose plugin | Docker Desktop for Linux is optional |
sudo systemctl enable --now docker
sudo usermod -aG docker $USER # log out/in so your user can run docker without sudo
docker compose version
docker compose works before running moorcheh up.
Ports and disk space
Default host ports:
| Port | Service |
|---|
| 8080 | Moorcheh API (http://localhost:8080) |
| 11434 | Ollama (when bundled or running on the host) |
moorcheh up --server-port 8081
moorcheh up --bundled-ollama --ollama-port 11435
moorcheh/server, optionally ollama/ollama) plus your data under ~/.moorcheh/data and Ollama model weights (~hundreds of MB for nomic-embed-text).
Network: First moorcheh up needs outbound access to Docker Hub to pull images.
Ollama
Ollama provides embedding models. Moorcheh uses it when:
- Uploading documents to a text namespace (embed each document)
- Running text semantic search (embed the query string)
Vector namespaces (you supply precomputed vectors) do not call Ollama for upload or vector-query search. If you only use vector namespaces, Ollama is still started by default when not detected on the host — you can ignore it for vector-only workflows, or use --use-host-ollama without running Ollama if you never use text features.
Default embedding model
| Setting | Default |
|---|
| Model | nomic-embed-text |
| Ollama URL (inside server container) | Set automatically by moorcheh up |
moorcheh status / GET /health under "model".
Two ways to run Ollama
moorcheh up picks automatically unless you pass a flag:
| Mode | When | Command |
|---|
| Auto (default) | Use host Ollama if already running; otherwise start bundled container | moorcheh up |
| Bundled Ollama | Always run Ollama in Docker (good if you don’t want a separate Ollama install) | moorcheh up --bundled-ollama |
| Host Ollama only | Never start moorcheh-ollama; server must reach Ollama on the host | moorcheh up --use-host-ollama |
Option A — Install Ollama on the host (recommended for daily dev)
- Download from ollama.com (Windows, macOS, or Linux).
- Start Ollama (it listens on
http://127.0.0.1:11434 by default).
- Pull the embedding model:
ollama pull nomic-embed-text
- Start Moorcheh:
You should see:
Using Ollama already running at http://127.0.0.1:11434 (moorcheh-ollama container not started)
curl http://127.0.0.1:11434/
Option B — Bundled Ollama (no host install)
If Ollama is not running on the host, moorcheh up starts moorcheh-ollama automatically using the ollama/ollama:latest image.
To force bundled Ollama even when host Ollama is running:
moorcheh up --bundled-ollama
docker exec moorcheh-ollama ollama pull nomic-embed-text
ollama_data), separate from a host Ollama install.
Option C — Vector-only (Ollama optional)
If you only use vector namespaces and vector search queries:
- You can upload and search without Ollama handling your data
moorcheh up may still start bundled Ollama when none is detected on the host (harmless if unused)- Text upload or text search will fail until Ollama is available and the model is pulled
Checklist before Quickstart
Run through this list once:
# 1. Python 3.10+
python --version
# 2. Docker daemon + Compose V2
docker info
docker compose version
# 3. Install Moorcheh client
pip install moorcheh-client
# 4. (Text workflows) Ollama + model
ollama pull nomic-embed-text # skip if using bundled Ollama only
# 5. Start Moorcheh
moorcheh up
moorcheh status
moorcheh status: "status": "ok" and "model": "nomic-embed-text".
If text upload jobs fail with Ollama errors, confirm the model is pulled and Ollama is reachable from the server container (host Ollama on 127.0.0.1:11434, or bundled container running).
Troubleshooting
| Symptom | Likely cause | What to try |
|---|
docker: command not found | Docker not installed or not on PATH | Install Docker Desktop or Docker Engine |
Cannot connect to the Docker daemon | Daemon not running | Start Docker Desktop or sudo systemctl start docker |
docker compose fails | Compose V2 missing | Install Compose plugin |
Error: docker compose failed on moorcheh up | Port in use, pull failed, permissions | Check 8080 / 11434; run docker pull moorcheh/server:latest; see moorcheh up |
| Text upload/search fails | Ollama down or model missing | ollama pull nomic-embed-text; or docker exec moorcheh-ollama ollama pull nomic-embed-text |
| Slow first text upload | Model downloading inside Ollama | Wait for pull to finish; retry upload |
Next steps
