Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/arrozet/caret/llms.txt

Use this file to discover all available pages before exploring further.

The fastest way to run Caret is locally with Docker Compose. The entire stack — frontend, API Gateway, auth, document, collaboration, and AI services — starts from a single command. The only external dependency you need to prepare before running anything is a Supabase project, which provides managed PostgreSQL, authentication, and the pgvector extension used by the AI service for RAG embeddings.
Caret does not bundle a local PostgreSQL instance. All services connect to Supabase Cloud via the DATABASE_URL you provide. Attempting to point the services at a plain local Postgres instance will bypass Supabase Auth and Row-Level Security, causing auth and document queries to fail. Create a free Supabase project at supabase.com before proceeding.

​
Prerequisites

  • Docker and Docker Compose (v2) installed and running
  • A Supabase project with its URL, anon key, and database connection string ready
  • An OpenAI API key for the AI service (the OPENAI_API_KEY variable)

​
Setup Steps

1

Clone the Repository

Clone the Caret repository and move into the project root:
git clone https://github.com/arrozet/caret.git
cd caret
2

Create the Environment File

Create a .env file at the repository root. Docker Compose reads this file automatically and injects the values into every service that references them.
# Supabase project URL — found in Project Settings > API
SUPABASE_URL=https://your-project-ref.supabase.co

# Supabase anon (public) key — found in Project Settings > API
SUPABASE_ANON_KEY=your-anon-key

# Supabase database connection string (pooled, port 6543 recommended)
DATABASE_URL=postgresql://postgres.your-ref:your-password@aws-0-your-region.pooler.supabase.com:6543/postgres

# OpenAI API key used by the AI service for completions and embeddings
OPENAI_API_KEY=sk-...
The following variables are optional but supported by the AI service if you want to use alternative model providers:
# Optional: Anthropic and OpenRouter keys for alternative AI providers
ANTHROPIC_API_KEY=
OPENROUTER_API_KEY=
OPENROUTER_MODEL=deepseek/deepseek-v4-flash
Additional variables consumed by the auth, document, and collab services (such as SUPABASE_SERVICE_ROLE_KEY, JWT_SECRET, and SUPABASE_JWT_SECRET) are not strictly required for local development but can be added if you need to exercise service-role operations or JWT verification in the collab service:
# Optional for local dev: used by auth-service and document-service for service-role operations
SUPABASE_SERVICE_ROLE_KEY=your-service-role-key
JWT_SECRET=your-supabase-jwt-secret

# Optional for local dev: used by collab-service to verify Supabase-issued JWTs
SUPABASE_JWT_SECRET=your-supabase-jwt-secret
3

Start All Services

Build and start the full stack with a single command from the repo root:
docker compose up --build
Docker Compose will build images for all six services and start them in dependency order. Health checks run every 10 seconds; wait until all services report as healthy before proceeding. On subsequent runs, omit --build if you have not changed any source files:
docker compose up
4

Open the Frontend

Once all containers are running, open your browser at:
http://localhost:5173
The React frontend is served by the Vite dev server on port 5173. It communicates with the API Gateway at http://localhost:3000/api/v1 and opens a WebSocket connection to the collab service at ws://localhost:3003 when you open a document.
5

Sign In and Explore

  1. Sign in using the Supabase Auth flow (email/password or any provider you have enabled in your Supabase project dashboard).
  2. Create a workspace — workspaces are the top-level container for your documents.
  3. Create a folder (optional) inside the workspace to organise documents.
  4. Create a document and start writing in the Tiptap editor.
  5. Open the AI panel with Ctrl+K (or Cmd+K on macOS) to interact with the agentic AI assistant. Switch between general and analyst modes from within the panel.

​
Service Ports

All services expose their ports on localhost during local development:
ServicePortNotes
Frontend5173React + Vite dev server
API Gateway3000Routes all /api/v1/... REST traffic
Auth Service3001Reached by the gateway; handles Supabase Auth
Document Service3002Workspaces, folders, and documents CRUD
Collab Service3003WebSocket — frontend connects directly, not through the gateway
AI Service8000FastAPI — completions, embeddings, and RAG

​
Makefile Shortcuts

The repo ships with a Makefile that wraps common Docker Compose and per-service commands so you do not have to remember long invocations.
make up            # docker compose up --build
make up-nocache    # force a clean build with --no-cache, then up
make down          # docker compose down
make logs          # docker compose logs -f (stream all logs)
make ps            # docker compose ps (show running containers)
Per-service targets follow the pattern make <service>-<action>, for example:
make frontend-lint          # run ESLint on the frontend
make frontend-test-unit     # run Vitest unit tests
make ai-service-test-unit   # run Pytest unit tests for the AI service
Run make help or inspect the Makefile at the repo root for the full list of targets.

Build docs developers (and LLMs) love

Get started for freeTalk to us