import type { Metadata } from "next"; import { CodeBlock } from "@/components/code-block"; export const metadata: Metadata = { title: "Self-Hosting", description: "Deploy AgentLens with Docker or from source. Configure database, API keys, and environment variables.", }; export default function SelfHostingPage() { return (

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. Self-hosted instances do not require registration with the AgentLens cloud service and are not subject to any session limits or billing tiers.

Quick start with Docker

{`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:

{`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:`} {`docker compose up -d`}

Running from source

For development or when you need to customize AgentLens:

{`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

{`# 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:

{`agentlens.yourdomain.com { reverse_proxy localhost:3000 }`} {`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

{`# 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+
); }