Quick Start

Get Admina running in under 5 minutes. The default workflow is zero-Docker — a single uvicorn process serves both the proxy API and the bundled dashboard on :3000 (auto-fallback to the next free port if it is taken). Docker Compose remains available for the full stack with ClickHouse, Grafana and OTEL collector.

Step 1 — Install Admina

# Recommended — proxy + infrastructure deps (what makes `admina dev` work)
pip install "admina-framework[proxy]"

# Broad install — [full] is [proxy,nlp,telemetry] and does not include Presidio;
# the complete roll-up is [all] = [proxy,nlp,telemetry,adapters,presidio] since v0.11.0
pip install "admina-framework[full]"

# Optional: Rust-accelerated engine (opt-in since v0.9.4)
pip install "admina-framework[rust]"

# Optional: Microsoft Presidio as a selectable PII engine (new in v0.11.0 —
# the default engine stays spacy-regex until you set ADMINA_PII_ENGINE=presidio)
pip install "admina-framework[presidio]"

# Advanced — SDK only (embed governance in your own app; no local dev server)
pip install admina-framework

The default install runs the pure-Python governance engines. The Rust accelerator is opt-in via the [rust] extra — it pulls the admina-core wheel from PyPI, and ADMINA_ENGINE=auto (the default) uses it for the firewall + loop breaker while keeping PII on Python for full recall. The two engines are not equivalent — the Python engines carry broader detection coverage, and the gap is measured and tracked by the shipped red-team baseline rather than assumed. See the Rust engine guide.

python -m spacy download en_core_web_sm it_core_news_sm

Step 2 — Initialize a project

admina init my-project
cd my-project
# Scaffolds admina.yaml, docker-compose.yml, .env, and a runnable main.py

Step 3 — Start the proxy + dashboard

admina dev has three execution modes:

# 1. Default — zero-Docker local mode (one uvicorn serves API + dashboard)
admina dev

# 2. Full Compose stack (proxy + dashboard + redis + clickhouse + otel + grafana)
admina dev --stack

# 3. Stack + local AI infra (ollama + chromadb + open-webui)
admina dev --with-llm

# Expose on the LAN instead of localhost:
admina dev --public                # or --host 0.0.0.0

git clone https://github.com/admina-org/admina.git
cd admina
./scripts/bootstrap-secrets.sh   # writes + prints random API key and dashboard password (.env)
docker compose up --build     # startup banner masks the key — re-read it with `cat .env`

Step 4 — Verify governance is active

In local mode everything — API, dashboard and Swagger UI — is on :3000. Under --stack the proxy is a separate container on :8080, so swap the port in the commands below.

# Health check (always public)
curl http://localhost:3000/health
# {
#   "status": "healthy",
#   "service": "admina-proxy",
#   "version": "0.11.1",
#   "engine": {
#     "engine": "python",
#     "rust_available": false,
#     "rust_version": null,
#     "selection": "auto",
#     "active": "python",
#     "pii_active": "python"
#   },
#   "timestamp": "2026-01-01T12:00:00+00:00"
# }

# Check stats (auth required when ADMINA_API_KEY is set)
curl http://localhost:3000/api/stats -H "X-API-Key: $ADMINA_API_KEY"

engine is an object, not a string. With the [rust] extra installed it reports "active": "rust" while "pii_active" stays "python" under the default ADMINA_ENGINE=auto, which keeps full PII recall.

Step 5 — Explore the dashboard

In local mode the dashboard opens without a login — the proxy hands the browser a signed, expiring session cookie so the SPA can call the API. HTTP Basic auth is a --stack feature: the dashboard container puts it in front of nginx when ADMINA_DASHBOARD_PASSWORD is set, using the credentials printed by admina dev or bootstrap-secrets.sh.

Local mode — admina dev

Full stack — admina dev --stack

Step 6 — Send your first governed request

Route your AI agent's MCP calls through Admina instead of directly to the MCP server. In local mode the proxy listens on port 3000 (8080 under --stack). /mcp forwards to UPSTREAM_MCP_URL, which local mode leaves empty — point it at your MCP server before this step, or run admina dev --stack, which wires the bundled mock MCP server for you. /mcp is also authenticated, unlike /health.

