AI Security Gateway

Appearance

Environment Variables Configuration ​

This document describes all environment variables that can be used to configure the AI Security Gateway.

There actually shouldnt be much reason to further customise environment variables in the .env file, defaults should work fine but we're listing here for when you want to really fine tune...you know the risks. Most things can be set under the Settings section of the UI (:

Also, side note, some environment variable listed may be removed over time

SQLite Database Configuration ​

DB_PATH ​

  • Description: Database file path
  • Default: ./data/ai-gateway-security.db
  • Example: DB_PATH=/var/lib/ai-gateway/security.db

DB_MAX_OPEN_CONNS ​

  • Description: Maximum number of open database connections
  • Default: 100 (increased from 50 for high-throughput scenarios)
  • Example: DB_MAX_OPEN_CONNS=150
  • Note: Increase for high-concurrency scenarios with multiple proxies and users (2000+ req/s)

DB_MAX_IDLE_CONNS ​

  • Description: Maximum number of idle database connections
  • Default: 20 (increased from 10 for better connection reuse)
  • Example: DB_MAX_IDLE_CONNS=30
  • Note: Higher values improve connection reuse but use more memory

DB_CONN_MAX_LIFETIME ​

  • Description: Maximum lifetime of a database connection in seconds
  • Default: 3600 (1 hour)
  • Example: DB_CONN_MAX_LIFETIME=7200
  • Note: Connections older than this will be closed and recreated

DB_LOG_LEVEL ​

  • Description: Database log level
  • Default: warn
  • Options: silent, error, warn, info
  • Example: DB_LOG_LEVEL=info

DB_RETENTION_DAYS ​

  • Description: Global data retention period in days (legacy setting, kept for backward compatibility)
  • Default: 90
  • Example: DB_RETENTION_DAYS=180
  • Note: This setting is automatically migrated to granular retention policy. For fine-grained control, use the granular retention environment variables below.

Granular Retention Settings ​

The following environment variables allow you to configure retention periods for specific data types. If not set, they default to values derived from DB_RETENTION_DAYS or system defaults.

DB_RETENTION_ALERTS_DAYS ​

  • Description: Security alerts retention period in days
  • Default: 90 (or value from DB_RETENTION_DAYS)
  • Example: DB_RETENTION_ALERTS_DAYS=180
  • Minimum: 7 days
  • Maximum: 3650 days (10 years)
  • Note: Recommended 90+ days for compliance and forensics

DB_RETENTION_AUDIT_LOGS_DAYS ​

  • Description: General audit logs retention (MCP/LLM proxy requests, A2A invocations)
  • Default: 90 (or value from DB_RETENTION_DAYS)
  • Example: DB_RETENTION_AUDIT_LOGS_DAYS=180
  • Minimum: 30 days
  • Maximum: 3650 days (10 years)
  • Note: Recommended 90+ days for compliance

DB_RETENTION_REQUEST_LOGS_DAYS ​

  • Description: HTTP/WebSocket request logs retention period
  • Default: 30 (or DB_RETENTION_DAYS / 3, minimum 7)
  • Example: DB_RETENTION_REQUEST_LOGS_DAYS=60
  • Minimum: 7 days
  • Maximum: 3650 days (10 years)
  • Note: Recommended 30 days for privacy (shorter than audit logs)

DB_RETENTION_TOKEN_USAGE_DAYS ​

  • Description: LLM token usage records retention period
  • Default: 365 (or value from DB_RETENTION_DAYS)
  • Example: DB_RETENTION_TOKEN_USAGE_DAYS=730
  • Minimum: 30 days
  • Maximum: 3650 days (10 years)
  • Note: Recommended 365 days for annual cost tracking

DB_RETENTION_HEALTH_METRICS_DAYS ​

  • Description: System health metrics retention period
  • Default: 30 days
  • Example: DB_RETENTION_HEALTH_METRICS_DAYS=60
  • Minimum: 7 days
  • Maximum: 3650 days (10 years)
  • Note: Recommended 30 days for operational monitoring

