Configuration

All Admina settings are configured via admina.yaml or environment variables. Secrets are auto-generated on first launch and stored in an encrypted vault (.admina/secrets.json). The defaults are tuned so that a fresh install lands in the OISG adequate band out of the box; turning any capability off immediately lowers the score. There are four supported bootstrap paths: 

# 1. CLI (recommended) — local mode, no Docker
pip install admina-framework
admina init my-project
cd my-project && admina dev

# 2. Generate admina.yaml interactively (or non-interactively for CI)
admina configure                  # interactive wizard
admina configure --non-interactive # scaffolds defaults to ./admina.yaml

# 3. Docker Compose without the CLI
./scripts/bootstrap-secrets.sh   # writes random creds to .env
docker compose up --build

# 4. Manual
cp .env.example .env                # then fill in values

Authentication

Admina ships with dashboard authentication enabled by default. Two credentials drive the platform:

  • ADMINA_API_KEY — protects every governance endpoint. /health and /docs (OpenAPI) remain public.
  • ADMINA_DASHBOARD_PASSWORD — shared login for the bundled Alpine.js dashboard, Grafana, and ClickHouse.

Both can be managed via the CLI:

admina password show      # display current credentials
admina password reset     # regenerate all credentials
admina password set       # set a custom password

Include the API key in every request to a protected endpoint:

# 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"

For local development only, set ALLOW_UNAUTHENTICATED=true to disable auth. A warning is logged at startup. The docker-compose default is false.

Fail-closed since v0.10.0. A proxy started with no ADMINA_API_KEY and no auth providers now rejects protected requests (with a loud startup warning) instead of authenticating every caller as admin. To run without a key you must explicitly set ALLOW_UNAUTHENTICATED=true.

All variables

Proxy & Upstream
VariableDefaultDescription
UPSTREAM_MCP_URL — Default upstream MCP server URL
CORS_ORIGINS http://localhost:3000 Comma-separated allowed CORS origins
LOG_LEVEL INFO Logging verbosity: DEBUG, INFO, WARNING, ERROR
ADMINA_ENGINE auto Governance-engine backend, uniform across proxy / SDK / integrations: auto | python | rust (since v0.10.0; unrecognized value raises). See the Rust engine guide.
ROUTING_CONFIG_PATH — Path to multi-upstream routing config (OpenClaw mode)
Authentication
ADMINA_API_KEY — API key for all endpoints. Auto-generated by the vault or bootstrap-secrets.sh
ADMINA_DASHBOARD_PASSWORD — Shared password for dashboard, Grafana, and ClickHouse UIs
ALLOW_UNAUTHENTICATED false Set true only for local development — bypasses the API key check
Storage — Redis
REDIS_URL redis://localhost:6379/0 Redis connection URL — session state, rate limiting, hash chain
Forensic Black Box — backend selection
FORENSIC_BACKEND memory One of memory | filesystem | s3
FORENSIC_BASE_DIR — Required when FORENSIC_BACKEND=filesystem (explicit opt-in, no default)
FORENSIC_S3_ENDPOINT — S3 endpoint URL when FORENSIC_BACKEND=s3 — boto3-based, S3-compatible (leave empty for AWS S3). Standard AWS_* credentials are honoured if the FORENSIC_S3_* equivalents are empty.
FORENSIC_S3_BUCKET forensic-blackbox Bucket that holds the forensic hash chain
FORENSIC_S3_LOCK false Enable S3 Object Lock (WORM COMPLIANCE mode); retention set by FORENSIC_S3_LOCK_DAYS (default 7 years)

Choose your forensic backend deliberately. The hash chain that makes Admina's audit trail tamper-evident depends on persistent storage. The no-config fallback is memory (records lost on restart); since v0.9.5 the admina init templates and the dev docker-compose.yml scaffold with filesystem instead:

Backend comparison
BackendLicenseWhen to use
memory default Local dev, tests, demos. Records LOST on restart (loud warning at startup).
filesystem — Single-host on-prem / air-gapped. Persistence depends on the host filesystem; not ideal for HA. Requires FORENSIC_BASE_DIR.
s3 Apache 2.0 (boto3) Recommended for production. Works against any S3-compatible service — AWS S3, Cloudflare R2, Backblaze B2, SeaweedFS (Apache 2.0), Garage (AGPLv3, as a backend), MinIO, Ceph RGW. Object Lock supported.
Using MinIO? Since v0.9.5 the dedicated MinIO backend has been removed — the archived MinIO Python SDK is no longer a dependency. MinIO servers remain fully supported through the s3 backend: point FORENSIC_S3_ENDPOINT at your MinIO server (boto3 speaks the S3 API). One thing to keep in mind that is not an Admina obligation but MinIO's own: MinIO Server is AGPLv3 — deploying it as part of a network-accessible service can be read to require publishing the source code of the combined application (the commercial license removes this obligation but is paid). If you want a fully permissive stack, SeaweedFS (Apache 2.0, lightweight, single-binary S3 gateway) is a FOSS-friendly drop-in. FORENSIC_BACKEND=minio still works for now — it routes to the s3 backend with a migration warning.
Storage — ClickHouse
CLICKHOUSE_HOST localhost ClickHouse host for analytics
CLICKHOUSE_PORT 8123 ClickHouse HTTP port
CLICKHOUSE_DB admina ClickHouse database name
CLICKHOUSE_PASSWORD — ClickHouse password. Change in production.
Telemetry — OpenTelemetry
OTEL_ENDPOINT http://localhost:4317 OTLP gRPC collector endpoint
Governance Domains
ADMINA_DOMAINS data_sovereignty,agent_security,compliance Comma-separated active governance domains. Add ai_infra to enable AI Infrastructure
ADMINA_GOVERNANCE_MODE enforce How the firewall reacts to flagged traffic: enforce (default, blocks), observe (never blocks, logs "would have blocked"), dry-run (like observe + tags the response). Use observe for the first 1–2 weeks of a new deployment.
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 — 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
Storage — Grafana
GRAFANA_ADMIN_PASSWORD admin Grafana admin password. Change in production.
CLI
ADMINA_CONFIG_PATH admina.yaml Path to the admina.yaml configuration file

Docker Compose environment

When using the included docker-compose.yml, run ./scripts/bootstrap-secrets.sh to generate all secrets at once. The script writes random values to .env and is idempotent — rerun with --force to regenerate. 

./scripts/bootstrap-secrets.sh
docker compose up --build

# Credentials are printed in the proxy startup banner and stored in .env:
ADMINA_API_KEY=<random 32-byte hex>
ADMINA_DASHBOARD_PASSWORD=<random 20-char>
CLICKHOUSE_PASSWORD=<random>
GRAFANA_ADMIN_PASSWORD=<random>

Production checklist

  • Run bootstrap-secrets.sh (or let the CLI vault generate them) — never commit .env
  • Leave ALLOW_UNAUTHENTICATED at its false default
  • Use FORENSIC_BACKEND=s3 with TLS and Object Lock for a tamper-evident production audit trail
  • Configure CORS_ORIGINS to your actual frontend domains (the proxy warns on wildcard)
  • Set LOG_LEVEL=WARNING to reduce log volume
  • Point OTEL_ENDPOINT to your observability platform