> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentops.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Native Development Guide

> Complete guide for running AgentOps backend services natively without Docker

# 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

```bash theme={null}
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

```bash theme={null}
# Install shared tools (linting, formatting)
bun install

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

#### API Dependencies

```bash theme={null}
cd api

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

# Or using pip
pip install -e .

cd ..
```

#### Dashboard Dependencies

```bash theme={null}
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](#external-services-setup) below.

### 4. Start Services

```bash theme={null}
# 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

* **API Health**: [http://localhost:8000/health](http://localhost:8000/health)
* **API Documentation**: [http://localhost:8000/redoc](http://localhost:8000/redoc)
* **Dashboard**: [http://localhost:3000](http://localhost:3000)
* **Landing Page**: [http://localhost:3001](http://localhost:3001)

## External Services Setup

### Supabase Configuration

1. Create a new project at [supabase.com](https://supabase.com)
2. Get your project credentials from Settings → API
3. Set up the database schema:
   ```bash theme={null}
   cd supabase
   npx supabase db push
   ```
4. Update `api/.env` and `dashboard/.env.local`:
   ```env theme={null}
   # 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](https://clickhouse.com/cloud) or self-host
2. Create a database and get connection details
3. Apply the schema:
   ```bash theme={null}
   # Use the schema from clickhouse/schema_dump.sql
   clickhouse-client --host your-host --query "$(cat clickhouse/schema_dump.sql)"
   ```
4. Update `api/.env`:
   ```env theme={null}
   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`:

```env theme={null}
# 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

#### Using Just (Recommended)

```bash theme={null}
just api-native
```

#### Manual Command

```bash theme={null}
cd api
uv run python run.py
```

#### Alternative Methods

```bash theme={null}
# 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

* **Auto-reload** on file changes
* **Interactive API docs** at [http://localhost:8000/docs](http://localhost:8000/docs)
* **ReDoc documentation** at [http://localhost:8000/redoc](http://localhost:8000/redoc)
* **Health check** at [http://localhost:8000/health](http://localhost:8000/health)

## Dashboard Setup

### Environment Configuration

Key variables in `dashboard/.env.local`:

```env theme={null}
# 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

#### Using Just (Recommended)

```bash theme={null}
just fe-run
```

#### Manual Commands

```bash theme={null}
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**:
   ```bash theme={null}
   # 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:
   ```bash theme={null}
   just test
   ```

### Code Quality Workflow

```bash theme={null}
# 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

```bash theme={null}
# 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

```bash theme={null}
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

```bash theme={null}
cd dashboard

# Run all tests
bun test

# Run tests in watch mode
bun test --watch

# Run tests with coverage
bun test --coverage
```

### Integration Testing

```bash theme={null}
# 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**:
   ```bash theme={null}
   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**:
   ```bash theme={null}
   cd dashboard
   NODE_OPTIONS='--inspect' bun dev
   ```
3. **Attach debugger** at chrome://inspect

### Log Debugging

```bash theme={null}
# 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**:
  ```bash theme={null}
  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**:
  ```bash theme={null}
  cd dashboard
  ANALYZE=true bun run build
  ```

## Troubleshooting

### Common Issues

**Python import errors:**

```bash theme={null}
# Reinstall in editable mode
cd api
uv pip install -e .
```

**Node.js module not found:**

```bash theme={null}
# Clear and reinstall
cd dashboard
rm -rf node_modules package-lock.json
bun install
```

**Port already in use:**

```bash theme={null}
# 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:**

```bash theme={null}
# Use uv for faster Python package management
uv pip install -e .
```

**Slow dashboard reload:**

```bash theme={null}
# Use bun instead of npm
cd dashboard
rm -rf node_modules
bun install
```

### Development Environment Reset

```bash theme={null}
# 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`):

```json theme={null}
{
  "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:

```env theme={null}
# 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:

```javascript theme={null}
// 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:

```python theme={null}
# 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](/v2/self-hosting/deployment).