Workflows

Workflows

n8n workflow system for HomePilot Agent — automation, notifications, and AI assistance.

Overview

All workflows are defined as JSON files in n8n/workflows/ and imported via scripts/import-workflows.sh. They are stored in n8n's database at runtime.

Workflow	Trigger	Purpose
Personal Assistant	Telegram messages	Full AI Agent with all tools
Chat Assistant	Telegram messages	Read-only infrastructure queries
Artifact Notification	HomePilot webhook	Format and relay artifact events
Morning Drift Briefing	Cron (08:00 UTC)	Daily infrastructure summary
Calendar Trigger	Cron (every 5 min)	Poll Radicale for hp:propose events
Voice Assistant	Voice webhook	Whisper STT → LLM → Piper TTS

Token Model

HomePilot uses two MCP token scopes:

Token	Scope	Used By
Read-only (HP_MCP_TOKEN)	Query infrastructure data, no mutations	Chat Assistant, Morning Briefing
Read-write (HP_MCP_TOKEN_RW)	propose_artifact, record_fact — creates pending changes	Personal Assistant (AI Agent)

propose_artifact does not apply changes — it creates a pending artifact requiring human approval in the HomePilot web UI.

Artifact Notification

Flow

HomePilot lifecycle.propose()
  → POST to HP_EVENTS_WEBHOOK_URL
  → n8n Webhook trigger node
  → Format message (intent, kind, host, review link)
  → POST to Matrix room
  → (Optional) Telegram DM

Webhook Payload

{
  "event": "artifact_proposed",
  "artifact": {
    "id": "uuid",
    "intent": "...",
    "kind": "...",
    "host": "...",
    "proposed_at": "ISO8601"
  }
}

Configuration

In HomePilot deployment .env:

HP_EVENTS_WEBHOOK_URL=http://<agent-host>:5678/webhook/artifact-proposed
HP_EVENTS_WEBHOOK_SECRET=<shared-secret>

The n8n workflow validates the X-HP-Webhook-Secret header against the HP Webhook Secret credential.

Morning Drift Briefing

What It Does

Every day at 08:00 UTC, the workflow:

1. Queries HomePilot MCP for infrastructure state (drift detection)
2. Checks artifact status (pending, approved, rejected)
3. Summarizes findings into a human-readable briefing
4. Posts to Matrix room

Customization

Edit the cron expression in the workflow trigger node to change the schedule. The briefing template is defined in the n8n workflow — modify it to include/exclude sections.

Calendar → HomePilot Trigger

How It Works

1. Polls Radicale CalDAV server every 5 minutes
2. Looks for events tagged hp:propose in the event title or category
3. For each matching event, calls HomePilot MCP to propose the corresponding change
4. Marks events as processed (adds a status note)

Radicale Setup

Create a calendar called "HomePilot" in Radicale. Add events with hp:propose prefix in the title:

• hp:propose:restart-container nginx — propose a container restart
• hp:propose:upgrade-package openssl on pve — propose a package upgrade

Configuration

Radicale credentials are stored in the Radicale Calendar n8n credential:

Field	Value
URL	http://radicale:5232
Username	From RADICALE_USER in .env
Password	From RADICALE_PASSWORD in .env

Chat Assistant (Read-Only)

What It Does

A Telegram bot that answers infrastructure questions using HomePilot MCP (read-only token):

• "What VMs are running on pve?"
• "Show me the status of LXC 100"
• "How much disk space is left on local-lvm?"

Scope

This workflow cannot make changes — it only queries. For mutations, use the Personal Assistant.

Personal Assistant (Full Agent)

What It Does

The full AI Agent workflow:

1. Receives Telegram message
2. Sends to Qwen3-14B for intent analysis
3. If the intent requires infrastructure changes, uses the read-write MCP token
4. Proposes artifacts (pending human approval) — never applies directly
5. Returns response to Telegram

Scope

The Agent can:

• Query all infrastructure data
• propose_artifact (creates pending change)
• record_fact (add knowledge to HomePilot)
• Search the web via SearXNG

It cannot apply changes directly — all mutations go through the artifact lifecycle.

Voice Assistant

Pipeline

Voice webhook → Whisper STT → Text → Qwen3-14B → Response → Piper TTS → Audio response

Requirements

• voice Compose profile must be active
• Whisper container running (whisper:8000)
• Piper container running (piper:5000/10200)
• GPU for Whisper (CPU mode is slow)

Usage

Send audio to the voice webhook endpoint. The workflow processes it and returns synthesized speech.

Matrix Bridge

Configuration

The Matrix bot credential (Matrix Bot) is configured in n8n with:

• Access token from your Matrix server
• Room ID for the target homelab channel

Alert Flow

Zabbix trigger fires
  → Zabbix Action sends webhook
  → Matrix room receives alert

See Monitoring for Zabbix → Matrix webhook setup.

Service Endpoints (Internal)

All services communicate on the Docker network:

Service	URL	Port
n8n	http://n8n:5678	5678
LLM	http://llm:8080/v1	8080
Embeddings	http://llm-embed:8081/v1	8081
SearXNG	http://searxng:8888	8888
Radicale	http://radicale:5232	5232
Whisper	http://whisper:8000	8000
Piper (HTTP)	http://piper:5000	5000
Piper (Wyoming)	http://piper:10200	10200

Adding Custom Workflows

1. Design your workflow in the n8n UI
2. Export as JSON
3. Save to n8n/workflows/your-workflow.json
4. Add credential references matching existing naming conventions
5. Import: scripts/import-workflows.sh