DB_RETENTION_MCP_TOOL_LOGS_DAYS ​

  • Description: MCP tool invocation logs retention period
  • Default: 90 (or value from DB_RETENTION_DAYS)
  • Example: DB_RETENTION_MCP_TOOL_LOGS_DAYS=180
  • Minimum: 30 days
  • Maximum: 3650 days (10 years)
  • Note: Recommended 90 days (same as audit logs)

DB_RETENTION_LLM_REQUEST_LOGS_DAYS ​

  • Description: LLM request/response logs retention period
  • Default: 90 (or value from DB_RETENTION_DAYS)
  • Example: DB_RETENTION_LLM_REQUEST_LOGS_DAYS=180
  • Minimum: 30 days
  • Maximum: 3650 days (10 years)
  • Note: Recommended 90 days (same as audit logs)

DB_RETENTION_A2A_INVOCATION_LOGS_DAYS ​

  • Description: A2A agent invocation audit logs retention period
  • Default: 90 (or value from DB_RETENTION_DAYS)
  • Example: DB_RETENTION_A2A_INVOCATION_LOGS_DAYS=180
  • Minimum: 30 days
  • Maximum: 3650 days (10 years)
  • Note: Recommended 90 days (same as audit logs)

Important Notes:

  • Granular retention settings override the global DB_RETENTION_DAYS setting
  • If DB_RETENTION_DAYS is set but granular settings are not, the system automatically migrates to granular policy preserving current behavior
  • Token usage records are now automatically cleaned up (previously missing - critical fix)
  • Cleanup runs daily at midnight
  • Changes to retention settings take effect on the next cleanup cycle

DB_MAX_PAYLOAD_SIZE ​

  • Description: Maximum size in bytes for audit log payloads (request/response bodies)
  • Default: 102400 (100KB)
  • Example: DB_MAX_PAYLOAD_SIZE=204800 (200KB)
  • Note:
    • Payloads larger than this limit will be truncated with a ...[truncated] indicator
    • Set to 0 for unlimited (not recommended for high-throughput scenarios)
    • Smaller values improve INSERT performance but may lose audit detail
    • Recommended: 50KB-200KB depending on typical payload sizes

Request Timeout Configuration ​

DB_QUERY_TIMEOUT ​

  • Description: Database query timeout in seconds
  • Default: 10
  • Example: DB_QUERY_TIMEOUT=15
  • Note: Maximum time allowed for a single database query

EXTERNAL_API_TIMEOUT ​

  • Description: External API timeout in seconds
  • Default: 30
  • Example: EXTERNAL_API_TIMEOUT=60
  • Note: Timeout for external API calls (OAuth, MCP, etc.)

POLICY_VALIDATION_TIMEOUT ​

  • Description: Policy validation timeout in seconds
  • Default: 5
  • Example: POLICY_VALIDATION_TIMEOUT=10
  • Note: Timeout for policy compilation and validation

REQUEST_HANDLER_TIMEOUT ​

  • Description: Request handler timeout in seconds
  • Default: 60
  • Example: REQUEST_HANDLER_TIMEOUT=120
  • Note: Maximum time allowed for processing an entire HTTP request

OAuth & Security Configuration ​

ENCRYPTION_KEY ​

  • Description: Encryption key for OAuth tokens and sensitive data
  • Required: Yes (for OAuth functionality)
  • Example: Generate with: openssl rand -hex 32
  • Note: Must be a secure random 32-byte hex string

MCP Tool Scanning Configuration ​

MCP_TOOL_SCAN_MAX_CONCURRENCY ​

  • Description: Maximum number of concurrent MCP tool scans
  • Default: 5
  • Example: MCP_TOOL_SCAN_MAX_CONCURRENCY=10
  • Note: Increase for faster scanning of multiple proxies, but be mindful of resource usage

