Quick Start

Get Admina running in under 5 minutes. You'll need Docker and Git installed. No additional dependencies required.

Prerequisites

Docker 24+ with Docker Compose v2
Git 2.30+
4 GB RAM available (9 containers)
Ports 3000, 3001, 4317, 8080, 9000 free

Step 1 — Clone the repository

git clone https://github.com/admina-org/admina.git
cd admina

Step 2 — Start the stack

A single command launches the full governance stack: proxy, dashboard, ClickHouse, MinIO, Redis, OpenTelemetry collector, Grafana, mock server, and mock agent.

docker compose up --build

# On first run this takes ~3-5 minutes to pull and build images.
# Subsequent starts take ~30 seconds.

Step 3 — Verify governance is active

# Health check
curl http://localhost:8080/health
# {"status":"healthy","version":"0.2.0","engine":"rust","pillars":6}

# Check all pillars are active
curl http://localhost:8080/governance/status
# Returns status of all 6 governance pillars

Step 4 — Explore the dashboard

Open your browser and navigate to the services:

http://localhost:3000 Governance dashboard — live events, pillar status, KPIs

http://localhost:8080/docs Interactive API documentation (Swagger UI)

http://localhost:3001 Grafana — OTEL metrics and traces

http://localhost:9000 MinIO — forensic black box storage

Step 5 — 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-decision: ALLOW
# x-admina-latency: 14µs
# x-admina-pillars: loop_breaker,firewall,pii,otel,forensic,eu_ai_act

What just happened?

Every call you made was:

Checked for prompt injection patterns (P2 Firewall)
Scanned for infinite loop signatures (P1 Loop Breaker)
Filtered for PII in both directions (P3 PII Redaction)
Recorded as an OpenTelemetry span (P4 OTEL)
Added to the SHA-256 hash chain audit log (P5 Forensic)
Classified for EU AI Act risk level (P6 Compliance)

Next steps

🏛️

Explore the pillars

Learn how to configure each governance pillar

🦾

OpenClaw integration

Use Admina as an OpenClaw skill or adapter

🔧

Configuration reference

Environment variables, tuning, and deployment modes

Troubleshooting

Containers fail to start

Check that all required ports are free. Admina uses 3000, 3001, 4317, 8080, and 9000. 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).

Need help?

Open an issue on GitHub or start a discussion in GitHub Discussions. We respond within 4 hours.