MinIO AIops

Disclaimer: Community-maintained open-source project. Not affiliated with, endorsed by, or sponsored by MinIO, Inc. or any storage vendor. Product and trademark names belong to their owners. MIT licensed.

Governed AI-ops for MinIO object storage — for the homelab and small/medium self-hosted deployments where MinIO actually lives. Talks to the S3 API (official minio SDK, SigV4), the admin API (bucket quota, server info), the unauthenticated health endpoints (/minio/health/live|ready|cluster), and the cluster metrics endpoint (/minio/v2/metrics/cluster, bearer-token or public auth) — with a built-in governance harness: unified audit log, policy engine, token/runaway budget guard, undo-token recording, and graduated-autonomy risk tiers. Self-contained: no external skill-family dependency.

What it does

Four flagship analyses, plus the guarded reads and writes around them:

• capacity_rca — capacity vs used, offline drives/nodes, per-drive hotspots and imbalance → each finding as cause + suggested action (nearfull/full thresholds are named constants, not magic).
• bucket_exposure_audit — every bucket scored and ranked for anonymous/public policy statements (read and, far worse, write), missing default encryption, versioning off, no lifecycle.
• lifecycle_gap_analysis — the storage ILM should be reclaiming but isn't: versioned buckets with no noncurrent expiry (old bytes accrue forever), incomplete multipart uploads with no abort rule (invisible space), large buckets with no lifecycle — with a clearly-labelled reclaimable estimate.
• healing_health — heal backlog and per-erasure-set write-quorum risk: how many more drive failures each set can tolerate, which sets are healing, where heal errors are piling up.
• Governed writes. Bucket policy / versioning / lifecycle / quota changes capture the real prior state and record an undo descriptor; bucket_delete is refused unless the bucket is verifiably empty (including versions and delete markers) and remove_incomplete_uploads only touches uploads older than a safety window.

What works

• CLI (minio-aiops ...): init, overview, doctor, health check/status, capacity rca/usage, heal status/drives/nodes, bucket ls/info/objects/audit/ilm-gap/uploads plus guarded writes (bucket versioning-set/policy-set/lifecycle-set/quota-set/purge-uploads/delete), secret set/list/rm/migrate/rotate-password, mcp. Destructive commands take --dry-run and double-confirm.
• MCP server (minio-aiops mcp or minio-aiops-mcp): the full 31 tools (22 read, 9 write), every one wrapped with the bundled @governed_tool harness. The CLI is a convenience subset; the MCP surface is the whole tool. CLI writes delegate to the same governed functions, so they are audited identically.
• Encrypted credentials: the secret key lives in an encrypted store ~/.minio-aiops/secrets.enc (Fernet + scrypt) — never plaintext on disk. Unlock with a master password from MINIO_AIOPS_MASTER_PASSWORD (MCP/CI) or an interactive prompt (CLI).
• Metrics auth, both modes: servers running MINIO_PROMETHEUS_AUTH_TYPE=public are scraped directly; for the default (jwt) mode the bearer token is derived from the stored credentials — no extra secret to manage.
• Reversibility: reversible writes capture prior state and record an inverse undo descriptor (prior policy JSON, prior lifecycle XML, prior versioning state, prior quota).

Capability matrix (31 MCP tools)

Totals: 31 tools — 22 read (incl. undo_list), 9 write (incl. undo_apply).

Security: read-only mode

This tool is meant to be handed to an AI agent, so its safety story is enforced by the server rather than requested in a prompt:

export MINIO_READ_ONLY=1

With that set, the 9 write tools are never registered. An MCP client lists 22 tools instead of 31 — the writes are not hidden, not gated behind a flag, and not merely refused when called. They are absent from the session. A model cannot invoke a tool it was never offered, and cannot be argued into one.

That distinction is the whole point. A tool that exists but refuses still invites retry loops and "I'll describe the call instead" behaviour from smaller models, and it leaves a reviewer trusting a promise. An absent tool is a fact you can check: connect, list the tools, and see that the writes are not there.

Enforcement is two layers deep, so the switch cannot be sidestepped by changing entry point:

Read operations are unaffected, and every call is still audited to ~/.minio-aiops/audit.db.

