> ## 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.

# Prerequisites

> Install Python and Docker; choose Ollama, OpenAI, or Cohere for text embeddings.

## Summary

| Requirement                                           | Required?                                | Why                                                          |
| ----------------------------------------------------- | ---------------------------------------- | ------------------------------------------------------------ |
| [Python 3.10+](#python)                               | **Yes**                                  | Installs `moorcheh-client` (CLI + SDK)                       |
| [Docker Engine](#docker)                              | **Yes**                                  | Runs the Moorcheh server container via `moorcheh up`         |
| [Docker Desktop](#docker-desktop-vs-docker-engine)    | **No** (but common)                      | One way to get Docker on Windows/macOS — not the only option |
| [Embedding provider](#embedding-provider)             | **Yes for text workflows**               | Embeds documents and text search queries                     |
| [Ollama](#ollama-optional)                            | **Only if provider is Ollama**           | Local embeddings; host app or bundled container              |
| [OpenAI / Cohere API key](#cloud-embedding-providers) | **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

```bash theme={null}
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). **Ollama** (`ollama/ollama:latest`) is pulled only when your config uses provider **ollama** and host Ollama is not already running.

<Note>
  You do **not** need to build Moorcheh from source or run `docker compose` manually.
</Note>

***

## Python

**Version:** Python **3.10 or newer**

```bash theme={null}
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) |

```bash theme={null}
moorcheh up --server-port 8081
```

**Network:** Pull `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](/on-prem/guides/embedding-providers).

| Provider   | You need                                          | Moorcheh starts                                        |
| ---------- | ------------------------------------------------- | ------------------------------------------------------ |
| **Ollama** | Nothing extra, or [host Ollama](#ollama-optional) | Server; optionally `moorcheh-ollama` + auto model pull |
| **OpenAI** | API key                                           | Server only                                            |
| **Cohere** | API key                                           | Server only                                            |

```bash theme={null}
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

```mermaid theme={null}
flowchart TD
  A[moorcheh up + provider ollama] --> B{"Ollama on 127.0.0.1:11434?"}
  B -->|Yes| C[Server only → host.docker.internal]
  B -->|No| D[Start moorcheh-ollama + server]
  D --> E[Auto-pull configured embedding model]
```

| Mode               | Command                         |
| ------------------ | ------------------------------- |
| **Auto (default)** | `moorcheh up`                   |
| **Force bundled**  | `moorcheh up --bundled-ollama`  |
| **Host only**      | `moorcheh up --use-host-ollama` |

### Option A — Host Ollama

1. Install from [ollama.com](https://ollama.com/download)
2. `moorcheh configure` → choose **ollama** and a model
3. `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](https://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](https://dashboard.cohere.com/)
* Default base URL: `https://api.cohere.com/v2`

***

## Checklist before Quickstart

```bash theme={null}
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            |

***

## Next steps

* [Quickstart](/on-prem/quickstart)
* [Embedding providers](/on-prem/guides/embedding-providers)
* [moorcheh configure](/on-prem/cli/runtime/configure)
* [moorcheh up](/on-prem/cli/runtime/up)