Configuration

All Admina settings are configured via environment variables or a .env file in the project root. Copy .env.example to get started:

cp .env.example .env
# Then edit .env with your values

Authentication

Set ADMINA_API_KEY to protect all governance endpoints in production. The /health endpoint and /docs (OpenAPI) are always public.

# Generate a strong key
openssl rand -hex 32

# Add to .env
ADMINA_API_KEY=your-generated-key-here

Include the key in all requests:

# Via header
curl http://localhost:8080/api/stats \
  -H "X-API-Key: $ADMINA_API_KEY"

# Via Bearer token
curl http://localhost:8080/api/stats \
  -H "Authorization: Bearer $ADMINA_API_KEY"

If ADMINA_API_KEY is not set, authentication is disabled. This is acceptable for local development; a warning is logged at startup.

All variables

Proxy & Upstream

VariableDefaultDescription

UPSTREAM_MCP_URL http://localhost:9000 Default upstream MCP server URL

CORS_ORIGINS http://localhost:3000 Comma-separated allowed CORS origins

LOG_LEVEL INFO Logging verbosity: DEBUG, INFO, WARNING, ERROR

ROUTING_CONFIG_PATH — Path to multi-upstream routing config (OpenClaw mode)

Authentication

ADMINA_API_KEY — API key for all endpoints. If empty, auth is disabled (dev only)

Storage — Redis

REDIS_URL redis://localhost:6379/0 Redis connection URL — session state, rate limiting, hash chain

Storage — MinIO (Forensic Black Box)

MINIO_ENDPOINT localhost:9000 MinIO or S3-compatible endpoint

MINIO_ACCESS_KEY admina MinIO access key

MINIO_SECRET_KEY admina-secret-key Change in production. MinIO secret key

MINIO_BUCKET forensic-blackbox S3 bucket name for forensic records

MINIO_SECURE false Enable TLS for MinIO. Set true in production

Storage — ClickHouse

CLICKHOUSE_HOST localhost ClickHouse host for analytics

CLICKHOUSE_PORT 8123 ClickHouse HTTP port

CLICKHOUSE_DB admina ClickHouse database name

Telemetry — OpenTelemetry

OTEL_ENDPOINT http://localhost:4317 OTLP gRPC collector endpoint

Rate Limiting

RATE_LIMIT_MAX_REQUESTS 100 Max requests per session per window

RATE_LIMIT_WINDOW_SECONDS 60 Rate limit window in seconds

Governance Thresholds — P1 Loop Breaker

LOOP_WINDOW_SIZE 10 Number of past requests to compare for loop detection

LOOP_SIMILARITY_THRESHOLD 0.85 Cosine similarity threshold (0.0–1.0) to trigger loop detection

Docker Compose environment

When using the included docker-compose.yml, set secrets via the .env file. Required variables that have no safe defaults:

# Required — change before deploying
MINIO_SECRET_KEY=change-me-in-production
GRAFANA_ADMIN_PASSWORD=change-me-in-production

# Recommended for any non-local deployment
ADMINA_API_KEY=$(openssl rand -hex 32)
MINIO_SECURE=true

Production checklist

Set ADMINA_API_KEY to a strong random value
Set MINIO_SECRET_KEY to a strong random value
Set MINIO_SECURE=true if using a remote MinIO/S3
Configure CORS_ORIGINS to your actual frontend domains
Set LOG_LEVEL=WARNING to reduce log volume
Point OTEL_ENDPOINT to your observability platform