Deployment

Run AgentLens in production.

Docker

Build and run the backend with Docker:

# Build
docker build -t agentlens-backend ./backend

# Run
docker run -d \
  --name agentlens \
  -p 3000:3000 \
  -v agentlens-data:/app/agentlens.db \
  agentlens-backend

💡 Persistent data

Mount a volume for /app/agentlens.db to persist the SQLite database across container restarts.

Environment Variables

Variable	Default	Description
`PORT`	`3000`	HTTP server port

Reverse Proxy (nginx)

Put AgentLens behind nginx for TLS and load balancing:

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

    ssl_certificate     /etc/ssl/certs/agentlens.crt;
    ssl_certificate_key /etc/ssl/private/agentlens.key;

    location / {
        proxy_pass http://127.0.0.1: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;
    }
}

Process Manager (PM2)

Use PM2 for auto-restart and log management:

# Install PM2
npm install -g pm2

# Start AgentLens
cd backend
pm2 start server.js --name agentlens

# Auto-start on boot
pm2 startup
pm2 save

# View logs
pm2 logs agentlens

systemd

Create a systemd service for Linux:

# /etc/systemd/system/agentlens.service
[Unit]
Description=AgentLens Backend
After=network.target

[Service]
Type=simple
User=agentlens
WorkingDirectory=/opt/agentlens/backend
ExecStart=/usr/bin/node server.js
Restart=on-failure
RestartSec=5
Environment=PORT=3000

[Install]
WantedBy=multi-user.target

sudo systemctl enable agentlens
sudo systemctl start agentlens

Security Considerations

⚠️ Production hardening

API authentication: The current backend doesn't enforce API key validation. For production, add middleware to verify the X-API-Key header.
CORS: The backend currently allows all origins. Restrict to your domain in production.
HTTPS: Always use TLS in production (via reverse proxy).
Request size: The backend accepts up to 10MB JSON bodies. Consider reducing this for public-facing deployments.

Monitoring

The /health endpoint returns a JSON status that you can use for health checks:

# Health check
curl http://localhost:3000/health
# {"status":"ok","timestamp":"2026-02-14T10:30:00.000Z"}

# Use with Docker health check
HEALTHCHECK --interval=30s --timeout=5s \
  CMD curl -f http://localhost:3000/health || exit 1

Scaling Considerations

AgentLens uses SQLite, which is a single-writer database. For most use cases (hundreds of concurrent agents, thousands of events per second), this is more than sufficient.

If you need horizontal scaling:

Run multiple backend instances with separate SQLite databases
Route agents to specific instances (agent affinity)
Or consider migrating to PostgreSQL for multi-writer support (contribution welcome!)