{
  "markdown": "<!-- mcp-name: io.github.AIops-tools/truenas-aiops -->\n\n# TrueNAS AIops\n\n> **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.\n\nAI-powered **TrueNAS SCALE** storage operations with a **built-in governance\nharness** — unified audit log, token/runaway budget guard, undo-token\nrecording, and descriptive risk tiers. Speaks **both** TrueNAS APIs: REST v2.0\nand the JSON-RPC/WebSocket API that replaces it in TrueNAS 26.\n\n> **Verification status**: live-verified against a real TrueNAS SCALE 25.04.2.1\n> appliance over both transports, including a full write → audit → undo →\n> verified-restore loop. Coverage is listed endpoint by endpoint — and so are\n> the gaps — in [docs/VERIFICATION.md](docs/VERIFICATION.md). Read it rather\n> than reading \"verified\" as \"everything\".\n\n## Supported TrueNAS versions — and which API you are speaking\n\n`truenas-aiops` speaks **both** TrueNAS APIs and picks the one that will still\nexist:\n\n| TrueNAS version | REST API v2.0 | JSON-RPC over WebSocket | what this tool does |\n|---|---|---|---|\n| ≤ 25.10.0 | supported | — | REST |\n| 25.04 – 25.10.x | deprecated (every call raises an appliance alert) | **already served** at `/api/current` | **WebSocket** (auto) |\n| **26 and newer** | **removed** | required | **WebSocket** |\n\nSet `transport:` per target in `config.yaml`:\n\n```yaml\ntargets:\n  - name: nas1\n    host: nas1.example.com\n    transport: auto        # default — probe /api/current, prefer WebSocket\n    # transport: websocket # pin the API that survives TrueNAS 26\n    # transport: rest      # pin REST while migrating\n```\n\n`auto` probes `/api/current` with a cheap HTTP upgrade (no credential spent). If\nthe appliance offers it, the tool uses it; otherwise it falls back to REST,\nwhich is still correct on 25.10 and older.\n\n**iXsystems documents that upgrading to TrueNAS 26 revokes existing API keys** —\nso expect to mint a new one after the upgrade. *We have not reproduced this\nourselves*; it is reported here from the upstream release notes, not from a\nverified upgrade. Treat it as a caution, not a measurement.\n\n`truenas-aiops doctor` tells you which transport the connection actually used,\nreads the server version, and — on REST — says plainly whether REST is\nsupported, deprecated, or gone. If the version cannot be parsed it reports\n**UNKNOWN**, never a clean bill of health it cannot justify.\n\n\n## What works\n\n- **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`.\n- **MCP server** (`truenas-aiops mcp` or `truenas-aiops-mcp`): **25 tools** (19 read, 6 write), every one wrapped with the bundled `@governed_tool` harness.\n- **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).\n- **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.\n- **Safety**: destructive CLI ops (`snapshot delete`, `service restart`) require double confirmation and support `--dry-run`.\n\n## What this tool does, and does not, decide\n\nIt delivers TrueNAS SCALE storage operations — reads and writes — accurately and\nefficiently, and records every one of them. It does **not** decide whether a\nwrite is allowed to happen. That is the agent's judgement, or the permission of\nthe account you connect it with: scope the TrueNAS API key to a limited-privilege\naccount and the writes fail at the appliance — the place that actually owns the\npermission.\n\nSo there is no read-only switch, no policy file, no approval gate to configure.\nThe one thing the tool guarantees is that nothing is silent: **every call, over\nMCP and over the CLI alike, lands an audit row** in `~/.truenas-aiops/audit.db`,\nand reversible writes still capture their before-state and record an inverse.\n\n> Each tool declares a `risk_level`, kept in agreement with its `[READ]`/`[WRITE]`\n> documentation tag by a test, and carried into the audit row as a descriptive\n> tier — so a reviewer can see at a glance that a row was a high-risk delete. It\n> is a label, not a gate.\n\nRunning a smaller / local model? See\n[agent-guardrails.md](skills/truenas-aiops/references/agent-guardrails.md) — it lists\nthe guardrails this tool now enforces for you (so you don't spend prompt budget\nrestating them) and gives a ready-made system prompt for what's left.\n\n## Playbook: triage a degraded pool\n\n```bash\ntruenas-aiops diagnose pool-health            # worst-first: bad state, error counters, capacity\n# → e.g. CRITICAL tank \"pool status is DEGRADED\", and \"read=4 checksum=2\" on a vdev\ntruenas-aiops pool status tank                # inspect the topology / scan detail it cited\ntruenas-aiops pool scrub-start tank           # kick an integrity scrub (governed, medium risk)\ntruenas-aiops diagnose alerts                 # cross-check active alerts + any datasets near full\n```\n\nEach finding cites the measured number that tripped it (status string, error\ncounts, used-percent) so you see **why** it was flagged, then points at the exact\nread/write command to act on it.\n\n## Capability matrix (25 MCP tools)\n\n| Category | Tools | Count | R/W |\n|----------|-------|:-----:|:---:|\n| **Overview / System** | `overview`, `system_info` | 2 | read |\n| **Diagnostics / RCA** | `pool_health_rca`, `alert_and_capacity_rca` | 2 | read |\n| **Pools** | `pool_list`, `pool_get`, `pool_status`, `scrub_status`, `pool_capacity` | 5 | read |\n| | `pool_scrub_start` | 1 | write (medium) |\n| **Datasets** | `dataset_list`, `dataset_get` | 2 | read |\n| | `dataset_create` | 1 | write (medium) |\n| **Snapshots** | `snapshot_list` | 1 | read |\n| | `snapshot_create` (medium), `snapshot_delete` (high) | 2 | write |\n| **Disks** | `disk_list`, `smart_test_results` | 2 | read |\n| **Alerts** | `alert_list` | 1 | read |\n| **Services** | `service_list` | 1 | read |\n| | `service_restart` | 1 | write (medium) |\n| **Replication** | `replication_list`, `cloudsync_list` | 2 | read |\n| **Undo (governance)** | `undo_list` | 1 | read |\n| | `undo_apply` | 1 | write (medium) |\n\n## Quick start\n\n### As a Claude Code plugin\n\nOne install gives an agent both the skill and the MCP server:\n\n```\n/plugin marketplace add AIops-tools/marketplace\n/plugin install truenas-aiops@aiops-tools\n```\n\nThe MCP server is fetched with [uv](https://docs.astral.sh/uv/) and pinned to the\npackage version this plugin declares, so an audit row can be traced back to the\ncode that wrote it. Credentials are still configured with `truenas-aiops init` — see below.\n\n### As a CLI or standalone MCP server\n\n```bash\nuv tool install truenas-aiops\ntruenas-aiops init        # interactive wizard: connection details + encrypted API key\ntruenas-aiops doctor      # verify config, encrypted store, connectivity (hits /system/info)\n```\n\n`init` writes `~/.truenas-aiops/config.yaml` (non-secret connection details) and\nstores the API key **encrypted** in `~/.truenas-aiops/secrets.enc`. Example\nconfig it produces:\n\n```yaml\ntargets:\n  - name: nas1\n    host: 10.0.0.30\n    port: 443\n    verify_ssl: false          # self-signed lab certs only\n    api_path: /api/v2.0\n```\n\nCreate the API key in the TrueNAS UI under **Credentials → API Keys**. For\nnon-interactive use (MCP server, CI, cron) export the master password so the\nstore can be unlocked without a prompt:\n\n```bash\nexport TRUENAS_AIOPS_MASTER_PASSWORD='your-master-password'\n```\n\n### Managing secrets\n\n```bash\ntruenas-aiops secret set nas1             # prompts hidden for the API key\ntruenas-aiops secret list                 # names only, values never shown\ntruenas-aiops secret rm nas1\ntruenas-aiops secret rotate-password      # re-encrypt under a new master password\ntruenas-aiops secret migrate              # import a legacy plaintext .env, then deletes it\n```\n\nA legacy plaintext env var `TRUENAS_<TARGET_NAME_UPPER>_APIKEY` is still honoured\nas a fallback with a deprecation warning (migrate with `truenas-aiops secret migrate`).\n\n## 支持范围 / Supported scope\n\nVersions: **TrueNAS SCALE 25.04 and newer over JSON-RPC/WebSocket, and any build\nstill serving REST v2.0 over REST** — the transport is selected automatically.\nSee [Supported TrueNAS versions](#supported-truenas-versions--and-which-api-you-are-speaking).\nNote that iXsystems documents an upgrade to TrueNAS 26 as **revoking existing\nAPI keys** (upstream claim, not reproduced here).\n\nRead: system info, ZFS pools (list/get/status/scrub-status/capacity), datasets\n(list/get), snapshots (list), disks + S.M.A.R.T. results, alerts, services,\nreplication & cloud-sync tasks, one-shot health overview, and read-only\ndiagnostics / RCA (`pool_health_rca`, `alert_and_capacity_rca`). Mutating (governed,\ndry-run + double-confirm where destructive): `pool_scrub_start`,\n`dataset_create`, `snapshot_create`, `snapshot_delete`, `service_restart`.\n\n**缺功能？(Missing something?)** Coverage is intentionally focused. Open an issue or PR at\n[github.com/AIops-tools/TrueNAS-AIops](https://github.com/AIops-tools/TrueNAS-AIops/issues)\n— feature requests, contributions, and comments are all welcome.\n\n## Caveats\n\n- **Live-verified against TrueNAS SCALE 25.04.2.1** over both transports —\n  reads cross-checked against the appliance's own API, and a full\n  write → audit → undo → verified-restore loop. What is and is not covered is\n  listed endpoint by endpoint in [docs/VERIFICATION.md](docs/VERIFICATION.md);\n  read it rather than assuming \"verified\" means everything.\n- **Still unverified**: S.M.A.R.T. against failing media (needs real hardware —\n  virtio exposes no S.M.A.R.T. at all), replication/cloudsync against real\n  targets, and TrueNAS 26's `auth.login_ex` (25.04 exercises only the fallback).\n- **CLI exit codes**: `0` confirmed, `1` failed or refused, `2` outcome\n  undetermined (the operation may still be in flight — poll before retrying).\n- Out of scope by design: anything that destroys bulk data (dataset/pool\n  deletion, replication runs that overwrite) — only `snapshot_delete` removes\n  data, and it is `high` risk + double-confirmed.\n\n## Not for\n\nOther NAS/storage or backup products, hypervisor VM lifecycle, container\nclusters, or network devices — those are out of scope for this tool.\n\n## License\n\nMIT — [github.com/AIops-tools/TrueNAS-AIops](https://github.com/AIops-tools/TrueNAS-AIops)\n",
  "bytes": 10859,
  "sha": "8babf314ad5689870871f397f4897e353bfc043e62ad0ecf044d3b7816a11c3c",
  "repo_slug": "aiops-tools/truenas-aiops",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_aiops_tools_truenas_aiops_9ffb1c88/readme"
}