Quickstart

Get a fully working CRTX instance — backend API, background worker, and frontend — running locally in about 15 minutes.

Want to run this for real users or inside a customer's infrastructure instead of on your laptop? See Self-hosting & deploying in your environment.

---

#Prerequisites

• Python 3.13+
• Node.js 20+ and Bun
• A running Redis instance (redis://localhost:6379 by default)
• Accounts with:
  • Supabase — auth, Postgres, and file storage
  • Pinecone — the vector index
  • OpenAI — embeddings, generation, vision, and the eval judge
  • (optional) Cohere — reranking

---

#1. Clone

git clone https://github.com/YOUR_USERNAME/crtx.git
cd crtx

#2. Provision the external services

Pinecone. Create a serverless index (name it e.g. crtx-documents) with dimension 1024 and metric cosine (matching text-embedding-3-small at 1024 dims). Note the index name and API key.

Supabase. Create a project, then:

1. Copy the project URL, the service role key (server-side secret), the anon key (client-side), and the JWKS URL (https://<project>.supabase.co/auth/v1/.well-known/jwks.json).
2. Create two Storage buckets: documents (private — original files, served via time-limited signed URLs) and images (public — extracted PDF figures, whose public URLs are stored in vector metadata).
3. Enable email/password auth.
4. Create the application tables. CRTX reads/writes: collections, collection_members, collection_shares, collection_documents, document_chunks, chat_sessions, chat_messages, ingest_jobs, rag_evals, plus the query_logs / ingest_logs observability tables. (Apply your project's migration/SQL for these; the columns each endpoint expects are documented in the API reference.)

OpenAI. Create an API key.

#3. Backend

cd backend
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt

Create backend/app/.env (this project loads env from backend/app/.env, which overrides the defaults in config.py):

# Supabase
SUPABASE_URL=https://<your-project>.supabase.co
SUPABASE_SECRET_KEY=<service role key>
SUPABASE_JWKS_URL=https://<your-project>.supabase.co/auth/v1/.well-known/jwks.json

# OpenAI
OPENAI_API_KEY=sk-...

# Pinecone
PINECONE_API_KEY=...
PINECONE_INDEX=crtx-documents

# Redis (required for ingestion + async eval scoring)
REDIS_URL=redis://localhost:6379

# CORS — the frontend origin(s), comma-separated
ALLOWED_ORIGINS=http://localhost:3000

Every tunable (chunk size, Top-K, retrieval defaults, vision model, reranking) has a sensible default and is documented in Configuration.

Now start both processes — the API and the worker. The worker is not optional: ingestion and async eval scoring run through it.

# Terminal 1 — API
uvicorn app.main:app --reload --port 8000

# Terminal 2 — background worker
arq app.worker.WorkerSettings

Sanity check: open http://localhost:8000/docs for FastAPI's auto-generated Swagger UI.

#4. Frontend

cd frontend
bun install

Create frontend/.env.local:

NEXT_PUBLIC_API_URL=http://localhost:8000
NEXT_PUBLIC_SUPABASE_URL=https://<your-project>.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=<anon key>

bun dev

Open http://localhost:3000.

---

#5. First run: from zero to a cited answer

1. Sign up at /login (email/password, via Supabase).
2. Create a collection — this becomes an isolated Pinecone namespace.
3. Upload a document (PDF, DOCX, PPTX, XLSX, CSV, TXT, or MD — up to 50 MB) or paste a URL. Ingestion runs in the background; watch the job progress (chunks_processed / chunks_total).
4. Ask a question. The answer streams in with its sources listed above it. Figure sources render inline.
5. Open the Evaluation dashboard to see faithfulness and context-relevance scores accumulate.

---

#Troubleshooting

Next: Ingesting documents →