MCP_TOOL_SCAN_TIMEOUT ​

  • Description: Timeout per proxy scan in seconds
  • Default: 120 (2 minutes)
  • Example: MCP_TOOL_SCAN_TIMEOUT=180
  • Note: Prevents one slow proxy from blocking the entire scan

MCP_TOOL_SCAN_INTERVAL_HOURS ​

  • Description: Interval between scheduled scans in hours
  • Default: 6
  • Example: MCP_TOOL_SCAN_INTERVAL_HOURS=12
  • Note: How often to automatically scan all MCP proxies for tool changes

API Server Configuration ​

PORT ​

  • Description: Port number for the API server
  • Default: 8080
  • Example: PORT=3000
  • Note: The port on which the API server will listen

ENVIRONMENT ​

  • Description: Application environment
  • Default: development
  • Options: development, production, staging
  • Example: ENVIRONMENT=production
  • Note: Affects logging levels and security settings

ALLOWED_ORIGINS ​

  • Description: Comma-separated list of allowed CORS origins
  • Default: http://localhost:8080,http://localhost:3000,http://localhost:5173
  • Example: ALLOWED_ORIGINS=http://localhost:3000,https://example.com
  • Note: Used for CORS configuration. Multiple origins should be comma-separated

Response Cache Configuration ​

CACHE_DASHBOARD_TTL ​

  • Description: Dashboard cache TTL in seconds
  • Default: 60
  • Example: CACHE_DASHBOARD_TTL=120
  • Note: How long dashboard data is cached before refresh

CACHE_POLICY_TTL ​

  • Description: Policy list cache TTL in seconds
  • Default: 300 (5 minutes)
  • Example: CACHE_POLICY_TTL=600
  • Note: How long policy list data is cached

CACHE_PROXY_TTL ​

  • Description: Proxy configuration cache TTL in seconds
  • Default: 300 (5 minutes)
  • Example: CACHE_PROXY_TTL=600
  • Note: How long proxy configuration data is cached

CACHE_ENABLE_ETAG ​

  • Description: Enable ETag support for HTTP caching
  • Default: true
  • Example: CACHE_ENABLE_ETAG=false
  • Note: ETags allow clients to cache responses and check for updates efficiently

HTTP Request Configuration ​

MAX_REQUEST_SIZE_MB ​

  • Description: Maximum request body size in megabytes
  • Default: 10
  • Example: MAX_REQUEST_SIZE_MB=50
  • Note: Prevents DoS attacks from large payloads. Increase for large file uploads.

System Metrics Configuration ​

METRICS_UPDATE_INTERVAL_SECONDS ​

  • Description: Interval for updating system and connection pool metrics in seconds
  • Default: 30
  • Example: METRICS_UPDATE_INTERVAL_SECONDS=60
  • Note: How often to collect system metrics (CPU, memory, goroutines, connection pool stats). Lower values provide more frequent updates but use more CPU.

ENABLE_METRICS ​

  • Description: Enable metrics collection
  • Default: true
  • Example: ENABLE_METRICS=false
  • Note: Disable metrics collection to reduce overhead in resource-constrained environments

HTTP Client Pool Configuration ​

The HTTP client pool manages connection reuse for outbound HTTP requests (MCP tool discovery, SSE connections, etc.). These settings control connection pooling behavior.

HTTP_CLIENT_POOL_MAX_IDLE_CONNS ​

  • Description: Maximum number of idle connections across all hosts
  • Default: 100
  • Example: HTTP_CLIENT_POOL_MAX_IDLE_CONNS=200
  • Note: Increase for high-concurrency scenarios with many outbound HTTP requests

HTTP_CLIENT_POOL_MAX_IDLE_CONNS_PER_HOST ​

  • Description: Maximum number of idle connections per host
  • Default: 10
  • Example: HTTP_CLIENT_POOL_MAX_IDLE_CONNS_PER_HOST=20
  • Note: Higher values improve connection reuse for frequently accessed hosts