# Send a test MCP call through the governance proxy
curl -X POST http://localhost:3000/mcp \
  -H "X-API-Key: $ADMINA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "read_file",
      "arguments": {"path": "/etc/hosts"}
    },
    "id": 1
  }'

# The response includes governance metadata:
# X-Admina-Governance-Action: ALLOW
# X-Admina-Latency-Us: 6.25
# X-Admina-Event-Id: evt_01J...
# X-Admina-Forensic-Hash: a3f8c9...

Step 7 — Point any OpenAI client at Admina

Since v0.11.0 the same proxy port also serves an OpenAI-compatible surface — POST /v1/chat/completions and GET /v1/models — so any client that speaks the OpenAI chat-completions API can be governed without a code change. Point Admina at your model server first — these go in .env or the shell that launches admina dev, since settings are read once at start-up:

# Upstream OpenAI-compatible API Admina forwards to — must include the /v1 base path.
# Default: http://localhost:11434/v1 (a local Ollama)
export ADMINA_GATEWAY_UPSTREAM=http://localhost:11434/v1

# Optional — comma-separated allow-list applied to GET /v1/models (default: empty = passthrough)
export ADMINA_GATEWAY_MODELS_ALLOWLIST=llama3.1:8b

# Optional — text returned to the caller when governance blocks a request
# (default: "This request was blocked by the Admina governance policy.")
export ADMINA_GATEWAY_BLOCK_MESSAGE="Blocked by policy."

Then talk to http://localhost:3000/v1 instead of the upstream (http://localhost:8080/v1 under --stack). The API key is your ADMINA_API_KEY — the proxy accepts it as Authorization: Bearer or X-API-Key, so an OpenAI SDK's api_key parameter works as-is.

curl -X POST http://localhost:3000/v1/chat/completions \
  -H "Authorization: Bearer $ADMINA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "llama3.1:8b",
    "messages": [{"role": "user", "content": "Summarise this clause…"}]
  }'

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:3000/v1",   # Admina, not the provider
    api_key="<your ADMINA_API_KEY>",
)

resp = client.chat.completions.create(
    model="llama3.1:8b",
    messages=[{"role": "user", "content": "Summarise this clause…"}],
)
print(resp.choices[0].message.content)

Streaming works the same way — Admina re-emits the upstream as Server-Sent Events, redacting PII across delta boundaries, and always terminates the stream with data: [DONE]:

for chunk in client.chat.completions.create(
    model="llama3.1:8b",
    messages=[{"role": "user", "content": "Summarise this clause…"}],
    stream=True,
):
    print(chunk.choices[0].delta.content or "", end="")

What just happened?

Every call you made was:

• Scanned for PII in both directions (Data Sovereignty)
• Checked for prompt injection patterns (Agent Security — Firewall)
• Checked for infinite loop signatures (Agent Security — Loop Breaker)
• Added to the SHA-256 hash chain audit log (Compliance — Forensic)
• Classified for EU AI Act risk level (Compliance)
• Recorded as an OpenTelemetry span (Compliance — OTEL) — only with the [telemetry] extra installed and OTEL_ENDPOINT set, which --stack does for you; bare admina dev clears it
• Counted into the Admina Score at /api/dashboard/score — the live runtime composite (residency, audit coverage, EU AI Act coverage, recent attacks, forensic chain)

Two exceptions on the /v1 gateway from Step 7: loop detection does not run on that surface, and a gateway request writes its forensic record without emitting an OpenTelemetry span. Everything else in the list applies.

Next steps

Troubleshooting

First stop: admina doctor

The CLI ships with a diagnostic command that inspects your environment and reports which checks pass or fail — Python version, Rust engine availability, plugin discovery, admina.yaml validity, and infrastructure reachability.

admina doctor

Containers fail to start

Check that all required ports are free. The stack binds 3000, 3001 and 8080 on all interfaces, plus 8123, 4317, 4318, 8888 and 8889 on localhost only. Run docker compose logs proxy for detailed error output.

Rust engine not detected

Admina automatically falls back to the Python implementation if the Rust binary is not available. The health endpoint's engine object will show "rust_available": false and "active": "python". To enable Rust, ensure the admina_core binary is compiled for your platform (see Rust engine guide).

Need help?

Open an issue on GitHub or start a discussion in GitHub Discussions.