Native Development Guide

This guide covers how to run AgentOps backend services natively on your local machine without Docker. Native development provides the fastest iteration cycles and is ideal for active development work.

Overview

Running natively means:
  • Faster startup times - No container overhead
  • Direct file system access - Immediate code changes
  • Native debugging - Use your preferred IDE debugger
  • Resource efficiency - Lower memory and CPU usage

Prerequisites

System Requirements

  • Python 3.12+ with pip or uv
  • Node.js 18+ with npm, yarn, or bun
  • Git for version control
  • Just (optional) for convenience commands

External Services

You’ll need these external services configured:
  • Supabase - Database and authentication
  • ClickHouse - Analytics database
  • Stripe (optional) - Payment processing

Quick Start

1. Clone and Setup

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

# Copy environment files
cp .env.example .env
cp api/.env.example api/.env
cp dashboard/.env.example dashboard/.env.local

2. Install Dependencies

Root Dependencies

# Install shared tools (linting, formatting)
bun install

# Install Python development tools
uv pip install -r requirements-dev.txt

API Dependencies

cd api

# Using uv (recommended)
uv pip install -e .

# Or using pip
pip install -e .

cd ..

Dashboard Dependencies

cd dashboard

# Using bun (recommended)
bun install

# Or using npm
npm install

cd ..

3. Configure Environment Variables

Update your environment files with your service credentials. See External Services Setup below.

4. Start Services

# Terminal 1: API Server
cd api && uv run python run.py

# Terminal 2: Dashboard (in a new terminal)
cd dashboard && bun dev

# Terminal 3: Landing Page (optional, in a new terminal)
cd landing && bun dev

5. Verify Setup

External Services Setup

Supabase Configuration

  1. Create a new project at supabase.com
  2. Get your project credentials from Settings → API
  3. Set up the database schema:
    cd supabase
    npx supabase db push
    
  4. Update api/.env and dashboard/.env.local:
    # API environment
    SUPABASE_URL=https://your-project-id.supabase.co
    SUPABASE_KEY=your-service-role-key
    
    # Dashboard environment
    NEXT_PUBLIC_SUPABASE_URL=https://your-project-id.supabase.co
    NEXT_PUBLIC_SUPABASE_ANON_KEY=your-anon-key
    

ClickHouse Configuration

  1. Sign up for ClickHouse Cloud or self-host
  2. Create a database and get connection details
  3. Apply the schema:
    # Use the schema from clickhouse/schema_dump.sql
    clickhouse-client --host your-host --query "$(cat clickhouse/schema_dump.sql)"
    
  4. Update api/.env:
    CLICKHOUSE_HOST=your-host.clickhouse.cloud
    CLICKHOUSE_PORT=8123
    CLICKHOUSE_USER=default
    CLICKHOUSE_PASSWORD=your-password
    CLICKHOUSE_DATABASE=your-database
    CLICKHOUSE_SECURE=true
    

API Server Setup

Environment Configuration

Key variables in api/.env:
# Database Connections
SUPABASE_URL=https://your-project.supabase.co
SUPABASE_KEY=your-service-role-key
CLICKHOUSE_HOST=your-clickhouse-host
CLICKHOUSE_PASSWORD=your-password

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

# Optional Integrations
SENTRY_DSN=your-sentry-dsn
SENTRY_ENVIRONMENT=development

Running the API Server

just api-native

Manual Command

cd api
uv run python run.py

Alternative Methods

# Using pip and python directly
cd api
pip install -e .
python run.py

# Using uvicorn directly
cd api
uvicorn agentops.main:app --host 0.0.0.0 --port 8000 --reload

API Development Features

Dashboard Setup

Environment Configuration

Key variables in dashboard/.env.local:
# Supabase Configuration
NEXT_PUBLIC_SUPABASE_URL=https://your-project.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=your-anon-key
SUPABASE_SERVICE_ROLE_KEY=your-service-role-key

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

# Feature Flags
NEXT_PUBLIC_ENVIRONMENT_TYPE=development
NEXT_PUBLIC_PLAYGROUND=true

# Optional Services
NEXT_PUBLIC_POSTHOG_KEY=your-posthog-key
NEXT_PUBLIC_SENTRY_DSN=your-sentry-dsn

Running the Dashboard

just fe-run

Manual Commands

cd dashboard

# Using bun
bun install
bun dev

# Using npm
npm install
npm run dev

# Using yarn
yarn install
yarn dev

Dashboard Development Features

  • Hot reload on file changes
  • Fast Refresh for React components
  • Development tools integration
  • Source maps for debugging

Development Workflow

Daily Development Routine

  1. Start services:
    # Terminal 1
    just api-native
    
    # Terminal 2
    just fe-run
    
  2. Make changes to your code
  3. Test changes - services auto-reload
  4. Run tests before committing:
    just test
    

