TrueNAS Scale Claude SKILL

A Claude skill for driving TrueNAS SCALE over its JSON-RPC 2.0 / WebSocket API.

⚠️ Use a Readonly Admin. Seriously.

This skill hands an LLM a live API key to your NAS. If you give it a Full Admin key, a single bad call — yours, the model's, or a prompt-injected one from a file it just read — can:

• Destroy data: delete datasets, snapshots, pools, or replication targets. ZFS doesn't have an undo button.
• Lock you out: disable your user, rotate root, change network/DNS so the NAS is unreachable.
• Expose data: create new SMB/NFS shares, open ports, mint new API keys, disable 2FA.
• Cripple the box: stop services, uninstall apps, kick off destructive jobs (scrub/resilver/reboot), wipe disks.

The Quickstart below provisions a Readonly Admin for a reason: it can answer every "how's my NAS doing?" question and cannot change a single thing. Start there. Only escalate when you have a specific write task in mind, and drop back to readonly when you're done.

If you're tempted to skip this because "it's just for me on my LAN" — the API key lives in .env, gets read by tools, gets passed through prompts. The blast radius is not just you typing commands.

Prerequisites

• TrueNAS SCALE — 24.10 (Electric Eel) or newer. The skill targets the JSON-RPC 2.0 / WebSocket API; the legacy REST API is not supported and is removed entirely in 26.04.
• Network reachability to the NAS over HTTPS / WSS (the skill refuses plain HTTP — TrueNAS auto-revokes API keys sent over an unencrypted connection). Self-signed certs are fine; see ADVANCED.md for NODE_TLS_REJECT_UNAUTHORIZED notes.
• Node.js 18+ (uses native fetch and ESM). Check with node --version.
• A TrueNAS user account you can attach an API key to. Local user is fine; LDAP/AD users work too.
• Claude Code (or another skill-aware Claude client) installed and able to read from ~/.claude/skills/ or a project-local .claude/skills/.
• git if you want to clone rather than download a zip — optional.

Install (~3 minutes)

1. In the TrueNAS UI → Credentials → Users → Add:

• Username: claude-skill
• TrueNAS Access: ✅ → Readonly Admin
• Disable Password: ✅
• SMB / Shell / SSH Access: all off

Example of the form filled out correctly:

2. Credentials → API Keys → Add under that user → copy the key (shown once).

Step 1 — open the API Keys page and click Add:

Step 2 — name the key, attach it to the claude-skill user, and copy the generated key:

3. In this directory:

npm install
cp .env.example .env

Edit .env:

TRUENAS_URL=https://your-nas.local
TRUENAS_USERNAME=claude-skill
TRUENAS_API_KEY=<paste the key>

4. Smoke-test:

node scripts/truenas.mjs --ping

5. Symlink (or copy) the directory into:

• User-global: ~/.claude/skills/truenas-scale/, or
• Project-local: .claude/skills/truenas-scale/

Done. Ask Claude "check my NAS health" and the skill kicks in.

Need write access? Edit the user, swap Readonly Admin for a stronger role (full list: Role-Based Access Control). The existing API key picks up new permissions on next call — no need to mint a new one. Custom least-privilege roles: see ADVANCED.md.

PowerShell? Inline JSON params ('[{"name":"…"}]') need special handling — see ADVANCED.md before running write methods.

Using the CLI

# Plain method call
node scripts/truenas.mjs system.info
node scripts/truenas.mjs alert.list

# Query helper — wraps the [filters, options] shape
node scripts/truenas.mjs --query pool.dataset.query \
  --filter pool = tank --select name,used --limit 20

# Long-running jobs — progress prints to stderr
node scripts/truenas.mjs --job pool.scrub '[1,"START"]'

# Tail a collection until Ctrl+C
node scripts/truenas.mjs --watch alert.list

# Full help
node scripts/truenas.mjs --help

Full flag reference, file upload/download, bulk calls, library API: see ADVANCED.md.

What's in the skill

Path	What it is
SKILL.md	Skill entry point Claude loads first.
scripts/truenas.mjs	JSON-RPC client — CLI and importable module.
references/	Topic-specific guides: storage, snapshots, apps, sharing, networking, system, virtualization, query syntax, alerts, audit, auth/2FA, certificates, mail, scheduled tasks, updates/boot.
ADVANCED.md	Deep dive: least-privilege setup, scripted provisioning, hardening, full CLI reference, library usage, security notes.

Security at a glance

• Don't use a Full Admin key. The Quickstart's Readonly Admin is the safe default. (RBAC reference)
• Always https:// / wss:// — TrueNAS auto-revokes keys used over plain HTTP.
• .env is gitignored. Never commit TRUENAS_API_KEY.

Full rationale and hardening checklist: ADVANCED.md.

Further reading

• TrueNAS SCALE documentation hub — top-level docs.
• JSON-RPC 2.0 over WebSocket API — the wire protocol this skill speaks.
• API method reference — every method, every version (use the version dropdown to match your box).
• Role-Based Access Control — role atoms (READONLY_ADMIN, DATASET_WRITE, …) and what each unlocks.
• Managing Users · Managing API Keys · Managing Privileges — UI walkthroughs for the Quickstart steps.
• 26.04 version notes — confirms REST is removed; plan ahead.

Collaborators & Contact

Maintained by Jamie Ede.

• LinkedIn: linkedin.com/in/jamie-ede-5622a662
• Issues & PRs: open one on this repo — the fastest way to get a fix or feature in.

Want to collaborate? Bug reports, new reference guides for TrueNAS subsystems, additional CLI ergonomics, and hardening tips are all welcome. Reach out on LinkedIn or by email if you'd rather chat before opening a PR.

License

MIT — see LICENSE.