Documentation

Welcome to the Admina documentation. Admina is an open source governance framework (Apache 2.0) for AI agents and LLM systems. It provides governed AI development through an SDK, a transparent MCP proxy, an OpenAI-compatible gateway, plugin system, CLI, and real-time dashboard.

⚡
Quick Start
Governance in 5 minutes. Zero-Docker by default — pip install, admina init, admina dev, then point any OpenAI client at it.
→
🏛️
4 Governance Domains
Data Sovereignty, AI Infrastructure, Agent Security, Compliance.
→
📊
Admina Score
Live-runtime governance composite (0–100). Formula, components, how to improve.
→
🛡️
OISG Adequacy
Open · Intelligent · Secure · Governed — Admina's default paradigm.
→
🔌
Integrations
Framework connectors, seven model adapters, and the OpenAI-compatible gateway.
→
📡
API Reference
JSON-RPC 2.0 proxy API, REST endpoints, and the /v1 gateway with SSE streaming.
→
🌐
Gateway & Streaming
Point any OpenAI-compatible client at Admina. Governed SSE with windowed PII redaction.
→
⚙️
Rust Engine
Build admina_core, benchmarks, Python/Rust hybrid mode.
→
🔧
Configuration
Environment variables, domain tuning, deployment modes.
→

What is Admina?

Admina is an open framework for governed AI development. It works as an SDK (in-process GovernedModel, GovernedData, GovernedAgent, ComplianceKit), a transparent MCP proxy (POST /mcp) and — since v0.11.0 — an OpenAI-compatible HTTP gateway (POST /v1/chat/completions, GET /v1/models) that any OpenAI-compatible client can be pointed at. Every AI interaction is automatically governed: PII redacted, injections blocked, loops broken, actions audited, and EU AI Act compliance tracked.

Streamed responses are governed too: PII spanning delta boundaries is redacted through a windowed recomposition buffer, both in the SDK's GovernedModel.stream() and on the gateway's SSE path.

Since v0.12.0 the governance pipeline can also check destinations against an egress allowlist — mainly tool-call arguments on /mcp; on the gateway, /api/v1/validate and GovernedModel it sees prompt text, where only a string that begins with a URL counts as a destination. Since v0.13.0 agent_security.egress.surfaces chooses the surfaces it runs on. The MCP proxy also flags agents that coordinate through one undeclared destination. Both run in observe by default — recorded, never refused — until ADMINA_EGRESS_MODE=enforce.

Key properties:

  • OISG adequate on the full stack — Open · Intelligent · Secure · Governed, scored automatically from live runtime state (Docker Compose 85; bare pip install 75, Good coverage)
  • Bidirectional — both requests and responses are governed
  • Three governed surfaces — SDK (in-process), MCP proxy, and an OpenAI-compatible gateway, plus /api/v1/validate for REST integrations; since v0.13.0 ADMINA_ENABLED_SURFACES chooses which proxy surfaces are served
  • Embeddable gateway — since v0.13.0 the proxy-minimal extra runs a gateway-only proxy without Redis, ClickHouse or boto3, with named upstream routes and secrets read from files
  • Destination control — egress allowlist aimed at tool calls (surfaces selectable since v0.13.0) and a cross-agent coordination detector on the MCP proxy, observe-first
  • Tamper-evident audit — SHA-256 hash-chained forensic records, each HMAC-signed since v0.13.0 when a chain-state key is set, checked with admina forensic verify
  • Hybrid runtime — Rust core (~6µs median) with automatic Python fallback
  • Plugin system — 9 interfaces, 17 built-in implementations
  • 6 framework integrations — OpenClaw, LangChain, CrewAI, n8n, Cheshire Cat AI, GuardrailsAI
  • EU AI Act compliant — risk classification and gap analysis built in
  • Apache 2.0 — free to use, modify, and distribute forever

Architecture at a glance

Admina has three runtime shapes. The first two cover the same 4 governance domains. The default is zero-Docker: a single uvicorn process that serves the governance proxy, the REST API and the bundled dashboard on one port, :3000. admina dev --stack splits the same surface across Docker Compose containers, which is where the additional ports appear. 

# Default — local mode, no Docker
admina dev

#  proxy + REST API + dashboard → :3000  (single process)

# Full stack — proxy, dashboard, ClickHouse, Redis, OTEL collector, Grafana
admina dev --stack

#  proxy      → :8080  (governance proxy + REST API)
#  dashboard  → :3000  (real-time governance UI)
#  otel       → :4317  (OpenTelemetry collector gRPC)
#  grafana    → :3001  (metrics and traces)

:8080, :3001 and :4317 exist only under --stack. In local mode everything is on :3000 (auto-fallback to the next free port if it is taken). The repository's own docker compose up runs 8 containers: the six above plus a mock MCP server and a mock agent. See Quick Start.

The third shape, new in v0.13.0, embeds only the gateway in a larger system: pip install "admina-framework[proxy-minimal]", then uvicorn admina.proxy.main:app with ADMINA_ENABLED_SURFACES=gateway and REDIS_URL= / CLICKHOUSE_HOST= empty. The mcp and integration surfaces need the proxy (or rust) extra; the proxy does not start when they are enabled without it. See Configuration.