HTTP_CLIENT_POOL_MAX_CONNS_PER_HOST ​

  • Description: Maximum number of connections per host (0 = unlimited)
  • Default: 0 (unlimited)
  • Example: HTTP_CLIENT_POOL_MAX_CONNS_PER_HOST=50
  • Note: Set to limit connections per host to prevent overwhelming target servers

HTTP_CLIENT_POOL_IDLE_TIMEOUT ​

  • Description: Maximum time an idle connection will remain idle before closing (in seconds)
  • Default: 90
  • Example: HTTP_CLIENT_POOL_IDLE_TIMEOUT=120
  • Note: Idle connections are closed after this timeout to free resources

HTTP_CLIENT_POOL_DISABLE_KEEP_ALIVES ​

  • Description: Disable HTTP keep-alives (not recommended)
  • Default: false
  • Example: HTTP_CLIENT_POOL_DISABLE_KEEP_ALIVES=true
  • Note: Disabling keep-alives prevents connection reuse and increases overhead

HTTP_CLIENT_POOL_DISABLE_COMPRESSION ​

  • Description: Disable HTTP compression
  • Default: false
  • Example: HTTP_CLIENT_POOL_DISABLE_COMPRESSION=true
  • Note: Disabling compression increases bandwidth usage but may reduce CPU overhead

HTTP_CLIENT_POOL_TLS_HANDSHAKE_TIMEOUT ​

  • Description: Maximum time to wait for TLS handshake (in seconds)
  • Default: 10
  • Example: HTTP_CLIENT_POOL_TLS_HANDSHAKE_TIMEOUT=15
  • Note: Increase for slow networks or servers with slow TLS handshakes

HTTP_CLIENT_POOL_RESPONSE_HEADER_TIMEOUT ​

  • Description: Maximum time to wait for response headers (in seconds)
  • Default: 10
  • Example: HTTP_CLIENT_POOL_RESPONSE_HEADER_TIMEOUT=20
  • Note: Increase for slow servers or high-latency networks

HTTP_CLIENT_POOL_EXPECT_CONTINUE_TIMEOUT ​

  • Description: Maximum time to wait for 100-continue response (in seconds)
  • Default: 1
  • Example: HTTP_CLIENT_POOL_EXPECT_CONTINUE_TIMEOUT=2
  • Note: Used when sending requests with Expect: 100-continue header

HTTP_CLIENT_POOL_DEFAULT_TIMEOUT ​

  • Description: Default timeout for HTTP requests (in seconds)
  • Default: 30
  • Example: HTTP_CLIENT_POOL_DEFAULT_TIMEOUT=60
  • Note: Used when no specific timeout is provided for a request

OpenTelemetry Tracing Configuration ​

The gateway supports distributed tracing using OpenTelemetry for end-to-end visibility into request flows. These settings control tracing behavior and integration with observability backends.

TRACING_ENABLED ​

  • Description: Enable/disable distributed tracing
  • Default: false
  • Example: TRACING_ENABLED=true
  • Note: When enabled, all HTTP requests are automatically traced

TRACING_SERVICE_NAME ​

  • Description: Service name for traces
  • Default: ai-security-gateway
  • Example: TRACING_SERVICE_NAME=ai-gateway-prod
  • Note: Used to identify your service in trace visualization tools

TRACING_ENVIRONMENT ​

  • Description: Environment name (development, staging, production)
  • Default: development
  • Example: TRACING_ENVIRONMENT=production
  • Note: Helps filter traces by environment in observability tools

TRACING_OTLP_ENDPOINT ​

  • Description: OTLP HTTP endpoint for trace export
  • Default: http://localhost:4318
  • Example: TRACING_OTLP_ENDPOINT=http://otel-collector:4318
  • Note: Endpoint must accept OTLP HTTP protocol

TRACING_SAMPLE_RATE ​

  • Description: Sampling rate for traces (0.0 to 1.0)
  • Default: 1.0 (100% sampling)
  • Example: TRACING_SAMPLE_RATE=0.1 (10% sampling)
  • Note: Lower values reduce trace volume but may miss important traces