Code Quality Workflow

# Format code
just format

# Run linting
just lint

# Run tests
just test

# All-in-one quality check
just format && just lint && just test

Database Development

# Apply Supabase migrations
cd supabase
npx supabase db push

# Reset database (development only)
npx supabase db reset

# Generate TypeScript types
npx supabase gen types typescript --local > types/database.types.ts

Testing

API Testing

cd api

# Run all tests
pytest

# Run with coverage
pytest --cov=agentops

# Run specific test file
pytest tests/test_auth.py

# Run with verbose output
pytest -v

Dashboard Testing

cd dashboard

# Run all tests
bun test

# Run tests in watch mode
bun test --watch

# Run tests with coverage
bun test --coverage

Integration Testing

# Run full test suite
just test

# Test API and dashboard separately
just api-test
just fe-test

Debugging

API Debugging

  1. Set breakpoints in your IDE
  2. Run with debugger:
    cd api
    python -m debugpy --listen 5678 --wait-for-client run.py
    
  3. Attach your IDE debugger to port 5678

Dashboard Debugging

  1. Use browser dev tools (F12)
  2. Next.js debugging:
    cd dashboard
    NODE_OPTIONS='--inspect' bun dev
    
  3. Attach debugger at chrome://inspect

Log Debugging

# API logs with debug level
cd api
LOGGING_LEVEL=DEBUG uv run python run.py

# Dashboard logs
cd dashboard
DEBUG=* bun dev

Performance Optimization

API Performance

  • Use native Python for fastest development
  • Enable hot reload with uvicorn
  • Profile with py-spy:
    pip install py-spy
    py-spy top --pid $(pgrep -f "python run.py")
    

Dashboard Performance

  • Use bun for faster package management
  • Enable Fast Refresh (enabled by default)
  • Analyze bundle size:
    cd dashboard
    ANALYZE=true bun run build
    

Troubleshooting

Common Issues

Python import errors:
# Reinstall in editable mode
cd api
uv pip install -e .
Node.js module not found:
# Clear and reinstall
cd dashboard
rm -rf node_modules package-lock.json
bun install
Port already in use:
# Find and kill process
lsof -i :8000  # API port
lsof -i :3000  # Dashboard port
kill -9 <PID>
Database connection issues:
  • Verify credentials in .env files
  • Check network connectivity
  • Ensure external services are running

Performance Issues

Slow API startup:
# Use uv for faster Python package management
uv pip install -e .
Slow dashboard reload:
# Use bun instead of npm
cd dashboard
rm -rf node_modules
bun install

Development Environment Reset

# Clean everything and start fresh
rm -rf api/.venv dashboard/node_modules node_modules
just setup

IDE Configuration

VS Code

Recommended extensions:
  • Python
  • Pylance
  • ES7+ React/Redux/React-Native snippets
  • Tailwind CSS IntelliSense
  • Prettier - Code formatter
Settings (.vscode/settings.json):
{
  "python.defaultInterpreterPath": "./api/.venv/bin/python",
  "python.linting.enabled": true,
  "python.linting.ruffEnabled": true,
  "editor.formatOnSave": true,
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": true
  }
}

PyCharm

  1. Set Python interpreter to ./api/.venv/bin/python
  2. Enable Ruff for Python linting
  3. Configure Node.js interpreter for dashboard
  4. Set up run configurations for API and dashboard

Advanced Configuration

Custom Environment Variables

Add custom variables to your .env files:
# Custom API settings
CUSTOM_FEATURE_FLAG=true
DEBUG_SQL_QUERIES=false

# Custom dashboard settings
NEXT_PUBLIC_CUSTOM_FEATURE=enabled

Development Proxy

Set up a proxy for API calls in development:
// dashboard/next.config.js
module.exports = {
  async rewrites() {
    return [
      {
        source: '/api/:path*',
        destination: 'http://localhost:8000/:path*',
      },
    ]
  },
}

Hot Reload Configuration

Fine-tune hot reload behavior:
# api/run.py
if __name__ == "__main__":
    import uvicorn
    uvicorn.run(
        "agentops.main:app",
        host="0.0.0.0",
        port=8000,
        reload=True,
        reload_dirs=["agentops"],  # Only watch specific directories
        reload_excludes=["*.pyc", "*.log"],  # Exclude certain files
    )

Next Steps

Once your native development environment is running:
  1. Explore the codebase - Start with api/agentops/main.py and dashboard/pages/index.tsx
  2. Make your first changes - Try modifying a simple component or API endpoint
  3. Set up testing - Write tests for your changes
  4. Configure your IDE - Set up debugging and linting
  5. Join the community - Connect with other developers
For production deployment, see our Deployment Guide.