The open framework for
governed AI development
Install once, get governed AI. The open framework for building AI applications that are governed by design. SDK, OpenAI-compatible gateway, proxy, plugins, CLI, and dashboard, with governance on streamed responses and destination control on agent tool calls. Apache 2.0.
Every interaction governed, bidirectionally
Admina works as both an SDK (in-process) and a transparent proxy (network). Every AI interaction is automatically governed.
Admina Proxy Rust + Python Embed the gateway, verify every record
Run the OpenAI-compatible gateway as one component of a larger system, and check the forensic trail record by record.
A gateway-only proxy
No Redis, ClickHouse or scientific stack. Named upstreams with their own keys, upstream errors propagated, the governance outcome in every response's headers.
pip install "admina[proxy-minimal]" ADMINA_ENABLED_SURFACES=gateway REDIS_URL= CLICKHOUSE_HOST= \ ADMINA_API_KEY_FILE=/run/secrets/admina_api_key \ FORENSIC_BACKEND=filesystem FORENSIC_BASE_DIR=/var/lib/admina/fx \ ADMINA_FORENSIC_STATE_KEY_FILE=/run/secrets/fkey \ uvicorn admina.proxy.main:app --host 0.0.0.0 --port 8080
A forensic trail you can verify
Atomic writes, an HMAC signature on each record, verification from a checkpoint and JSON Lines export.
# the proxy signs each record with the chain-state key; # verify with the same key to check the signatures export FORENSIC_BASE_DIR=/var/lib/admina/fx export ADMINA_FORENSIC_STATE_KEY_FILE=/run/secrets/fkey admina forensic verify admina forensic verify --checkpoint SEQ:HASH admina forensic export --out records.jsonl
Control where tool calls go
A destination allowlist on MCP tool calls, and a detector for agents quietly
coordinating through one destination. Both record without refusing until you
switch them to enforce.
Allowlist destinations, not verbs
Destinations are read from tool-call arguments and checked against your allowlist. The HTTP method is never consulted: it is a claim, not a boundary.
domains:
agent_security:
egress:
allow:
- api.openai.com
- "*.corp.internal"
- 10.0.0.0/8
# observe (default) records only; then
# ADMINA_EGRESS_MODE=enforce is default-deny Catch undeclared coordination
Many agents writing to one undeclared destination raise suspected; a keyed
content echo between them confirms it and quarantines the destination for writes.
# build the allowlist from observed traffic admina egress suggest-allowlist --since 7 # without a key: "suspected" only export ADMINA_EGRESS_FINGERPRINT_KEY=<secret> admina egress quarantine list admina egress quarantine lift wiki.corp
Drop-in gateway, governed streaming
Point an OpenAI-compatible client at the proxy, or stream deltas from the SDK. Both surfaces run the same governance pipeline.
Drop-in for OpenAI-compatible clients
Change base_url and the API key. Admina governs the request, then
forwards it to its configured upstream — by default a local Ollama.
import os from openai import OpenAI client = OpenAI( base_url="http://localhost:8080/v1", # gateway (:3000 in local mode) api_key=os.environ["ADMINA_API_KEY"], ) resp = client.chat.completions.create( model="llama3.1:8b", messages=[{"role": "user", "content": "Summarise this clause"}], )
Governance on streamed responses
Deltas are PII-redacted across chunk boundaries; the outcome lands in
last_stream_result.
import asyncio from admina.plugins.builtin.adapters.ollama import OllamaAdapter from admina.sdk import GovernedModel model = GovernedModel(model_name="llama3.1:8b", adapter=OllamaAdapter()) async def main(): async for delta in model.stream("Summarise this clause"): print(delta, end="", flush=True) print(model.last_stream_result["action"]) # ALLOW | REDACT | BLOCK asyncio.run(main())
Four domains of protection
Applied bidirectionally to every request and response. Configurable. Extensible. Built for production.
Data Sovereignty
PII redaction, data residency enforcement, data classification. Rust-accelerated 0.62µs per scan.
Documentation →AI Infrastructure
LLM engine (Ollama/vLLM), RAG pipeline (ChromaDB), Web UI, hot model switching. Opt-in.
Documentation →Agent Security
Anti-injection firewall (44 patterns across 13 categories with an Italian baseline; 15 patterns at 2.08µs on the Rust engine), loop breaker (TF-IDF cosine similarity, 2.38µs). Bidirectional. Destination allowlist and cross-agent coordination detector on MCP tool calls.
Documentation →Compliance
EU AI Act classification (Art. 6-15), forensic black box (SHA-256 hash chain, optional per-record HMAC signatures, S3-compatible), OpenTelemetry native.
Documentation →Governance in 5 minutes
Install Admina, scaffold a project, and start governing your AI agents with a single command. No configuration needed to get started.
admina init # Install from PyPI pip install "admina[proxy]" admina init my-project cd my-project admina dev # local mode, no Docker required # API + dashboard → http://localhost:3000 # the dashboard asks for the API key: admina password show # Verify curl http://localhost:3000/health # {"status":"healthy","service":"admina-proxy","version":"0.14.2", # "engine":{"active":"python","rust_available":false, ...}, ...}
OISG adequate on the full stack
Admina is built around OISG — Open,
Intelligent, Secure, Governed.
The adequacy score is computed from the live runtime state — not a checklist —
and the full Docker Compose stack reaches the adequate band out of the
box. A bare pip install scores 75, in the Good coverage band.
/api/dashboard/oisg 
Supporting open source AI governance infrastructure. Thank you for making Admina possible.
Admina is Apache 2.0 and always will be. No paid tiers, no feature gating on the core.
Apache 2.0 License →Built in the open, for the community
Star the repo, open an issue, contribute a domain. Every interaction counts. We respond to all issues as soon as possible.