homelab-assist

Manage Docker via Dockhand — the preferred control plane in this homelab — and its Hawser remote agents. Covers the Dockhand architecture (central server + Hawser Standard/Edge agents), how to drive it (the mcp-dockhand MCP server or its REST API), compose-stack and container operations, multi-host/environment targeting, and Git-synced stacks. Load this when the user manages Docker with Dockhand.

Shared foundational knowledge for working with Docker Compose stacks — the compose file format, services/networks/volumes/secrets, environment and .env handling, healthchecks, common operations (up/down/pull/logs/ps), and safe-change practices. Load this for any compose-based work, alongside the control-plane skill (Dockhand/Portainer/Dockge) that actually applies the changes.

Understand and troubleshoot a Docker host running inside Proxmox — as a VM or as a privileged/unprivileged LXC — and how VLAN networking, macvlan/ipvlan, VLAN-aware bridges, and passed-through/bind-mounted storage interact across the Proxmox and Docker layers. Load this when a Docker networking or storage problem may originate at the Proxmox layer, or when planning how to host Docker on Proxmox.

Entry point and router for managing Docker in a homelab. Load this first for any Docker request — it identifies which control plane is in use (Dockhand preferred, or Portainer/Dockge/raw Engine), establishes the version check, and routes to the right skill (compose stacks, Dockhand, reverse-proxy label routing, or Docker-on-Proxmox networking).

Manage Docker compose stacks via Dockge — a file-based stack manager that stores stacks as compose files under /opt/stacks. Covers its file-on-disk model, the lack of a REST API/MCP (so operations are filesystem- or SSH-oriented), and how to edit stacks safely. Load this when the user manages Docker with Dockge.

Set up and manage domain routing for homelab services using nginx-proxy-manager (NPM) driven by Docker container labels via npm-docker-sync. Load this when the user wants to expose a container/stack at a domain, debug why a service isn't routing, or understand the label-based proxy-host automation pattern. Covers the npm.* label scheme, how sync maps containers to NPM proxy hosts, and SSL/forced-host details.

Manage Docker (and Kubernetes) via Portainer's REST API or the official portainer-mcp server — environments/endpoints, stacks, containers/images/networks/volumes, and the Docker API proxy. Load this when the user manages Docker with Portainer rather than Dockhand.

Orientation for the homelab-assist plugin suite — what plugins and skills exist (Proxmox, Docker), how they relate, and how to route a homelab request to the right skill. Load this when the user makes a broad homelab request, when you're unsure which homelab skill applies, or when a task spans both Proxmox and Docker.

How to research version-correct, canonical answers for homelab software (Proxmox, Docker, Dockhand, Portainer, nginx-proxy-manager, etc.) without being misled by stale search results. Load this whenever you are not fully confident about a configuration, command, API field, or behavior before acting on a homelab system.

The change-approval and SSH-confirmation policy for ALL homelab operations (Proxmox, Docker, and any other infrastructure). Load and apply this before performing any action that changes a homelab system or that requires SSH/host access. Other homelab skills defer to this policy.

How to store and use homelab credentials securely via the OS-native secret store (macOS Keychain, Windows Credential Vault, Linux libsecret/pass) instead of plaintext env vars, dotfiles, or committed files — and how to handle SSH auth (keys over passwords, ssh-agent, passphrases in the keychain). Load this whenever a task needs a token, password, or SSH credential: setting one up, retrieving one to run a command or MCP server, or advising the user where to keep it. Pairs with homelab-ssh and homelab-safety.

The execution discipline and guardrails for doing ANYTHING over SSH on a homelab host (Proxmox nodes, Docker hosts, NAS, etc.). SSH is root-level power with no undo, so load this whenever a task will run shell commands or edit files on a host over SSH. Covers host-identity confirmation, read-before-write, backup/rollback, validate-before-apply, the never-without-confirmation dangerous-command list, lockout avoidance, scripting hygiene, and secret handling. Works together with homelab-safety (which governs approval) — this skill governs how the SSH work is actually carried out.

How to authenticate to and call the Proxmox VE REST API — API token setup, the pve-api.sh helper, common endpoints, and how to poll background tasks. Load this when you need to make Proxmox API calls directly (any VM/LXC/storage/backup/cluster operation that goes through the API rather than an MCP server).

Host-level Proxmox configuration that the REST API cannot do and requires SSH/file edits — GPU and PCIe passthrough, VFIO/IOMMU/kernel-module setup, unprivileged-LXC lxc.idmap UID/GID remapping, LXC features (nesting/keyctl/fuse), hookscripts, and advanced /etc/network/interfaces. Load ONLY when an API-based approach is impossible. Every action here requires confirming the SSH drop first and backing up files before editing.

Manage Proxmox LXC containers via the REST API — list, inspect, start/stop, create, clone, migrate, snapshot, and basic config. Covers the privileged-vs-unprivileged distinction and where simple mount points end and host-file edits begin. Load this for LXC/container tasks on Proxmox. For lxc.idmap, bind-mount UID remapping, nesting/keyctl tweaks, or hookscripts, use proxmox-host-config.

Entry point and router for managing Proxmox VE. Load this first for any Proxmox request — it establishes the version check, the API-first-vs-SSH decision, how to authenticate, and which specific Proxmox skill to use (VMs, LXC, storage/backups, updates, or host-level config like GPU passthrough).

Understand and manage Proxmox storage and backups via the REST API — list storage and content, understand storage types (dir/LVM/ZFS/NFS/CIFS/PBS), run vzdump backups, schedule backup jobs, and restore VMs/LXC from archives or Proxmox Backup Server. Load this for storage inspection, backup creation, or restore tasks on Proxmox.

Check for and apply Proxmox VE package updates safely via the API, understand the enterprise vs no-subscription repositories, and navigate major-version upgrade gotchas (8.x to 9.x). Load this when the user wants to check for updates, patch, or upgrade Proxmox. Major upgrades are high-risk — research version-specific guidance first.

Manage Proxmox QEMU/KVM virtual machines via the REST API — list, inspect, start/stop/reboot, create, clone, migrate, snapshot/rollback, resize disks, and edit VM config. Load this for any virtual-machine task on Proxmox. For GPU/PCIe passthrough or other host-file-level VM config, use proxmox-host-config instead.