Self-Hosting

AgentLens is open source and designed to be self-hosted. You can deploy it with Docker in minutes, or run from source for development.

Quick start with Docker

terminal

git clone https://gitea.repi.fun/repi/agentlens
cd agentlens
docker build -t agentlens .
docker run -p 3000:3000 \
  -e DATABASE_URL="postgresql://user:pass@host:5432/agentlens" \
  -e AGENTLENS_API_KEY="your-secret-key" \
  agentlens

The dashboard will be available at http://localhost:3000 and the API at http://localhost:3000/api/traces.

Docker Compose

For a complete setup with PostgreSQL included:

docker-compose.yml

version: "3.8"

services:
  db:
    image: postgres:16-alpine
    environment:
      POSTGRES_USER: agentlens
      POSTGRES_PASSWORD: agentlens
      POSTGRES_DB: agentlens
    volumes:
      - pgdata:/var/lib/postgresql/data
    ports:
      - "5432:5432"

  app:
    build: .
    ports:
      - "3000:3000"
    environment:
      DATABASE_URL: "postgresql://agentlens:agentlens@db:5432/agentlens"
      AGENTLENS_API_KEY: "your-secret-key"
      PORT: "3000"
    depends_on:
      - db

volumes:
  pgdata:

terminal

docker compose up -d

Running from source

For development or when you need to customize AgentLens:

terminal

git clone https://gitea.repi.fun/repi/agentlens
cd agentlens

# Install dependencies (uses npm workspaces)
npm install

# Set up the database
cp apps/web/.env.example apps/web/.env
# Edit .env with your DATABASE_URL

# Generate Prisma client and push schema
npm run db:generate --workspace=@agentlens/web
npm run db:push --workspace=@agentlens/web

# Start the development server
npm run dev --workspace=@agentlens/web

Environment variables

Variable	Required	Default	Description
DATABASE_URL	Yes	-	PostgreSQL connection string
AGENTLENS_API_KEY	Yes	-	API key that SDKs must present to ingest traces
PORT	No	3000	HTTP port the server listens on
NODE_ENV	No	production	Set to "development" for dev mode
NEXTAUTH_SECRET	No	-	Secret for session signing (if auth is enabled)

Database setup

AgentLens uses PostgreSQL with Prisma ORM. The database schema is managed via Prisma migrations.

Connection string format

postgresql://USER:PASSWORD@HOST:PORT/DATABASE

Running migrations

terminal

# Push schema to database (development)
npm run db:push --workspace=@agentlens/web

# Run migrations (production)
npm run db:migrate --workspace=@agentlens/web

Reverse proxy setup

For production deployments behind nginx or Caddy:

Caddyfile

agentlens.yourdomain.com {
  reverse_proxy localhost:3000
}

nginx.conf

server {
    listen 443 ssl;
    server_name agentlens.yourdomain.com;

    location / {
        proxy_pass http://localhost:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Updating

terminal

# Pull latest changes
cd agentlens
git pull origin main

# Rebuild
docker build -t agentlens .

# Restart with new image
docker compose up -d

Resource requirements

Component	Minimum	Recommended
CPU	1 core	2+ cores
Memory	512 MB	1 GB+
Disk	1 GB	10 GB+ (depends on trace volume)
PostgreSQL	14+	16+