Langfuse Integration (LLM Observability) ​

Langfuse is an open-source LLM observability platform that provides specialized monitoring and analytics for LLM applications. These settings enable integration with Langfuse for enhanced LLM-specific observability.

⚠️ Configuration Method: Langfuse can be configured via Web UI (recommended) or Environment Variables. The Web UI is the preferred method for most users as it provides immediate feedback and testing capabilities. Environment variables are useful for:

  • Containerized deployments (Docker, Kubernetes)
  • Infrastructure-as-Code (Terraform, Ansible)
  • CI/CD pipelines
  • Initial setup before UI access

Note: Settings configured via the Web UI are persisted and take precedence over environment variables. Both methods are equivalent - choose based on your deployment needs.

LANGFUSE_ENABLED ​

  • Description: Enable Langfuse integration
  • Default: false
  • Example: LANGFUSE_ENABLED=true
  • Note:
    • When enabled, automatically enables tracing and sends traces to Langfuse
    • Alternative: Configure via Web UI (Settings → Integrations → Langfuse) - no restart required

LANGFUSE_OTLP_ENDPOINT ​

  • Description: Langfuse OTLP endpoint URL
  • Default: https://cloud.langfuse.com (when LANGFUSE_ENABLED=true)
  • Example (Cloud): LANGFUSE_OTLP_ENDPOINT=https://cloud.langfuse.com
  • Example (Self-hosted): LANGFUSE_OTLP_ENDPOINT=http://langfuse:4318
  • Note:
    • For Langfuse Cloud, use https://cloud.langfuse.com
    • For self-hosted Langfuse, use your Langfuse server URL with port 4318
    • The gateway automatically appends /api/public/otel/v1/traces for Langfuse endpoints
    • Alternative: Configure via Web UI (Settings → Integrations → Langfuse) - no restart required

LANGFUSE_PUBLIC_KEY ​

  • Description: Langfuse public key (pk-...)
  • Required: Yes (when LANGFUSE_ENABLED=true)
  • Example: LANGFUSE_PUBLIC_KEY=pk-lf-...
  • Note:
    • Get from Langfuse project settings
    • Used for authentication with Langfuse API
    • Keep this key secure but it can be exposed in client-side code
    • Alternative: Configure via Web UI (Settings → Integrations → Langfuse) - no restart required

LANGFUSE_SECRET_KEY ​

  • Description: Langfuse secret key (sk-...)
  • Required: Yes (when LANGFUSE_ENABLED=true)
  • Example: LANGFUSE_SECRET_KEY=sk-lf-...
  • Note:
    • Get from Langfuse project settings
    • Used for authentication with Langfuse API
    • Keep this key secret - never expose in client-side code or logs
    • Alternative: Configure via Web UI (Settings → Integrations → Langfuse) - no restart required

WebSocket Configuration ​

The WebSocket manager handles real-time connections for alert broadcasting and notifications. These settings control connection limits, timeouts, and performance tuning.

WEBSOCKET_MAX_CONNECTIONS ​

  • Description: Maximum number of concurrent WebSocket connections (0 = unlimited)
  • Default: 1000
  • Example: WEBSOCKET_MAX_CONNECTIONS=2000
  • Note: Increase for high-concurrency scenarios with many connected clients

WEBSOCKET_MAX_IDLE_TIME ​

  • Description: Maximum time a connection can be idle before cleanup (in seconds)
  • Default: 600 (10 minutes)
  • Example: WEBSOCKET_MAX_IDLE_TIME=1200
  • Note: Idle connections are automatically cleaned up to free resources

WEBSOCKET_PING_INTERVAL ​

  • Description: Interval for sending ping messages to keep connections alive (in seconds)
  • Default: 30
  • Example: WEBSOCKET_PING_INTERVAL=60
  • Note: Lower values keep connections more active but use more bandwidth

