Disclaimer: Community-maintained open-source project. Not affiliated with, endorsed by, or sponsored by iXsystems or the TrueNAS project. "TrueNAS" is a trademark of its owner. MIT licensed.
AI-powered TrueNAS SCALE storage operations with a built-in governance
harness — unified audit log, token/runaway budget guard, undo-token
recording, and descriptive risk tiers. Speaks TrueNAS APIs: REST v2.0
and the JSON-RPC/WebSocket API that replaces it in TrueNAS 26.
Verification status: live-verified against a real TrueNAS SCALE 25.04.2.1
appliance over both transports, including a full write → audit → undo →
verified-restore loop. Coverage is listed endpoint by endpoint — and so are
the gaps — in docs/VERIFICATION.md. Read it rather
than reading "verified" as "everything".
Supported TrueNAS versions — and which API you are speaking
truenas-aiops speaks both TrueNAS APIs and picks the one that will still
exist:
TrueNAS version
REST API v2.0
JSON-RPC over WebSocket
what this tool does
≤ 25.10.0
supported
—
REST
25.04 – 25.10.x
deprecated (every call raises an appliance alert)
already served at /api/current
WebSocket (auto)
26 and newer
removed
required
WebSocket
Set transport: per target in config.yaml:
targets:
- name: nas1
host: nas1.example.com
transport: auto # default — probe /api/current, prefer WebSocket
# transport: websocket # pin the API that survives TrueNAS 26
# transport: rest # pin REST while migrating
auto probes /api/current with a cheap HTTP upgrade (no credential spent). If
the appliance offers it, the tool uses it; otherwise it falls back to REST,
which is still correct on 25.10 and older.
iXsystems documents that upgrading to TrueNAS 26 revokes existing API keys —
so expect to mint a new one after the upgrade. We have not reproduced this
ourselves; it is reported here from the upstream release notes, not from a
verified upgrade. Treat it as a caution, not a measurement.
truenas-aiops doctor tells you which transport the connection actually used,
reads the server version, and — on REST — says plainly whether REST is
supported, deprecated, or gone. If the version cannot be parsed it reports
UNKNOWN, never a clean bill of health it cannot justify.
What works
CLI (truenas-aiops ...): init, overview, system, pool list/get/status/scrub-status/capacity/scrub-start, dataset list/get/create, diagnose pool-health/alerts, snapshot list/create/delete, disk list/smart, alert list, service list/restart, replication list/cloudsync, secret set/list/rm/migrate/rotate-password, doctor, mcp.
MCP server (truenas-aiops mcp or truenas-aiops-mcp): 25 tools (19 read, 6 write), every one wrapped with the bundled @governed_tool harness.
Encrypted credentials: the TrueNAS API key lives in an encrypted store ~/.truenas-aiops/secrets.enc (Fernet + scrypt) — never plaintext on disk. Unlock with a master password from TRUENAS_AIOPS_MASTER_PASSWORD (MCP/CI) or an interactive prompt (CLI).
Reversibility: snapshot_create records an inverse snapshot_delete undo descriptor. The irreversible snapshot_delete (high risk) captures the snapshot's BEFORE state for the audit record and declares no undo.
Safety: destructive CLI ops (snapshot delete, service restart) require double confirmation and support --dry-run.
What this tool does, and does not, decide
It delivers TrueNAS SCALE 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 account you connect it with: scope the TrueNAS API key to a limited-privilege
account and the writes fail at the appliance — 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 ~/.truenas-aiops/audit.db,
and reversible writes still capture their before-state and record an inverse.
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 now enforces for you (so you don't spend prompt budget
restating them) and gives a ready-made system prompt for what's left.
Playbook: triage a degraded pool
truenas-aiops diagnose pool-health # worst-first: bad state, error counters, capacity
# → e.g. CRITICAL tank "pool status is DEGRADED", and "read=4 checksum=2" on a vdev
truenas-aiops pool status tank # inspect the topology / scan detail it cited
truenas-aiops pool scrub-start tank # kick an integrity scrub (governed, medium risk)
truenas-aiops diagnose alerts # cross-check active alerts + any datasets near full
Each finding cites the measured number that tripped it (status string, error
counts, used-percent) so you see why it was flagged, then points at the exact
read/write command to act on it.
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 truenas-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/truenas-aiops
openclaw skills info truenas-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.
init writes ~/.truenas-aiops/config.yaml (non-secret connection details) and
stores the API key encrypted in ~/.truenas-aiops/secrets.enc. Example
config it produces:
Create the API key in the TrueNAS UI under Credentials → API Keys. For
non-interactive use (MCP server, CI, cron) export the master password so the
store can be unlocked without a prompt:
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.
Managing secrets
truenas-aiops secret set nas1 # prompts hidden for the API key
truenas-aiops secret list # names only, values never shown
truenas-aiops secret rm nas1
truenas-aiops secret rotate-password # re-encrypt under a new master password
truenas-aiops secret migrate # import a legacy plaintext .env, then deletes it
A legacy plaintext env var TRUENAS_<TARGET_NAME_UPPER>_APIKEY is still honoured
as a fallback with a deprecation warning (migrate with truenas-aiops secret migrate).
支持范围 / Supported scope
Versions: TrueNAS SCALE 25.04 and newer over JSON-RPC/WebSocket, and any build
still serving REST v2.0 over REST — the transport is selected automatically.
See Supported TrueNAS versions.
Note that iXsystems documents an upgrade to TrueNAS 26 as revoking existing
API keys (upstream claim, not reproduced here).
缺功能?(Missing something?) Coverage is intentionally focused. Open an issue or PR at
github.com/AIops-tools/TrueNAS-AIops
— feature requests, contributions, and comments are all welcome.
Caveats
Live-verified against TrueNAS SCALE 25.04.2.1 over both transports —
reads cross-checked against the appliance's own API, and a full
write → audit → undo → verified-restore loop. What is and is not covered is
listed endpoint by endpoint in docs/VERIFICATION.md;
read it rather than assuming "verified" means everything.
Still unverified: S.M.A.R.T. against failing media (needs real hardware —
virtio exposes no S.M.A.R.T. at all), replication/cloudsync against real
targets, and TrueNAS 26's auth.login_ex (25.04 exercises only the fallback).
CLI exit codes: 0 confirmed, 1 failed or refused, 2 outcome
undetermined (the operation may still be in flight — poll before retrying).
Out of scope by design: anything that destroys bulk data (dataset/pool
deletion, replication runs that overwrite) — only snapshot_delete removes
data, and it is high risk + double-confirmed.
Not for
Other NAS/storage or backup products, hypervisor VM lifecycle, container
clusters, or network devices — those are out of scope for this tool.