Installation#

Install both halves of the platform — the FastAPI backend and the Next.js frontend — and verify each one is healthy.

1. Clone the repository#

git clone https://github.com/ahmedjajan93/veyraops_ai.git
cd veyraops_ai

2. Install the backend#

The backend lives in backend/ and is managed with uv. Dependencies are pinned in backend/pyproject.toml and backend/uv.lock:

requires-python = ">=3.14"
dependencies = [
    "chromadb>=1.5.9",
    "fastapi>=0.136.3",
    "langgraph>=1.2.5",
    "openai>=2.38.0",
    "python-dotenv>=1.2.2",
    "python-multipart>=0.0.32",
    "sqlalchemy>=2.0.50",
    "uvicorn>=0.48.0",
]

# Install uv if you don't have it
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
 
cd backend
uv sync

uv sync creates backend/.venv and installs everything from the lock file. You never need to activate the venv manually — prefix commands with uv run.

Configure the OpenAI key#

Create backend/app/.env (loaded by python-dotenv in the service modules):

OPENAI_API_KEY=sk-your-key-here
# Optional overrides (defaults shown)
OPENAI_MODEL=gpt-4o-mini
OPENAI_EMBEDDING_MODEL=text-embedding-3-small

See Configuration for the full variable reference.

Start the backend#

The app imports its own modules as top-level names (from database import ...), so run uvicorn from inside backend/app/:

cd backend/app
uv run uvicorn main:app --reload --port 8001

Verify the backend#

curl http://localhost:8001/health

{ "status": "ok", "service": "agentops-ai-backend" }

Interactive Swagger UI is at http://localhost:8001/docs — every endpoint in the API Reference can be exercised from there.

On first boot the backend creates backend/app/agentops.db (SQLite). The Chroma store backend/app/chroma_db/ appears after the first document upload. Both are runtime artifacts — never commit them.

3. Install the frontend#

cd frontend
npm install
npm run dev

Open http://localhost:3000 — the root page redirects to /dashboard.

4. Build the documentation site (optional)#

The docs you are reading are built with MkDocs Material. Dependencies are in the root pyproject.toml / requirements.txt:

# from the repository root
uv sync
uv run mkdocs serve   # http://localhost:8000

Common installation problems#

Next steps#

• Quick Start — create your first agent and exercise every feature
• Project Structure — learn what every folder is for
• Architecture — the big picture