WEBSOCKET_WRITE_TIMEOUT ​

  • Description: Write deadline timeout for WebSocket messages (in seconds)
  • Default: 10
  • Example: WEBSOCKET_WRITE_TIMEOUT=20
  • Note: Increase for slow networks or large message payloads

WEBSOCKET_READ_TIMEOUT ​

  • Description: Read deadline timeout for WebSocket connections (in seconds)
  • Default: 60
  • Example: WEBSOCKET_READ_TIMEOUT=120
  • Note: Increase for clients that may have long periods between messages

WEBSOCKET_WRITE_BUFFER_SIZE ​

  • Description: Write buffer size in bytes
  • Default: 8192 (8KB)
  • Example: WEBSOCKET_WRITE_BUFFER_SIZE=16384
  • Note: Larger buffers improve throughput but use more memory per connection

WEBSOCKET_ENABLE_COMPRESSION ​

  • Description: Enable WebSocket compression (permessage-deflate)
  • Default: true
  • Example: WEBSOCKET_ENABLE_COMPRESSION=false
  • Note: Compression reduces bandwidth but increases CPU usage

WEBSOCKET_RATE_LIMIT_PER_CONN ​

  • Description: Maximum messages per second per connection (0 = unlimited)
  • Default: 100
  • Example: WEBSOCKET_RATE_LIMIT_PER_CONN=200
  • Note: Prevents individual connections from overwhelming the server

WEBSOCKET_RATE_LIMIT_WINDOW ​

  • Description: Rate limit window duration (in seconds)
  • Default: 1
  • Example: WEBSOCKET_RATE_LIMIT_WINDOW=2
  • Note: Time window for rate limiting calculations

WEBSOCKET_CLEANUP_INTERVAL ​

  • Description: Interval for cleanup goroutine to remove inactive connections (in seconds)
  • Default: 300 (5 minutes)
  • Example: WEBSOCKET_CLEANUP_INTERVAL=600
  • Note: How often to check for and remove idle connections

Memory Pool Configuration ​

The memory pool manages object reuse for frequently allocated objects (buffers, maps, slices) to reduce garbage collection pressure and improve performance.

MEMORY_POOL_INITIAL_BUFFER_SIZE ​

  • Description: Initial buffer size for buffer pool in bytes
  • Default: 4096 (4KB)
  • Example: MEMORY_POOL_INITIAL_BUFFER_SIZE=8192
  • Note: Larger initial sizes reduce reallocations but use more memory per buffer

MEMORY_POOL_MAX_BUFFER_SIZE ​

  • Description: Maximum buffer size before discarding (in bytes)
  • Default: 102400 (100KB)
  • Example: MEMORY_POOL_MAX_BUFFER_SIZE=204800
  • Note: Buffers larger than this are discarded to prevent memory bloat

MEMORY_POOL_INITIAL_SLICE_CAPACITY ​

  • Description: Initial slice capacity for slice pool in bytes
  • Default: 4096 (4KB)
  • Example: MEMORY_POOL_INITIAL_SLICE_CAPACITY=8192
  • Note: Larger initial capacities reduce reallocations but use more memory per slice

MEMORY_POOL_MAX_SLICE_CAPACITY ​

  • Description: Maximum slice capacity before discarding (in bytes)
  • Default: 102400 (100KB)
  • Example: MEMORY_POOL_MAX_SLICE_CAPACITY=204800
  • Note: Slices larger than this are discarded to prevent memory bloat

Garbage Collection (GC) Configuration ​

The garbage collection tuner monitors GC performance and can adaptively adjust GOGC based on pause times.

GOGC ​

  • Description: Go garbage collection target percentage (controls heap growth)
  • Default: 100 (Go runtime default)
  • Example: GOGC=150
  • Note:
    • Lower values (50-100): More frequent GCs, lower memory usage, potentially higher CPU
    • Higher values (150-300): Less frequent GCs, higher memory usage, potentially lower CPU
    • Range: 1-1000 (values outside this range are clamped)

