​
Backend Setup Guide

This guide covers how to set up and run the AgentOps backend services from the /app directory. The backend includes the API server, dashboard, database services, and observability infrastructure.

​
Architecture Overview

The AgentOps backend consists of several interconnected services:
  • API Server (api/) - FastAPI backend with authentication, billing, and data processing
  • Dashboard (dashboard/) - Next.js frontend for visualization and management
  • Supabase - Authentication and primary PostgreSQL database
  • ClickHouse - Analytics database for traces and metrics
  • OpenTelemetry Collector - Observability and trace collection
  • Redis (optional) - Caching and session storage

​
Prerequisites

Before setting up the backend, ensure you have the following installed:

​
Required Software

​
External Services

You’ll need accounts and setup for these external services:

​
Quick Start

​
1. Clone and Navigate

git clone https://github.com/AgentOps-AI/AgentOps.Next.git
cd AgentOps.Next/app

​
2. Environment Setup

Copy and configure environment files: 
# Root environment (for Docker Compose)
cp .env.example .env

# API environment
cp api/.env.example api/.env

# Dashboard environment  
cp dashboard/.env.example dashboard/.env.local

​
3. Install Dependencies

# Using Just (recommended)
just install

# Or manually:
bun install                              # Root dependencies
uv pip install -r requirements-dev.txt  # Python dev tools
cd api && uv pip install -e . && cd ..  # API dependencies
cd dashboard && bun install && cd ..    # Dashboard dependencies

​
4. Configure External Services

Update your .env files with your service credentials. See External Services Configuration below.

​
5. Start Services

# Option 1: Using Docker Compose (recommended)
docker-compose up -d

# Option 2: Using Just commands
just api-run    # Start API server
just fe-run     # Start dashboard (in another terminal)

# Option 3: Native development
cd api && uv run python run.py          # API server
cd dashboard && bun dev                  # Dashboard (in another terminal)

​
6. Verify Setup

​
External Services Configuration

​
Supabase Setup

  1. Create a new project at supabase.com
  2. Go to Settings → API to get your keys
  3. Run the database migrations: 
    cd supabase
npx supabase db push
  4. Update your .env files with: 
    NEXT_PUBLIC_SUPABASE_URL=https://your-project-id.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=your-anon-key
SUPABASE_SERVICE_ROLE_KEY=your-service-role-key
SUPABASE_PROJECT_ID=your-project-id

​
ClickHouse Setup

  1. Sign up for ClickHouse Cloud or self-host
  2. Create a database and get connection details
  3. Run the ClickHouse migrations: 
    # Apply schema from clickhouse/schema_dump.sql
  4. Update your .env files with: 
    CLICKHOUSE_HOST=your-host.clickhouse.cloud
CLICKHOUSE_PORT=8123
CLICKHOUSE_USER=default
CLICKHOUSE_PASSWORD=your-password
CLICKHOUSE_DATABASE=your-database
CLICKHOUSE_SECURE=true

​
Stripe Setup (Optional)

For billing functionality:
  1. Create a Stripe account
  2. Get your API keys from the dashboard
  3. Update your .env files with: 
    NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_test_...
STRIPE_SECRET_KEY=sk_test_...
STRIPE_WEBHOOK_SECRET=whsec_...

​
Additional Services (Optional)

  • Sentry: Error monitoring 
    SENTRY_DSN=https://your-dsn@sentry.io/project-id
SENTRY_ENVIRONMENT=development
  • PostHog: Analytics 
    NEXT_PUBLIC_POSTHOG_KEY=phc_your-key
NEXT_PUBLIC_POSTHOG_HOST=https://app.posthog.com

​
Development Workflow

The justfile provides convenient commands for development: 
# Setup and installation
just setup              # Complete development setup
just install             # Install all dependencies

# API Development
just api-native          # Run API natively (fastest)
just api-build           # Build API Docker image
just api-run             # Run API in Docker
just api-test            # Run API tests

# Frontend Development  
just fe-run              # Run dashboard development server
just fe-build            # Build dashboard for production
just fe-test             # Run frontend tests

# Code Quality
just lint                # Run all linting checks
just format              # Format all code
just test                # Run all tests

# Docker Management
just up                  # Start all services
just down                # Stop all services
just logs                # View service logs
just clean               # Clean up Docker resources

​
Manual Development

If you prefer running services manually: 
# Start API server
cd api && uv run python run.py

# Start dashboard (in another terminal)
cd dashboard && bun dev

# Start landing page (in another terminal)  
cd landing && bun dev

​
Service Configuration

​
API Server Configuration

Key environment variables for the API server (api/.env): 
# Database connections
SUPABASE_URL=https://your-project.supabase.co
SUPABASE_KEY=your-service-role-key
CLICKHOUSE_HOST=your-clickhouse-host

# Application settings
APP_URL=http://localhost:3000
LOGGING_LEVEL=INFO
JWT_SECRET_KEY=your-jwt-secret

# External integrations
SENTRY_DSN=your-sentry-dsn

​
Dashboard Configuration

Key environment variables for the dashboard (dashboard/.env.local): 
# Supabase
NEXT_PUBLIC_SUPABASE_URL=https://your-project.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=your-anon-key

# Application URLs
NEXT_PUBLIC_APP_URL=http://localhost:8000
NEXT_PUBLIC_SITE_URL=http://localhost:3000

# Features
NEXT_PUBLIC_ENVIRONMENT_TYPE=development
NEXT_PUBLIC_PLAYGROUND=true

​
Troubleshooting

​
Common Issues

Port conflicts: 
# Check what's running on ports 3000 and 8000
lsof -i :3000
lsof -i :8000
Database connection issues:
  • Verify your Supabase and ClickHouse credentials
  • Check network connectivity to external services
  • Ensure database migrations have been applied
Docker issues: 
# Reset Docker environment
just clean
docker system prune -f
just up
Dependency issues: 
# Clean and reinstall
rm -rf node_modules api/.venv dashboard/node_modules
just install

​
Logs and Debugging

# View service logs
just logs

# View specific service logs
docker-compose logs api
docker-compose logs dashboard

# Run with debug logging
LOGGING_LEVEL=DEBUG just api-run

​
Next Steps

Once your backend is running:
  1. Create an account at http://localhost:3000
  2. Generate an API key in the dashboard
  3. Install the AgentOps SDK and start tracking your AI agents
  4. Explore the dashboard to view traces and analytics
For production deployment, see our Deployment Guide.