J Jozie AI / Model Builder
Installation Guide

Local installation · macOS

Run Jozie AI on your own machine

Jozie AI is a local-first platform for building, training, and evaluating domain-specific AI models — no data leaves your machine. This guide walks through every command needed to get the full stack running, end to end.

~25–35 min macOS + Homebrew Python 3.11+ Node 18+ Apple Silicon for fine-tuning

Prerequisites

Install these before starting. Everything below assumes a Mac with Homebrew already set up.

Python 3.11+

Backend & workers. Developed against 3.14.

Node 18+

Frontend. Developed against 22.

Homebrew

Installs Postgres, Redis, pgvector, Caddy.

Ollama

Running locally, with a chat model (llama3.1:8b) and embeddinggemma pulled.

Apple Silicon

Only required for the Fine-Tuning module (MLX is Apple GPU-only). Everything else runs fine on Intel.

1

Database & queue

Postgres (with the pgvector extension) stores everything; Redis backs the background job queue and live progress updates.

terminal 
# install & start services
brew install postgresql@16 redis pgvector
LC_ALL="en_US.UTF-8" /opt/homebrew/opt/postgresql@16/bin/postgres -D /opt/homebrew/var/postgresql@16 &
/opt/homebrew/opt/redis/bin/redis-server /opt/homebrew/etc/redis.conf &

# create the database, app role, and vector extension
export PATH="/opt/homebrew/opt/postgresql@16/bin:$PATH"
createdb jozie_ai
psql -d jozie_ai -c "CREATE ROLE jozie_app WITH LOGIN PASSWORD 'jozie_dev_local' CREATEDB;"
psql -d jozie_ai -c "ALTER DATABASE jozie_ai OWNER TO jozie_app;"
psql -d jozie_ai -c "CREATE EXTENSION IF NOT EXISTS vector;"
IF

The CREATE EXTENSION vector step fails with a missing-file error, Homebrew's pgvector bottle doesn't match your Postgres version — build it from source instead:

terminal — pgvector from source 
git clone --branch v0.8.5 --depth 1 https://github.com/pgvector/pgvector.git /tmp/pgvector-src
cd /tmp/pgvector-src
PG_CONFIG=/opt/homebrew/opt/postgresql@16/bin/pg_config make -j4
PG_CONFIG=/opt/homebrew/opt/postgresql@16/bin/pg_config make install
i

If your environment supports launchd background services, brew services start postgresql@16 and brew services start redis work too — the commands above just run them directly, which works everywhere.

2

Backend

Sets up the Python environment, installs dependencies, and applies the database schema.

terminal — backend/ 
cd backend
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env   # defaults already match the DB/Redis setup above
mkdir -p data/uploads logs
alembic upgrade head
3

Frontend

Installs the React/Vite app.

terminal — frontend/ 
cd frontend
npm install
cp .env.example .env   # dev: http://localhost:8000/api/v1
4

Fine-tuning setup Optional · Apple Silicon

Only needed for the Fine-Tuning module. It trains real LoRA adapters on-device via Apple's MLX framework, then converts the result to GGUF using llama.cpp's own converter — which needs an isolated Python environment so its older dependency pins don't downgrade the main app.

terminal — backend/ 
cd backend
git clone --depth 1 https://github.com/ggml-org/llama.cpp vendor-llama-cpp-convert
python3 -m venv .venv-gguf
source .venv-gguf/bin/activate
pip install -r vendor-llama-cpp-convert/requirements/requirements-convert_hf_to_gguf.txt
deactivate
i

That's it — the pipeline calls .venv-gguf/bin/python3 by path at runtime, so no activation is needed later. Base models download from Hugging Face on first use (a few hundred MB to a few GB) and cache under ~/.cache/huggingface.

Run it

Three processes, each in its own terminal tab. Leave all three running.

API server

terminal 1 
cd backend && source .venv/bin/activate
uvicorn app.main:app --reload --port 8000

Background worker

terminal 2 
cd backend && source .venv/bin/activate
celery -A app.core.celery_app worker --loglevel=info

Frontend

terminal 3 
cd frontend
npm run dev

Open http://localhost:5173 and click Create org to register your first account.

First walkthrough

Once you're in, this is the natural order to try each module — each step feeds the next.

  1. Knowledge Base — upload a document, wait for cleaned, confirm the cleaned text.
  2. Datasets — create a dataset, Generate from the confirmed document, approve examples in the review queue.
  3. RAG Builder — index the confirmed document, run a semantic/hybrid search over it.
  4. Prompt Library — save a system prompt.
  5. Conversation Testing — chat with a saved prompt + RAG on, thumbs-up a good answer, Add to training data.
  6. Evaluation — run a target model against approved examples, optionally RAG-augmented.
  7. Model Registry — bake a saved prompt into a named custom Ollama model.
  8. Fine-Tuning (needs step 4 above) — once a dataset has 6+ approved examples, start a job and watch it train, fuse, convert, and land as a new Ollama tag.
  9. Administration — invite a teammate, issue an API key, review the audit log.

API docs (OpenAPI/Swagger, local only by default): http://localhost:8000/docs

Production deployment Optional

A hardened, supervised setup for running Jozie AI persistently on this machine rather than in terminal tabs — a built frontend behind Caddy with local HTTPS, and launchd-supervised backend/worker processes with nightly backups.

terminal 
cd frontend && npm run build          # builds against .env.production
brew install caddy
caddy trust                            # installs Caddy's local CA — prompts for sudo once
./deploy/scripts/install-services.sh   # launchd: backend + worker + nightly backup
caddy run --config deploy/Caddyfile

Then visit https://localhost.

!

Before doing this for real, set ENVIRONMENT=production and generate a real JWT_SECRET (openssl rand -hex 32) in backend/.env — the app refuses to boot in production mode with the default secret.

Troubleshooting

Known rough edges and how to get past them.

Ollama model creation fails with a permissions error›

The ollama create flow (used by Model Registry and Fine-Tuning) needs Ollama's own model blob files to be owned by the user running the daemon. If you ever ran sudo ollama pull, some blobs may be root-owned.

Fix: sudo chown -R $(whoami):staff ~/.ollama/models

Dataset generation returns oddly-shaped or missing examples›

Ollama's format: "json" forces valid JSON but not a specific shape — a single-example request sometimes returns one object instead of an array. This is handled defensively already; if you see it in your own logs, it's expected and non-fatal.

Fine-tuning: GGUF export or Ollama import fails›

Make sure step 4 above was completed — the isolated .venv-gguf and vendor-llama-cpp-convert clone both need to exist under backend/. If the error mentions a missing module inside that venv, re-run the pip install line from step 4.

Postgres or Redis won't start›

Check nothing else is already bound to 5432 or 6379. If a previous run left a stale process, stop it before re-running the commands in step 1 — running them twice is safe otherwise.

Verify the install

Everything is working if:

  • http://localhost:8000/docs loads the API reference
  • http://localhost:5173 shows the sign-in screen
  • the Dashboard shows Ollama and Database as Reachable after logging in
  • uploading a document in Knowledge Base reaches cleaned status within a minute or two
This guide mirrors README.md at the repository root — treat the README as the source of truth if the two ever drift.