Quick Start

Get Admina running in under 5 minutes. You'll need Python 3.11+ and Docker installed.

Prerequisites

Python 3.11+ (pinned in .python-version)
Docker 24+ with Docker Compose v2
Git 2.30+
4 GB RAM available (9 containers)
Ports 3000, 3001, 4317, 8080, 9090 free

Step 1 — Install Admina CLI

Admina is not yet published to PyPI. Install from source until the package name is finalised and the first PyPI release ships:

git clone https://github.com/admina-org/admina.git
cd admina
pip install -e .                  # SDK only
# or with optional extras
pip install -e ".[proxy]"           # proxy + infra deps
pip install -e ".[full]"            # everything (proxy + NLP + telemetry)

Step 2 — Initialize a project

admina init my-project
cd my-project
# Scaffolds admina.yaml, docker-compose.yml, and selects governance domains

Step 3 — Start the stack

admina dev
# Starts the full governance stack via Docker Compose with health monitoring
# On first run this takes ~3-5 minutes to pull and build images.

Without the CLI? Docker-only workflow

If you cloned the repo directly and prefer Docker Compose without the Python CLI, bootstrap a .env with random credentials first:

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.9.0","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.

http://localhost:3000 Governance dashboard — Admina Score, OISG adequacy, live event feed, EU AI Act gaps

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

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

http://localhost:9090 MinIO Console — forensic storage browser

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

OISG adequate out of the box

With the default stack running, your OISG score at /api/dashboard/oisg lands in the adequate band (≥ 80). Flipping any capability off in admina.yaml immediately lowers it — the score reflects actual runtime state, not a checklist. See OISG Adequacy for the full paradigm.

Next steps

🏛️

Explore the domains

Learn how to configure each governance domain

🦾

Integrations

Use Admina as an OpenClaw skill or adapter

🔧

Configuration reference

Environment variables, tuning, and deployment modes

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, 8080, and 9090. 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.