Configuration

All Admina settings are configured via admina.yaml or environment variables. A few settings accept both forms — the PII engine, for instance, is the top-level pii_engine: key in admina.yaml (a sibling of forensic_store: and auth_provider:, not nested under domains) or the ADMINA_PII_ENGINE environment variable; where both are set, the environment wins. Others, such as ADMINA_GUARD_FAIL_MODE, the egress mode and most gateway limits, are environment-variable-only, and the firewall's pattern rules are admina.yaml-only. Secrets are auto-generated on first launch and stored in an encrypted vault (.admina/secrets.json). The defaults are tuned so that the full Docker Compose stack lands in the OISG adequate band out of the box, and a bare pip install lands at 75, in the Good coverage band; 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

Where admina.yaml comes from

Without ADMINA_CONFIG, the library loader looks for admina.yaml in the current working directory, then in the installed package root, and falls back to environment variables / .env when neither exists. Since v0.13.0, ADMINA_CONFIG=/etc/admina/admina.yaml names the file instead: the proxy, the SDK, the firewall overrides, the egress policy and the PII engine selection then read exactly that file, and a missing, unreadable or invalid file is a ConfigFileError — the proxy does not start, there is no fallback to the defaults. The CLI is stricter than the library — admina dev reads admina.yaml from the current directory only and exits if it is missing. To write one somewhere else, use admina configure -o /path/to/admina.yaml (the --output flag defaults to ./admina.yaml).

Schema check (since v0.13.0). The file is checked against its schema (schema_version: 1). A value of the wrong type — a string where a list is expected, say — is a ConfigSchemaError naming the key (admina.yaml ./admina.yaml: domains.agent_security.loop_breaker.window_size: must be an integer; for a file named by ADMINA_CONFIG it surfaces as a ConfigFileError carrying the same message) and the proxy does not start; the engine factories the SDK uses raise the same error. An empty value (key: with nothing after it) is not checked, nor are the free-form blocks (plugin_config, integrations, agent_security.domains, the entries of custom_patterns). An unknown key, typically a typo, is logged as a warning at startup (unknown keys, not read: …). The proxy also warns about ADMINA_* variables in its environment or .env that nothing reads (names only, never values).

Authentication

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