GC_METRICS_UPDATE_INTERVAL ​

  • Description: Interval for updating GC metrics (in seconds)
  • Default: 5
  • Example: GC_METRICS_UPDATE_INTERVAL=10
  • Note: How often GC metrics are collected and updated

GC_ENABLE_ADAPTIVE_TUNING ​

  • Description: Enable adaptive GC tuning based on pause times
  • Default: false
  • Example: GC_ENABLE_ADAPTIVE_TUNING=true
  • Note: When enabled, GOGC is automatically adjusted to maintain target pause times

GC_TARGET_PAUSE_MS ​

  • Description: Target GC pause time in milliseconds (for adaptive tuning)
  • Default: 10
  • Example: GC_TARGET_PAUSE_MS=20
  • Note: Adaptive tuning will adjust GOGC to maintain this target pause time

GC_MIN_GOGC ​

  • Description: Minimum GOGC value for adaptive tuning
  • Default: 50
  • Example: GC_MIN_GOGC=25
  • Note: Prevents GOGC from going too low (which would cause excessive GCs)

GC_MAX_GOGC ​

  • Description: Maximum GOGC value for adaptive tuning
  • Default: 500
  • Example: GC_MAX_GOGC=1000
  • Note: Prevents GOGC from going too high (which would cause excessive memory usage)

Example .env File ​

Create a .env file in the project root with the following structure:

bash
# Server Configuration
PORT=8080
ENVIRONMENT=production
ALLOWED_ORIGINS=http://localhost:3000,https://example.com

# Database Configuration
DB_PATH=./data/ai-gateway-security.db
DB_MAX_OPEN_CONNS=100
DB_MAX_IDLE_CONNS=20
DB_CONN_MAX_LIFETIME=3600
DB_LOG_LEVEL=warn
DB_RETENTION_DAYS=90
DB_MAX_PAYLOAD_SIZE=102400

# Timeout Configuration
DB_QUERY_TIMEOUT=10
EXTERNAL_API_TIMEOUT=30
POLICY_VALIDATION_TIMEOUT=5
REQUEST_HANDLER_TIMEOUT=60

# OAuth & Security
ENCRYPTION_KEY=your-encryption-key-here

# Cache Configuration
CACHE_DASHBOARD_TTL=60
CACHE_POLICY_TTL=300
CACHE_PROXY_TTL=300
CACHE_ENABLE_ETAG=true

# Request Configuration
MAX_REQUEST_SIZE_MB=10

# MCP Tool Scanning
MCP_TOOL_SCAN_MAX_CONCURRENCY=5
MCP_TOOL_SCAN_TIMEOUT=120
MCP_TOOL_SCAN_INTERVAL_HOURS=6

# Metrics Configuration
METRICS_UPDATE_INTERVAL_SECONDS=30
ENABLE_METRICS=true

# Tracing Configuration (OpenTelemetry)
TRACING_ENABLED=false
TRACING_SERVICE_NAME=ai-security-gateway
TRACING_ENVIRONMENT=development
TRACING_OTLP_ENDPOINT=http://localhost:4318
TRACING_SAMPLE_RATE=1.0

# Langfuse Integration (LLM Observability)
LANGFUSE_ENABLED=false
LANGFUSE_OTLP_ENDPOINT=https://cloud.langfuse.com
LANGFUSE_PUBLIC_KEY=
LANGFUSE_SECRET_KEY=

# HTTP Client Pool Configuration
HTTP_CLIENT_POOL_MAX_IDLE_CONNS=100
HTTP_CLIENT_POOL_MAX_IDLE_CONNS_PER_HOST=10
HTTP_CLIENT_POOL_MAX_CONNS_PER_HOST=0
HTTP_CLIENT_POOL_IDLE_TIMEOUT=90
HTTP_CLIENT_POOL_DISABLE_KEEP_ALIVES=false
HTTP_CLIENT_POOL_DISABLE_COMPRESSION=false
HTTP_CLIENT_POOL_TLS_HANDSHAKE_TIMEOUT=10
HTTP_CLIENT_POOL_RESPONSE_HEADER_TIMEOUT=10
HTTP_CLIENT_POOL_EXPECT_CONTINUE_TIMEOUT=1
HTTP_CLIENT_POOL_DEFAULT_TIMEOUT=30

