Pensieve Docs

Local Setup

setuplocalgetting-started

Local Setup

This guide walks you through running Pensieve directly on your machine using Python and npm. This is the recommended approach for development and gives you the most control over each component.

Prerequisites

Tool Version Purpose
Python ≥ 3.11 Backend runtime
pip (or uv) Latest Python package manager
Node.js ≥ 18 Frontend build and dev server
npm ≥ 9 Frontend package manager
Git Any Clone the repository

1. Clone the Repository

git clone https://github.com/5000K/pensieve.git
cd pensieve

2. Configure Environment Variables

Pensieve uses environment variables for secrets. Create a .env file in the repository root:

# .env — loaded automatically by python-dotenv
OPENAI_API_KEY=sk-your-openai-api-key
SEARCH_API_KEY=tvly-your-tavily-api-key    # optional, for web search

The backend loads .env automatically at startup. See the Environment Variables reference for all available variables.

3. Set Up the Backend

Install the Python package in editable mode:

pip install -e ".[dev]"

Or, if you use uv:

uv sync

Start the Backend

pensieve

This starts the FastAPI server on http://127.0.0.1:8000 by default. You can override the host and port with environment variables:

PENSIEVE_HOST=0.0.0.0 PENSIEVE_PORT=9000 pensieve

Alternatively, use uvicorn directly for auto-reload during development:

uvicorn pensieve.main:app --reload --host 127.0.0.1 --port 8000

Verify the backend is running:

curl http://localhost:8000/health
# → {"status":"ok"}

4. Set Up the Frontend

In a separate terminal:

cd frontend
npm install

Start the Dev Server

npm run dev

The Vite dev server starts on http://localhost:5173 by default.

Connect to the Backend

The frontend connects to the backend using two environment variables:

Variable Default Purpose
VITE_API_URL http://localhost:8000 REST API base URL
VITE_WS_URL ws://localhost:8000/ws WebSocket endpoint

If your backend runs on a different host or port, set these before starting the dev server:

VITE_API_URL=http://localhost:9000 VITE_WS_URL=ws://localhost:9000/ws npm run dev

Or create a frontend/.env.local file (not committed to git):

VITE_API_URL=http://localhost:9000
VITE_WS_URL=ws://localhost:9000/ws

Note: VITE_* variables are embedded at build time. If you change them, restart the dev server or rebuild.

5. Build the Frontend for Production

To create an optimized production build:

cd frontend
npm run build

The output is written to frontend/dist/. You can serve it with any static file server (e.g., nginx, npx serve dist).

6. Configure Pensieve

Edit config.yaml in the repository root to configure LLM providers, search, and server settings. See Global Configuration for the full reference.

Each workspace has its own config.yaml for pipeline settings. See Workspace Configuration for details.

Running Tests

Backend Tests

pytest

Frontend Tests

cd frontend
npm test

Frontend Linting

cd frontend
npm run lint

Troubleshooting

Backend won’t start — “Configuration error”

  • Check that your .env file contains valid OPENAI_API_KEY
  • Ensure config.yaml exists in the repo root (or set PENSIEVE_CONFIG to point to it)
  • See Environment Variables for required variables

Frontend shows “Failed to fetch” errors

  • Verify the backend is running and accessible at the URL configured in VITE_API_URL
  • Check that CORS origins in Global Configuration include the frontend URL (default: http://localhost:5173)

Port already in use

Change the port with environment variables:

# Backend
PENSIEVE_PORT=9000 pensieve

# Frontend
cd frontend
npx vite --port 3001

Next Steps