• ADMINA_API_KEY — protects every governance endpoint. The only exempt paths are /health, /metrics, the OpenAPI docs (/docs, /redoc, /openapi.json) and the bundled dashboard shell (/, /heimdall.png, /vendor/*), which holds no credential. Since v0.13.0, ADMINA_METRICS_REQUIRE_AUTH=true and ADMINA_API_DOCS_REQUIRE_AUTH=true put /metrics and the docs behind the key too; otherwise /metrics serves Prometheus counters unauthenticated, so keep it off the public internet.
• ADMINA_DASHBOARD_PASSWORD — the HTTP Basic Auth password (user admin) of the Docker Compose dashboard container. bootstrap-secrets.sh and the CLI vault write the same value to CLICKHOUSE_PASSWORD and GRAFANA_ADMIN_PASSWORD, so one password opens every UI of the stack. The proxy itself does not read it.

Dashboard sign-in (since v0.12.1). The dashboard the proxy serves itself (at / on the proxy's port — 3000 under admina dev, 8080 in Docker) asks for the API key once and exchanges it at POST /api/dashboard/session for a signed, HttpOnly, SameSite=Strict session cookie scoped to /api/. The session is accepted only for read-only requests to the dashboard API (/api/dashboard/*, /api/stats, the live feed); /mcp, the gateway and the integration and compliance APIs always need the key. Rotating the API key invalidates every session. The built-in apikey auth provider reads X-API-Key / Authorization: Bearer only, never cookies.

Both credentials 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"

The key in the query string (?api_key=) is accepted only on the dashboard live-feed WebSocket, where browsers cannot set headers, and is deprecated since v0.13.0: the first use logs a warning, and a later release will refuse it.

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

Secrets from files

Since v0.13.0 each of these secrets can be given directly or as <NAME>_FILE, the path of a file holding it (a Docker or Kubernetes secret): ADMINA_API_KEY, ADMINA_FORENSIC_STATE_KEY, ADMINA_AUDIT_APPEND_KEY, ADMINA_GATEWAY_UPSTREAM_API_KEY and the per-route ADMINA_GATEWAY_UPSTREAM_<NAME>_API_KEY. The file is read once at startup with one trailing newline removed. A missing, unreadable, non-UTF-8 or empty file, or a secret set both directly and as a file, stops the proxy with an error that names the setting and the path, never the secret. ADMINA_FORENSIC_STATE_KEY_FILE inside the forensic directory is refused (SecretFileError): keep the key outside the store it signs.

All variables

The proxy reads its own settings from the process environment and from .env. A handful of variables are read from the process environment only — a .env line takes effect for them only where something exports it, as Docker Compose's env_file does: ADMINA_CONFIG, ADMINA_ENGINE, ADMINA_OFFLINE, ADMINA_PII_ENGINE, ADMINA_PII_MASK_STYLE, ADMINA_PRESIDIO_NLP_MODELS, ADMINA_PATTERN_PACK_DIRS, ADMINA_FORENSIC_STATE_KEY (and _FILE), ADMINA_EGRESS_MODE, ADMINA_EGRESS_FINGERPRINT_KEY, ADMINA_SPACY_MODEL and ROUTING_CONFIG_PATH.

Routes, the default route, the stream mode and the scan-policy allow-lists can also live in the top-level gateway section of admina.yaml (since v0.13.0). A malformed section — a route without a url, a default_upstream that names no route, an unreadable key file — stops the proxy at startup:

gateway:
  upstreams:
    main:
      url: "http://main.upstream.test/v1"
      api_key_file: /run/secrets/upstream_api_key
    util:
      url: "http://util.upstream.test/v1"
  default_upstream: main      # default: the first route
  stream_mode: passthrough    # ADMINA_GATEWAY_STREAM_MODE wins
  # tags a request may declare as already scanned (X-Admina-Scan-Policy)
  prescan_tags: []
  # rulesets (SHA-256) accepted in that header besides the proxy's own
  prescan_rulesets: []

Response codes, the X-Admina-* response headers, the scan-policy header syntax and the forensic records the gateway writes are documented under API Reference → OpenAI-compatible gateway. The ruleset hash covers the Admina version, so it changes with every upgrade (and its whole form changed in v0.13.0): after each release, recompute any value pinned in prescan_rulesets from GET /v1/admina/ruleset.

Without the key (since v0.13.0). The state file and records are unsigned and an intact chain state is used as it is, but a chain state that is missing while records exist can no longer be rebuilt — the records cannot be verified without the key, so the chain is reported invalid and nothing is recorded until an operator restores or moves the store aside. Records written before a key was set are reported as unsigned. Verification, rebuild and admina forensic verify are described under Governance Domains → Compliance.

Programmatic form. Both classes take the key as the keyword argument state_signing_key: str | None = None. The explicit argument wins; the environment variables (ADMINA_FORENSIC_STATE_KEY, then its _FILE) are only read when the argument is left at None (or empty), so SDK users need no env var at all. ForensicBlackBox also takes fail_mode="open" | "closed" (since v0.13.0):

from admina.domains.compliance.forensic import ForensicBlackBox
from admina.plugins.builtin.forensic.filesystem import FilesystemForensicStore

# key material comes from your own secret manager — never hardcode it
box = ForensicBlackBox(
    filesystem_dir="/var/lib/admina/forensic",
    state_signing_key=signing_key,
)
store = FilesystemForensicStore(
    base_dir="/var/lib/admina/forensic",
    state_signing_key=signing_key,
)

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). The repository's docker-compose.yml and the one admina init generates set FORENSIC_BACKEND=filesystem with FORENSIC_BASE_DIR=/app/.admina/forensic on the named volume forensic-data, so records and chain state outlive the container (since v0.13.0). The admina init admina.yaml leaves the backend lines commented out, and admina dev local mode exports FORENSIC_BACKEND=memory unless you set it — which, being an environment value, overrides the YAML.

There is no environment variable that selects the active domains — each one is toggled individually in admina.yaml under domains.<name>.enabled (data_sovereignty, ai_infra, agent_security, compliance). Three of them ship enabled; ai_infra is opt-in and defaults to false.

Firewall rules in admina.yaml

The injection firewall's rules live under domains.agent_security.firewall; there is no environment-variable form apart from ADMINA_PATTERN_PACK_DIRS (separated by : — os.pathsep), which replaces pattern_pack_dirs when set. Shown with defaults:

domains:
  agent_security:
    firewall:
      enabled: true
      # deep-path score from which a text is flagged (Python engine)
      heuristic_threshold: 0.5
      # tags the deep path does not count as context switches (Python engine)
      allowed_tags: []
      # ── Python-only keys: any non-empty one selects the Python firewall ──
      custom_patterns: []       # entries: regex, category, risk_level
      disabled_categories: []
      disabled_patterns: []     # pattern ids, e.g. instruction_override.en.1
      pattern_packs: []         # names of versioned pattern packs
      # ── pack lookup; these do not select an engine ──
      pattern_pack_dirs: []
      strict_pack_timing: false # true: a pack pattern over 50 ms stops the proxy

disabled_patterns, allowed_tags, pattern_packs, pattern_pack_dirs and strict_pack_timing are new in v0.13.0. A pack that is missing, found twice or invalid stops the proxy (PatternPackError); a malformed custom_patterns entry is skipped with a warning. Under ADMINA_ENGINE=auto, any of the four Python-only keys makes the firewall Python (warning logged); under ADMINA_ENGINE=rust it is an EngineSelectionError. Pattern ids, packs and the categories are documented under Governance Domains → Agent Security.

Both are environment-variable-only and read from the process environment, not from .env (see the note above the tables). Everything else lives under domains.agent_security.egress in admina.yaml, shown here with its defaults (an empty allow list under enforce refuses every destination):

domains:
  agent_security:
    egress:
      # false skips the stage entirely
      enabled: true
      # exact hosts, "*.suffix" wildcards, CIDR ranges
      allow: []
      # tool names exempt from the payload-bearing classification
      read_only_tools: []
      # surfaces the stage runs on: gateway, mcp, integration, sdk
      # (unset: all of them; []: none) — since v0.13.0
      # surfaces: [mcp]
      # shared write destinations: exact lowercase hostnames only
      coordination_declared: []
      fanin:
        window_seconds: 3600   # effective window is 1–2×
        min_agents: 5          # raises "suspected" (floor 2)
      # fleet-wide write quarantine after "confirmed"
      quarantine_ttl_seconds: 86400

Since v0.13.0 a wrong-typed value anywhere in admina.yaml is a ConfigSchemaError that stops the proxy (and raises in the SDK) — it no longer degrades to an empty allowlist — and an unknown name in surfaces stops the proxy too. What each key does, the per-surface coverage and the admina egress commands are documented under Governance Domains → Egress control.

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

# An API key and one password shared by every UI — the two values the
# script prints. Both are written to .env:
ADMINA_API_KEY=<random 32-byte hex>
ADMINA_DASHBOARD_PASSWORD=<random 20-char password>
CLICKHOUSE_PASSWORD=<same value>
GRAFANA_ADMIN_PASSWORD=<same value>
MINIO_SECRET_KEY=<same value>      # unused residue of the removed MinIO backend (v0.9.5)

# .env also gets a separate, unprinted WEBUI_SECRET_KEY (another random
# 32-byte hex), used only by the Open WebUI service that `admina init`
# adds to its compose file when the ai_infra domain is on.

• The proxy listens on 8080 and keeps its forensic records on the named volume forensic-data (FORENSIC_BACKEND=filesystem, FORENSIC_BASE_DIR=/app/.admina/forensic), so they survive docker compose down / up.
• The dashboard container is published on 127.0.0.1:3000 only (Grafana on 3001). With ADMINA_API_KEY set, it refuses to start without ADMINA_DASHBOARD_PASSWORD (HTTP Basic Auth, user admin) and accepts only a key made of letters, digits and . _ ~ + / = - (a hex key is fine). Its nginx adds the key only to the dashboard's read-only routes (/api/dashboard/*, the live feed, /api/stats); /mcp and the other /api/ routes are forwarded with the caller's own key. Without the key, the page signs in with the API key itself. Since v0.13.0.
• The proxy image's entrypoint exits unless ADMINA_API_KEY or ADMINA_API_KEY_FILE is set, and prints only whether a key is set, never any of its characters.

Production checklist

• Run bootstrap-secrets.sh (or let the CLI vault generate them) — never commit .env. In containers, prefer the *_FILE forms for secrets
• Leave ALLOW_UNAUTHENTICATED at its false default
• Pin the configuration: ADMINA_CONFIG=/etc/admina/admina.yaml and ADMINA_CONFIG_STRICT=true, so a missing file, a typo'd key or a stray ADMINA_* variable stops the proxy instead of being ignored
• Serve only what you use with ADMINA_ENABLED_SURFACES; set ADMINA_DASHBOARD_ENABLED=false and ADMINA_API_DOCS_ENABLED=false if nobody needs them
• Set ADMINA_METRICS_REQUIRE_AUTH=true, or keep /metrics reachable only from your monitoring network
• Behind TLS, set DASHBOARD_COOKIE_SECURE=true (or auto) so the dashboard session cookie is never sent over plain HTTP
• Use FORENSIC_BACKEND=s3 with TLS and Object Lock for a tamper-evident production audit trail; set ADMINA_FORENSIC_FAIL_MODE=closed if no request may be served without its record
• Set ADMINA_FORENSIC_STATE_KEY (or _FILE, outside the forensic directory) so the chain state and every record are signed, and back the key up — without it a lost chain state cannot be rebuilt
• After deploying, check GET /health: forensic_writable not false, forensic_chain ok, and engine naming the engines you expect
• On upgrade from 0.12, check heuristic_threshold in your admina.yaml (see above) and recompute any pinned ruleset hash (it changes with every release)
• Decide your guard fail mode deliberately: ADMINA_GUARD_FAIL_MODE=closed makes a guard exception a BLOCK instead of a skipped check
• On the gateway, bound the upstream with ADMINA_GATEWAY_MODELS_ALLOWLIST, the ADMINA_GATEWAY_TIMEOUT_* settings and ADMINA_GATEWAY_PIPELINE_TIMEOUT; leave ADMINA_GATEWAY_SCAN_POLICY_ENABLED off unless every key holder is trusted
• Roll egress control out observe-first: collect destinations with a persistent forensic backend, build the allowlist with admina egress suggest-allowlist, review it, and only then set ADMINA_EGRESS_MODE=enforce
• If agents share write destinations, list them under coordination_declared before enforcing — and remember X-Agent-Id is unauthenticated, so forged ids can arm a coordination quarantine
• Configure CORS_ORIGINS to your actual frontend domains (the proxy warns on wildcard)
• Set LOG_LEVEL=WARNING to reduce log volume, and ADMINA_LOG_FORMAT=json if a log pipeline parses the output
• Point OTEL_ENDPOINT to your observability platform, or set OTEL_ENABLED=false