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
(official SDK, SigV4), the (bucket quota, server info),
the unauthenticated (),
and the (, bearer-token
or public auth) — with a : a unified audit log,
a token/runaway budget guard, undo-token recording, and a descriptive risk
tier on every audit row. Self-contained: no external skill-family dependency.
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 48
tools (29 read, 19 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).
bucket_create (med, undo — the only way to enable object lock), set_default_retention (high, undo), clear_default_retention (med, undo), set_legal_hold (med, undo)
4
write
set_object_retention (critical, dry-run, extend-only, no undo exists)
create_user (med, undo, secret redacted + never returned), set_user_status (med, undo), attach_user_policy (med, undo), detach_user_policy (med, undo) — all refused for this tool's own credential
4
write
remove_user (high, dry-run, no undo: MinIO keeps no recoverable secret)
It delivers MinIO object-storage operations — reads and writes — accurately and
efficiently, and records every one of them. It does not decide whether a
write is allowed to happen. That is the agent's judgement, or the permission of
the access key you connect it with: give the key a read-only IAM policy and the
writes fail at the server — the place that actually owns the permission.
So there is no read-only switch, no policy file, no approval gate to configure.
The one thing the tool guarantees is that nothing is silent: every call, over
MCP and over the CLI alike, lands an audit row in ~/.minio-aiops/audit.db,
and reversible writes still capture their real prior state and record an inverse
undo descriptor.
Each tool declares a risk_level, kept in agreement with its [READ]/[WRITE]
documentation tag by a test, and carried into the audit row as a descriptive
tier — so a reviewer can see at a glance that a row was a high-risk delete. It
is a label, not a gate.
Running a smaller / local model? See
agent-guardrails.md — it lists
the guardrails this tool 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
As a Claude Code plugin
One install gives an agent both the skill and the MCP server:
The MCP server is fetched with uv and pinned to the
package version this plugin declares, so an audit row can be traced back to the
code that wrote it. Credentials are still configured with minio-aiops init — see below.
As an OpenClaw plugin
The same bundle is published on ClawHub, where one
install delivers the skill and its MCP server together:
openclaw plugins install clawhub:@zw008/minio-aiops
openclaw skills info minio-aiops # expect: Visible to model: yes
Restart the OpenClaw gateway afterwards so it loads the plugin. The MCP server is
fetched with uv, pinned to this exact release, so
uvx has to be on PATH — without it the skill still installs but reports
Visible to model: no. Credentials are configured exactly as below.
As a CLI or standalone MCP server
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
Where that password then lives: an exported variable is readable by
every process this shell starts and is recorded by shell history. On a
shared or long-lived host, prefer the interactive prompt, or inject it from
a secret manager for the life of the one command that needs it.
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.
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, and any
MINIO_AUDIT_APPROVED_BY / MINIO_AUDIT_RATIONALE annotations) is logged to
~/.minio-aiops/audit.db (relocatable via MINIO_AIOPS_HOME).
Budget / runaway guard — token and call budgets trip a circuit breaker.
A safety backstop, not authorization.
Risk-tier labelling — each tool's declared risk_level is recorded on the
audit row as a descriptive tier (bucket_delete is high). It is a label for
the reviewer, not a gate: there is no read-only switch, policy file, or
approval gate, and MINIO_AUDIT_APPROVED_BY / MINIO_AUDIT_RATIONALE are
optional annotations recorded when set, never required.
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), and
the governance loop (real set_versioning → undo restoring it to Suspended, the
correct S3 inverse). 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, IAM policy authoring (creating and editing policy
documents — attachment is supported), group membership writes, tiering to remote
storage — not here yet. Open an issue or send a PR — feedback and
contributions are welcome.