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

# Everything (proxy + NLP + telemetry)
pip install "admina-framework[full]"

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

# 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 still carry broader detection coverage; full parity is on the roadmap. See the Rust engine guide.

python -m spacy download en_core_web_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 random API key + dashboard password to .env
docker compose up --build     # credentials printed in the startup banner

Step 4 — Verify governance is active

# Health check (always public)
curl http://localhost:8080/health
# {"status":"healthy","version":"0.10.1","engine":"rust","domains":4}

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

Step 5 — Explore the dashboard

The dashboard is password-protected by default when ADMINA_API_KEY is set. Log in with the credentials from bootstrap-secrets.sh or from your .env.

Step 6 — Send your first governed request

Route your AI agent's MCP calls through Admina instead of directly to the MCP server. The proxy listens on port 8080.

# Send a test MCP call through the governance proxy
curl -X POST http://localhost:8080/mcp \
  -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...

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)
• Counted into the OISG adequacy score — the live runtime measure of Open · Intelligent · Secure · Governed

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. Admina uses 3000, 3001, 4317, and 8080. 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 will show "engine":"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.