Run Garage on Linux

What you get, and what you don’t

The Linux version is the same garage_rag Python package the Mac app runs inside. CI tests it on Linux on every push, against a real PostgreSQL with pgvector.

• Included: indexing folders and git repositories; Markdown, PDF, Office documents, code and .eml mail; image OCR with Tesseract; authorship attribution; hybrid search; fact distillation; and the MCP server over stdio or HTTP.
• Not on Linux: the menu-bar app and its first-run assistant, the bundled database, and the built-in llama.cpp engine. Apple Messages, Apple Mail and HEIC images need a Mac too. Use Ollama or LM Studio for embeddings and answers.

Before you start

• Python 3.13 or 3.14 and uv, which can fetch Python for you (or pipx).
• PostgreSQL with pgvector 0.7 or later. CI tests PostgreSQL 18, the version the Mac app bundles.
• Ollama or LM Studio, on this computer or on another machine you run.
• For OCR, optional: libtesseract with English language data (tesseract-ocr and tesseract-ocr-eng on Debian and Ubuntu).

1. Set up the database

On Debian or Ubuntu, with the PostgreSQL project’s apt repository set up:

sudo apt install postgresql-18 postgresql-18-pgvector tesseract-ocr tesseract-ocr-eng
sudo -u postgres createuser "$USER"
sudo -u postgres createdb --owner "$USER" garage
sudo -u postgres psql -d garage -c 'CREATE EXTENSION IF NOT EXISTS vector'

pgvector is not a trusted extension, so postgres creates it once. Your own role, which owns the database, can then apply the rest of the schema without superuser rights. If you would rather use Docker, the pgvector/pgvector:pg18 image is what CI runs.

2. Install Garage

Garage is on PyPI as garage-rag. Install it as a tool, which puts the garage and garage-mcp commands on your PATH in an environment of their own:

uv tool install --python 3.14 garage-rag
garage version

Without uv, pipx install garage-rag does the same. To update later, run uv tool upgrade garage-rag. To run the latest code from main instead of a release, use uv tool install --python 3.14 "garage-rag @ git+https://github.com/rickmark/garage-rag#subdirectory=garage_python".

3. Configure and initialize

garage config init --user                                 # writes ~/.garage.json
garage config set database.url postgresql:///garage       # the local socket, as your user
garage config set facts.provider ollama                   # no built-in engine on Linux
garage init-db

If Ollama or LM Studio runs on another machine, set embedding.ollama_host or embedding.lmstudio_host to its address. Garage sends documents and code only to that server. Communications such as mail never leave this computer; see privacy.

4. Add a model and your files

ollama pull bge-m3
garage register-model bge-m3 --provider ollama --dims 1024 --default

garage add-source notes ~/Documents/Notes --class document --trust authored
garage ingest
garage backfill
garage search "what did I decide about the deployment"

5. Connect your AI assistant

garage mcp-install --target claude-code-user   # or cursor, vscode, zed, windsurf, project
garage mcp-test

The assistant starts garage-mcp itself over stdio. To serve several clients from one process, run garage mcp-serve and register it with --http.