Skip to content

Getting Started

Get the Companion application running on your local machine in 15 minutes.

Prefer Docker? The entire stack (backend, Postgres, frontend, Firebase emulators) can run in containers with no local Python/Node services — see Docker Dev & Testing.

Prerequisites

Install these before starting:

Windows-Specific Notes

On Windows, use PowerShell for all commands. Python commands use python (not python3).

Step 1: Clone the Repository

git clone <repo-url>
cd ideator

Step 2: Configure Environment

# Copy the environment template
cp .env.example .env  # Unix/macOS
# Copy-Item .env.example .env  # Windows PowerShell

Edit .env and set at minimum:

OPENAI_API_KEY=sk-your-key-here
OPENAI_MODEL_NAME=gpt-4o
LANGGRAPH_STRICT_MSGPACK=true

See .env.example for all available options.

Step 3: Set Up the Backend

Choose the environment you are working with:

python -m venv .venv
.venv\Scripts\activate  # Windows
cd backend
pip install -r requirements.txt

Beta is deployed by pushing to develop. Monitor the deployment with:

gh run list --workflow release-beta.yml --limit 5

Production is released through a pull request merged into main:

gh run list --workflow release-prod.yml --limit 5

# Create virtual environment
python -m venv .venv

# Activate it
.venv\Scripts\activate  # Windows
# source .venv/bin/activate  # macOS/Linux

# Install dependencies
cd backend
pip install -r requirements.txt
cd ..

Step 4: Start the Backend

From the project root, in one terminal:

.venv\Scripts\activate  # If not already activated
cd backend
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

You should see: INFO: Uvicorn running on http://0.0.0.0:8000

Verify the health endpoint:

curl http://localhost:8000/health
# Windows alternative: Invoke-RestMethod http://localhost:8000/health

Step 5: Set Up the Frontend

In a second terminal:

cd frontend
npm install

Step 6: Start the Frontend

In the second terminal (with backend still running):

# Set the API proxy
$env:VITE_API_PROXY="http://localhost:8000"

# Start the dev server
npm run dev

You should see: Local: http://localhost:3000/

Step 7: Verify Everything Works

  1. Open http://localhost:3000 in your browser
  2. You should see the Companion chat interface
  3. Send a test message — you should see streaming agent responses

Running Tests

Backend Tests

cd backend
python -m pytest -v

All backend tests use in-memory SQLite and mock LLM — no API key needed.

Frontend Tests

cd frontend

# Unit tests
npm test

# E2E tests (backend must be running)
npm run test:e2e

Troubleshooting

Backend won't start

  • Port 8000 in use: Stop any process on port 8000 or use --port 8001
  • Missing API key: Set OPENAI_API_KEY in .env — agent features need it
  • LANGGRAPH_STRICT_MSGPACK error: Add LANGGRAPH_STRICT_MSGPACK=true to .env

Frontend can't connect to backend

  • CORS errors: The Vite dev proxy handles this — ensure VITE_API_PROXY points to your backend
  • Backend not running: Start the backend first (port 8000), then the frontend

"Database is locked" errors

This indicates multiple SqliteSaver connections. The checkpointer is a singleton — restart the backend to clear any stale connections.

E2E tests fail

  • Backend must be running: Playwright dev tests assume the backend is on port 8000
  • Browser installation: Run npx playwright install once to install test browsers

Next Steps