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