claude-homelab

Claude Homelab

Current release: 1.4.0.

Homelab plugin hub for Claude Code, Codex, and Gemini. This repository is the source of truth for the homelab-core plugin, bundled skill-only integrations, agents, commands, and shared credential bootstrapping.

Overview

claude-homelab serves three roles at once:

• The homelab-core plugin published through the Claude marketplace
• The canonical mono-repo for 16 bundled skill-only service integrations
• The source for Codex and Gemini extension manifests that mirror the same workflow surface

The repo root is the plugin root. Do not edit generated copies in ~/.claude/ or ~/.claude/plugins/cache/ directly.

Installation

Claude marketplace

/plugin marketplace add jmagar/claude-homelab
/plugin install homelab-core @jmagar-claude-homelab

After install, Claude Code downloads the plugin into ~/.claude/plugins/cache/. No symlinks are created on this path.

Bash / symlink install

curl -sSL https://raw.githubusercontent.com/jmagar/claude-homelab/main/scripts/install.sh | bash

Or, if you already have the repo cloned:

./scripts/install.sh

The installer:

1. Checks prerequisites (git, jq, curl)
2. Clones the repo to ~/claude-homelab (or pulls if it exists)
3. Runs setup-creds.sh — creates ~/.claude-homelab/.env from .env.example with chmod 600
4. Runs setup-symlinks.sh — symlinks skills, agents, and commands into ~/.claude/
5. Runs verify.sh — confirms every symlink and required file is in place
6. Prints next steps

Credential Model

All credentials for every service live in a single file:

~/.claude-homelab/.env

This file is created from .env.example at install time and is never committed. Set it up interactively after install:

# Interactive wizard (preferred)
# Open Claude Code and run:
/homelab-core:setup

# Or configure manually
$EDITOR ~/.claude-homelab/.env

Security requirements:

• ~/.claude-homelab/.env must have chmod 600 (owner read/write only)
• Never commit .env — it is gitignored
• Never log credentials, even in debug mode
• Use .env.example as the template (tracked in git, placeholder values only)

All service scripts load credentials via scripts/load-env.sh:

source "${CLAUDE_PLUGIN_ROOT:-$HOME/claude-homelab}/scripts/load-env.sh"
load_env_file || exit 1
validate_env_vars "SERVICE_URL" "SERVICE_API_KEY"

Environment Variable Reference

Variables are grouped by service. Copy .env.example to ~/.claude-homelab/.env and replace placeholder values.

Media

Variable	Required	Description
PLEX_URL	yes	Plex server base URL
PLEX_TOKEN	yes	Plex authentication token
OVERSEERR_URL	yes	Overseerr base URL (skill)
OVERSEERR_API_KEY	yes	Overseerr API key (skill)
RADARR_URL	yes	Radarr base URL
RADARR_API_KEY	yes	Radarr API key
RADARR_DEFAULT_QUALITY_PROFILE	no	Default quality profile ID (default: 1)
SONARR_URL	yes	Sonarr base URL
SONARR_API_KEY	yes	Sonarr API key
SONARR_DEFAULT_QUALITY_PROFILE	no	Default quality profile ID (default: 1)
PROWLARR_URL	yes	Prowlarr base URL
PROWLARR_API_KEY	yes	Prowlarr API key
TAUTULLI_URL	yes	Tautulli base URL
TAUTULLI_API_KEY	yes	Tautulli API key

Downloads

Variable	Required	Description
SABNZBD_URL	yes	SABnzbd base URL
SABNZBD_API_KEY	yes	SABnzbd API key
QBITTORRENT_URL	yes	qBittorrent WebUI URL
QBITTORRENT_USERNAME	yes	qBittorrent username
QBITTORRENT_PASSWORD	yes	qBittorrent password

Infrastructure

Variable	Required	Description
UNRAID_SERVER1_NAME	yes	Display name for first Unraid server
UNRAID_SERVER1_URL	yes	Unraid GraphQL endpoint (skill)
UNRAID_SERVER1_API_KEY	yes	Unraid API key (skill)
UNRAID_SERVER2_NAME	no	Display name for second Unraid server
UNRAID_SERVER2_URL	no	Second Unraid GraphQL endpoint
UNRAID_SERVER2_API_KEY	no	Second Unraid API key
UNIFI_URL	yes	UniFi controller URL (skill)
UNIFI_USERNAME	yes	UniFi username
UNIFI_PASSWORD	yes	UniFi password
UNIFI_SITE	no	UniFi site name (default: default)
TAILSCALE_API_KEY	yes	Tailscale API key
TAILSCALE_TAILNET	yes	Tailscale tailnet name or -
ZFS_HOST	yes	Host where ZFS commands run
SWAG_HOST	yes	SWAG reverse proxy host
SWAG_CONTAINER_NAME	no	SWAG container name (default: swag)
SWAG_APPDATA_PATH	no	SWAG appdata path
SWAG_COMPOSE_PATH	no	SWAG compose file path

Utilities and Document Management