Skip to content
2 min read · 446 words

Getting Started

This section takes you from a fresh git clone to a running platform: backend on port 8001, frontend on port 3000, and your first agent answering questions.

Prerequisites at a glance

RequirementVersionUsed forCheck with
Python≥ 3.14FastAPI backendpython --version
uvlatestPython dependency managementuv --version
Node.js≥ 20Next.js 15 frontendnode --version
npm≥ 10Frontend packagesnpm --version
OpenAI API key—All LLM and embedding callsplatform.openai.com
Gitany recentCloning and contributinggit --version

Every intelligent feature — chat, email analysis, workflows, embeddings, RAG — calls the OpenAI API. Without OPENAI_API_KEY in backend/app/.env (or your environment), those endpoints raise ValueError: OPENAI_API_KEY is missing and chats return the fallback message "Sorry, I could not generate a response right now." See Configuration.

Your path through this section

[Installation](installation.md)Clone the repo, install backend deps with `uv`, install frontend deps with `npm`, and verify both servers boot.Installation [Quick Start](quick-start.md)Five minutes: create an agent, chat with it, analyze an email, and ask a question about an uploaded document.Quick Start [Configuration](configuration.md)Every environment variable the platform reads, its default, and what breaks without it.Configuration [Project Structure](project-structure.md)What every top-level folder and file is for — including which files are scratch code you should ignore.Project Structure

The 30-second version

bash
# Backend (terminal 1)
cd backend
uv sync
echo "OPENAI_API_KEY=sk-your-key" > app/.env
cd app && uv run uvicorn main:app --reload --port 8001
 
# Frontend (terminal 2)
cd frontend
npm install
npm run dev

Then open:

What happens on first boot

When the backend starts, backend/app/main.py does three things before serving traffic (details in Application Entry):

  1. Base.metadata.create_all(bind=engine) — creates all SQLite tables in agentops.db if they do not exist.
  2. run_startup_migrations() — adds the model_name, estimated_tokens, and estimated_cost columns to tool_calls on older databases (Migrations).
  3. Mounts the agents and documents routers under /agents.

The first document upload also creates the chroma_db/ folder — the persistent Chroma vector store (RAG Ingestion).

PreviousBrowse by TagNextInstallation