Overview
Starts the Moorcheh API in Docker using settings from ~/.moorcheh/config.json (or an interactive wizard on first run). Behavior depends on embedding provider:
| Provider | Containers | Ollama |
|---|
| openai / cohere | Moorcheh server only | Not started |
| ollama | Server; plus moorcheh-ollama if host Ollama is down | Auto-pull embedding model if missing |
~/.moorcheh/data.
After moorcheh configure: If the stack is already running, run moorcheh down then moorcheh up so embedding and LLM settings from config.json are applied to the server container. See moorcheh configure — Apply changes. If ~/.moorcheh/data already has text namespaces and you change the embedding provider or model, search and RAG /answer for that data may break until you re-upload documents. The configure wizard warns when stored data is detected.
Synopsis
Options
| Flag | Default | Description |
|---|
--server-image | moorcheh/server:latest | Docker image for the API server |
--server-port | 8080 | Host port for the API |
--embedding-provider | from config | ollama, openai, or cohere |
--embedding-model | from config | Provider-specific model id |
--embedding-api-key | from config | Required for openai/cohere when not in config |
--configure | off | Run interactive embedding setup before start |
--no-configure | off | Fail if config.json is missing (no prompts) |
--skip-ollama-model-pull | off | Ollama only: check model but do not pull |
--ollama-image | ollama/ollama:latest | Image when starting bundled Ollama |
--ollama-port | 11434 | Host port to probe or publish bundled Ollama |
--ollama-host | 127.0.0.1 | Host to probe for existing Ollama |
--ollama-model | — | Deprecated alias for --embedding-model |
--bundled-ollama | off | Always start moorcheh-ollama (ollama provider only) |
--use-host-ollama | off | Never start moorcheh-ollama (ollama provider only) |
--bundled-ollama and --use-host-ollama apply only when the embedding provider is ollama. They are ignored for OpenAI/Cohere.
You cannot use --bundled-ollama and --use-host-ollama together (exit code 1).
First run (no config)
If ~/.moorcheh/config.json does not exist, moorcheh up runs the same prompts as moorcheh configure:
- Provider: ollama / openai / cohere
- Model (numbered menu)
- API key (cloud providers only)
For ollama when Ollama is not running yet, configure saves your choice; moorcheh up then starts bundled Ollama and pulls the model automatically.
Ollama provider flow
Examples
# Use saved config (or interactive wizard)
moorcheh up
# Cloud provider without wizard
moorcheh up --embedding-provider openai --embedding-model text-embedding-3-small --embedding-api-key "$OPENAI_API_KEY" --no-configure
# Force bundled Ollama
moorcheh up --bundled-ollama
# Host Ollama only
moorcheh up --use-host-ollama
Output
Data directory: <~/.moorcheh/data>
Embedding provider: ollama | model: nomic-embed-text
<ollama or cloud summary line>
Moorcheh API: http://localhost:<server-port>
Using Ollama already running at http://127.0.0.1:11434 (moorcheh-ollama container not started)
Started Moorcheh server + Ollama container (Ollama on host port 11434)
Moorcheh server started (cloud embedding provider; Ollama not required).
Exit codes
| Code | Meaning |
|---|
0 | Stack started |
1 | Conflicting flags, missing config with --no-configure, Docker error, or Ollama not ready |
