Getting Started

Up and Running in Three Steps

CoLoci runs entirely on your machine using Ollama — a free, open-source local model runner (ollama.com). Install Ollama, then open CoLoci — it detects which models are missing and offers to pull them for you, no terminal required. This page walks you through it.

Step 1

Install Ollama

Ollama is a free, open-source app that runs AI models locally on your hardware. Download it from ollama.com/download and follow the installer for your platform (macOS or Windows).

On macOS, Ollama installs as a menubar app and starts automatically. On Windows, it runs as a background service. Either way, once it's installed you're ready for the next step.

8 GB RAM
Minimum — works well with lighter models
16 GB RAM
Recommended — faster responses, better quality
Apple Silicon? M1 and later Macs run local models exceptionally well — the unified memory architecture gives Ollama much more headroom than an equivalent Intel or AMD machine with the same spec.
Step 2

Download and Open CoLoci

Download CoLoci from the CoLoci homepage and open the installer. On first launch, CoLoci will look for Ollama at http://localhost:11434.

CoLoci needs two kinds of model: a generation model that writes your NPCs, encounters, and lore; and an embedding model that indexes your PDFs for semantic search. If Ollama is running but doesn't have them yet, CoLoci shows a banner — "CoLoci needs <model> — Pull now" — and downloads them for you with one click. No terminal needed.

Model Used For Size
nomic-embed-text Indexing — converting PDF text to searchable embeddings ~274 MB Required
qwen3:latest Generation — best quality, handles complex queries well ~5 GB Recommended
qwen2.5:7b Generation — good quality, faster on 8 GB machines ~4.7 GB
qwen2.5:3b Index extraction — used during PDF scanning, not generation ~2 GB
Not sure which generation model to pick? qwen3:latest gives the most accurate results and runs well on any Apple Silicon Mac. On a CPU-only Windows/Linux machine, try qwen2.5:7b instead — it's faster, though occasionally less precise on rules details. Switch models anytime from Settings, no re-indexing required.

Prefer the terminal, or want to pull a model CoLoci hasn't suggested? Open a terminal (macOS: Terminal.app or iTerm; Windows: Command Prompt or PowerShell) and run ollama pull <model> directly — or use the Add a Model field in Settings → Generation, which pulls any Ollama model by name from inside the app.

If CoLoci shows an Ollama warning banner instead, make sure the Ollama app is running (macOS: check your menubar for the Ollama icon; Windows: check the system tray). You can also change the Ollama URL in Settings → Connection if you're running it at a different address.

Step 3

Index Your First Book

Click + Add Book in the sidebar and select a PDF from your collection. CoLoci will read the text, extract the structure, and build a searchable index. How long this takes depends on the book:

Typical indexing times
50-page supplement   ~1–2 minutes 300-page corebook    ~5–8 minutes Scanned / image PDF  ~10–20 minutes (OCR)

You can queue multiple books and CoLoci will process them in the background. Once a book is indexed it stays indexed — you only need to do this once per PDF.

Scanned PDFs? If your PDF was created by scanning physical pages rather than exporting from a layout application, CoLoci will detect this and offer to run OCR automatically. OCR takes longer but the result is the same — a fully searchable index.
Step 4

Ask Your First Question

Select the indexed book in the sidebar (it should be selected by default after indexing), choose a template from the tabs at the top — NPC, Encounter, Freeform, and more — type your prompt, and hit Ask CoLoci.

CoLoci retrieves the most relevant passages from your indexed books, hands them to the local model, and streams the answer back in real time. Everything happens on your machine.

Ready to go? Download CoLoci and start with your first 50 generations free.

Download CoLoci →