truenas-skill

# TrueNAS SCALE Skill

Manage a TrueNAS SCALE server and its apps via the TrueNAS API and Dockge Socket.IO.

## Setup

### Required Environment Variables

```
TRUENAS_URL       — TrueNAS base URL (e.g., https://10.0.0.5:444)
TRUENAS_API_KEY   — API key from TrueNAS UI → API Keys
```

### Optional: TLS Configuration

```
TRUENAS_VERIFY_TLS  — Set to "1" to enforce TLS certificate validation (default: skip for self-signed certs)
```

### Optional: Dockge (Docker Compose UI)

```
DOCKGE_URL        — Dockge URL (e.g., http://10.0.0.5:5001)
DOCKGE_USER       — Dockge login username
DOCKGE_PASS       — Dockge login password
```

### Optional: Homelab Service API Keys

See the `references/` directory for per-service env vars. Common ones:

```
SONARR_URL, SONARR_API_KEY           — TV show management
RADARR_URL, RADARR_API_KEY           — Movie management
PROWLARR_URL, PROWLARR_API_KEY       — Indexer management
OVERSEERR_URL, OVERSEERR_API_KEY     — Media request UI
PLEX_URL                             — Media server (no auth on LAN)
TAUTULLI_URL, TAUTULLI_API_KEY       — Plex analytics
QBITTORRENT_URL                      — Torrent client (no auth)
SABNZBD_URL, SABNZBD_API_KEY         — Usenet client
AUDIOBOOKSHELF_URL, AUDIOBOOKSHELF_API_KEY
NTFY_URL                             — Push notifications
SYNCTHING_URL, SYNCTHING_API_KEY     — File sync
N8N_URL, N8N_API_KEY                 — Workflow automation
NOCODB_URL, NOCODB_API_KEY           — Database
CHANGEDETECTION_URL, CHANGEDETECTION_API_KEY
CRAFTY_URL, CRAFTY_API_KEY           — Game servers
LAZYLIBRARIAN_URL, LAZYLIBRARIAN_API_KEY
METUBE_URL                           — YouTube downloader
KARAKEEP_URL, KARAKEEP_API_KEY       — Bookmarks with AI tagging
```

## API Notes

**HTTPS REQUIRED:** TrueNAS auto-revokes API keys used over HTTP.

> **REST API Deprecation Notice:** The REST API (`/api/v2.0/`) is deprecated in TrueNAS 25.04
> and **fully removed in 26.04**. Use the WebSocket API (via `scripts/truenas-ws.mjs`)...

# TrueNAS Skill

An AI agent skill for managing TrueNAS SCALE via its API. Check pool health, manage datasets and snapshots, monitor alerts, control apps, orchestrate Dockge container stacks, and manage bookmarks — all through natural language.

Works with [Claude Code](https://docs.anthropic.com/en/docs/claude-code), [OpenClaw](https://github.com/openclaw/openclaw), [Cursor](https://cursor.com), and any tool supporting the [SKILL.md](https://agentskills.io) standard.

Part of [unsol.dev](https://unsol.dev)

## Prerequisites

- TrueNAS SCALE instance with API access
- `curl` and `jq` installed
- Node.js 18+ (for WebSocket and Dockge scripts)

## Installation

### OpenClaw (via ClawHub)

```bash
clawhub install truenas-skill
```

### Claude Code

```bash
git clone https://github.com/anotb/truenas-skill.git ~/.claude/skills/truenas-skill
cd ~/.claude/skills/truenas-skill && npm install
```

### Cursor / Other

Clone to your agent's skill directory and run `npm install`.

## Configuration

1. Generate an API key in TrueNAS UI > API Keys
2. Set environment variables (copy `.env.example` to `.env` and fill in values):

```bash
# Required
export TRUENAS_URL=https://10.0.0.5:444
export TRUENAS_API_KEY=your-api-key

# Optional: Dockge
export DOCKGE_URL=http://10.0.0.5:5001
export DOCKGE_USER=your-username
export DOCKGE_PASS=your-password
```

See `.env.example` for the full list of optional service API keys.

**Important:** TrueNAS auto-revokes API keys used over HTTP. Always use HTTPS.

> **Note:** The REST API (`/api/v2.0/`) is deprecated in TrueNAS 25.04 and fully removed in
> 26.04. This skill uses the WebSocket API as the primary method for forward compatibility.

## What You Can Do

| Task | How |
|------|-----|
| Check NAS health | Pool status, alerts, service state |
| Manage datasets | Create, list, delete ZFS datasets |
| Snapshots | Create manual snapshots, check schedules (via WebSocket) |
| Replication | Monitor replication job status |
| App management | List...