The read/write split is derived from each tool's declared risk_level, and a test asserts that this never disagrees with the [READ]/[WRITE] tag in the tool's own documentation — so a write can't quietly present itself as a read.

Running a smaller / local model? See agent-guardrails.md — it lists the guardrails this tool now enforces for you (so you don't spend prompt budget restating them) and gives a ready-made system prompt for what's left.

Quick start

uv tool install minio-aiops         # or: pipx install minio-aiops
minio-aiops init                    # wizard: endpoint + access key; secret key stored encrypted
minio-aiops doctor                  # live/ready + S3 auth + metrics reachability
minio-aiops overview                # health + capacity headline + exposure headline
minio-aiops capacity rca            # why is storage filling up, and what to do
minio-aiops bucket audit            # ranked bucket-exposure findings

Run as an MCP server (stdio):

export MINIO_AIOPS_MASTER_PASSWORD=...   # unlock secrets non-interactively
minio-aiops-mcp

MCP client config

{
  "mcpServers": {
    "minio-aiops": {
      "command": "uvx",
      "args": ["--from", "minio-aiops", "minio-aiops-mcp"],
      "env": { "MINIO_AIOPS_MASTER_PASSWORD": "your-master-password" }
    }
  }
}

Env-block caveat: MCP clients launch the server without a TTY and without your shell profile, so the master password cannot be prompted for and an export in ~/.zshrc is not seen — it must be passed in the client's env block (or the client process's environment) as above. Everything else (targets, TLS, region, metrics mode) comes from ~/.minio-aiops/config.yaml written by minio-aiops init.

Configuration

~/.minio-aiops/config.yaml (non-secret connection details only):

targets:
  - name: lab1
    host: 192.0.2.10
    port: 9000
    access_key: minio-ops        # identifies the account; NOT the secret
    secure: true                 # https (false for plain-http labs)
    verify_ssl: true             # false for self-signed lab certs
    region: ""                   # optional
    metrics_public: false        # true when MINIO_PROMETHEUS_AUTH_TYPE=public

The secret key is stored with minio-aiops secret set lab1 (encrypted; a legacy MINIO_LAB1_SECRET_KEY env var is honoured as a fallback with a migration warning).

Governance

Every MCP tool passes through the bundled @governed_tool harness:

• Audit — every call (params, result, status, duration, risk tier, approver, rationale) is logged to ~/.minio-aiops/audit.db (relocatable via MINIO_AIOPS_HOME).
• Budget / runaway guard — token and call budgets trip a circuit breaker.
• Risk tiers, secure by default — with no rules.yaml, high-risk ops (bucket_delete) require a named approver (MINIO_AUDIT_APPROVED_BY / MINIO_AUDIT_RATIONALE); init seeds an explicit, editable starter policy.
• Undo recording — reversible writes record an inverse descriptor built from the captured prior state.

Supported scope & limitations

• Deployments: any reasonably current MinIO server (single-node or distributed/erasure-coded) reachable over its S3 port. Admin features (quota, server_info) need admin-capable keys. Generic S3 services are not a target: the health/metrics/admin surfaces used here are MinIO-specific.
• Metrics: the capacity/healing RCAs read the v2 cluster metrics endpoint; both public and bearer-token (default) auth modes are supported.
• Incomplete-upload listing uses the SDK's core ListMultipartUploads call (the public alias was removed from the SDK); it is exercised in tests and documented in connection.py.
• Verification status. Live-verified against a real single-node MinIO server (2026-07-19): connectivity, the reads, the exposure audit (it correctly scored an anonymously-writable bucket high and named PUBLIC_WRITE_POLICY), the governance loop (real set_versioning → undo restoring it to Suspended, the correct S3 inverse), and read-only mode. Distributed / multi-node MinIO is still unverified — healing was never exercised against a real degraded drive or erasure set — as are lifecycle/quota writes and TLS endpoints. See docs/VERIFICATION.md; minio-aiops doctor is the fastest live check.

Missing a capability?

Site replication status, object locking / legal-hold governance, per-user / policy (IAM) management, tiering to remote storage — not here yet. Open an issue or send a PR — feedback and contributions are welcome.