# WebSocket Configuration
WEBSOCKET_MAX_CONNECTIONS=1000
WEBSOCKET_MAX_IDLE_TIME=600
WEBSOCKET_PING_INTERVAL=30
WEBSOCKET_WRITE_TIMEOUT=10
WEBSOCKET_READ_TIMEOUT=60
WEBSOCKET_WRITE_BUFFER_SIZE=8192
WEBSOCKET_ENABLE_COMPRESSION=true
WEBSOCKET_RATE_LIMIT_PER_CONN=100
WEBSOCKET_RATE_LIMIT_WINDOW=1
WEBSOCKET_CLEANUP_INTERVAL=300

# Memory Pool Configuration
MEMORY_POOL_INITIAL_BUFFER_SIZE=4096
MEMORY_POOL_MAX_BUFFER_SIZE=102400
MEMORY_POOL_INITIAL_SLICE_CAPACITY=4096
MEMORY_POOL_MAX_SLICE_CAPACITY=102400

# Garbage Collection Configuration
GOGC=100
GC_METRICS_UPDATE_INTERVAL=5
GC_ENABLE_ADAPTIVE_TUNING=false
GC_TARGET_PAUSE_MS=10
GC_MIN_GOGC=50
GC_MAX_GOGC=500

Performance Tuning Recommendations ​

High-Concurrency Scenarios ​

For deployments with many concurrent users and proxies:

  • Increase DB_MAX_OPEN_CONNS to 100-200 (default is now 100)
  • Increase DB_MAX_IDLE_CONNS to 20-50 (default is now 20)
  • Increase DB_QUERY_TIMEOUT to 15-30 seconds
  • Set DB_MAX_PAYLOAD_SIZE to 50KB-100KB for better INSERT performance with large audit logs

Low-Resource Environments ​

For resource-constrained deployments:

  • Decrease DB_MAX_OPEN_CONNS to 25-30
  • Decrease DB_MAX_IDLE_CONNS to 5-10
  • Keep default timeout values

Production Recommendations ​

  • Always set ENCRYPTION_KEY to a secure random value
  • Use DB_LOG_LEVEL=warn or error in production
  • Monitor connection pool utilization and adjust accordingly
  • Set appropriate retention periods based on compliance requirements
  • For deployments with many MCP proxies, increase MCP_TOOL_SCAN_MAX_CONCURRENCY to 10-20
  • Adjust MCP_TOOL_SCAN_TIMEOUT based on typical proxy response times
  • For high-traffic deployments, increase HTTP_CLIENT_POOL_MAX_IDLE_CONNS to 200-500
  • Monitor HTTP client pool metrics via /api/v1/metrics endpoint
  • For deployments with many WebSocket clients, increase WEBSOCKET_MAX_CONNECTIONS to 2000-5000
  • Monitor WebSocket metrics via /api/v1/metrics endpoint (includes active connections, messages sent/failed, latency)
  • Adjust WEBSOCKET_PING_INTERVAL based on network conditions (lower for unstable networks)
  • For high-throughput scenarios, increase MEMORY_POOL_INITIAL_BUFFER_SIZE to 8192-16384 to reduce reallocations
  • Monitor memory pool hit rates via /api/v1/metrics endpoint (higher hit rates indicate better memory reuse)
  • For low-latency applications, set GOGC=50-100 to reduce GC pause times (at the cost of more frequent GCs)
  • For memory-constrained environments, set GOGC=150-200 to reduce memory usage (at the cost of longer pause times)
  • Enable GC_ENABLE_ADAPTIVE_TUNING=true for automatic GC tuning based on pause times
  • Monitor GC metrics via /api/v1/metrics endpoint (includes pause times, heap usage, GC frequency)