Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/karpathy/llm-council/llms.txt

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

LLM Council runs entirely on your local machine — a FastAPI backend talks to OpenRouter on your behalf and a Vite-powered React frontend gives you the chat interface. Follow the steps below to go from a fresh clone to a running app in just a few minutes.
The backend runs on port 8001 and the frontend runs on port 5173. Make sure neither port is occupied by another process before starting.
1

Check Prerequisites

Before you begin, confirm the following are installed on your system:
  • Python 3.10 or later — required by the FastAPI backend
  • Node.js (LTS recommended) — required to run the React frontend
  • uv — the Python package manager used by this project. Install it from docs.astral.sh/uv if you don’t have it yet
  • An OpenRouter API key — LLM Council routes all model queries through OpenRouter. Sign up at openrouter.ai and purchase credits (or enable auto top-up) before proceeding
# Verify Python version
python --version

# Verify Node.js
node --version

# Verify uv
uv --version
2

Clone the Repository

Clone the project from GitHub and navigate into the project directory:
git clone https://github.com/karpathy/llm-council.git && cd llm-council
3

Install Backend Dependencies

Use uv to create a virtual environment and install all Python dependencies declared in pyproject.toml:
uv sync
This installs FastAPI, Uvicorn, httpx, pydantic, and python-dotenv into an isolated environment managed by uv.
4

Install Frontend Dependencies

Move into the frontend/ directory, install Node dependencies, then return to the project root:
cd frontend && npm install && cd ..
This pulls in React 19, Vite, react-markdown, and the related dev tooling.
5

Configure Your API Key

Create a .env file in the project root (next to pyproject.toml) and add your OpenRouter API key:
.env
OPENROUTER_API_KEY=sk-or-v1-...
The backend reads this value at startup via python-dotenv. The key is never hardcoded in source files. If the variable is missing, model queries will fail with authentication errors.
Get your key at openrouter.ai. You will need to add credits to your account — OpenRouter charges per-token based on the models you select. Consider enabling automatic top-up so the app doesn’t stall mid-session.
6

Start the Application

You can start both servers with a single command or manage them in separate terminals.
./start.sh
The ./start.sh script launches both the backend and frontend as background processes and registers a SIGINT/SIGTERM trap — pressing Ctrl+C in the same terminal cleanly shuts down both servers at once. If you run the servers manually in separate terminals you will need to stop each one individually.
7

Open the App in Your Browser

Once both servers are running, navigate to the frontend in your browser:
http://localhost:5173
You should see the LLM Council chat interface. Type any question and press Enter to trigger the three-stage pipeline. The UI will progressively reveal Stage 1 responses, Stage 2 peer reviews, and the Stage 3 Chairman synthesis as each stage completes.

​
Verifying the Backend

If the UI does not load or model queries fail, confirm the backend is healthy by hitting the root health-check endpoint: 
curl http://localhost:8001/
A healthy backend responds with: 
{"status": "ok", "service": "LLM Council API"}
If you receive a connection error, check that the backend process started without import errors (missing .env file or wrong working directory are the most common causes). Always run the backend from the project root using python -m backend.main, not from inside the backend/ directory — relative imports in the backend modules depend on this.

Build docs developers (and LLMs) love

Get started for freeTalk to us