Netgrimoire/Gremlin-Grimoire/Stack/User-Guide.md

title	description	published	date	tags	editor	dateCreated
Gremlin — User Guide	How to use Gremlin — the NetGrimoire self-hosted AI agent	true	2026-04-02T12:23:18.000Z	gremlin, ai, guide, n8n, ollama	markdown	2026-04-02T12:23:18.000Z

Gremlin — User Guide

Gremlin is the NetGrimoire self-hosted AI agent. It runs entirely on local hardware — no cloud, no external APIs. This guide covers day-to-day use of all Gremlin interfaces and automations.

---

What Gremlin Does

Capability	How
AI chat and Q&A	Open WebUI at ai.netgrimoire.com
Compose file analysis and generation	Open WebUI with qwen2.5-coder:7b
Weekly repo standards audit	n8n automated workflow
Service alert triage	Uptime Kuma → n8n → ntfy
Audit reports to Wiki.js	n8n commits to Netgrimoire/Audits/

---

Accessing Gremlin

Interface	URL	Purpose
Open WebUI	https://ai.netgrimoire.com	Primary chat interface
n8n	https://n8n.netgrimoire.com	Workflow management
Ollama API	http://ollama.netgrimoire.com:11434	Direct model API
Qdrant	http://qdrant.netgrimoire.com:6333/dashboard	Vector DB browser

---

Using the Chat Interface

Open WebUI is the primary way to interact with Gremlin directly.

1. Log in at https://ai.netgrimoire.com
2. Select a model from the dropdown at the top
3. Start a conversation

Choosing the Right Model

Task	Model
General questions, infrastructure Q&A, summarization	llama3.2:3b
Docker compose files, YAML, code review, audit	qwen2.5-coder:7b
Complex reasoning, detailed analysis	qwen2.5:14b

Example Prompts

Audit a compose file:

You are Gremlin, the NetGrimoire homelab AI. Our stacks run on Docker Swarm, node docker4, network netgrimoire, volumes at /DockerVol/. Audit this compose file against our standards — check homepage labels, kuma labels, caddy labels, placement constraints, and volume paths. [paste YAML]

Generate a new service:

Generate a NetGrimoire-compliant Docker Swarm service for Gotify (image: gotify/server:latest, port 8080, exposed at gotify.netgrimoire.com, runs on docker4). Follow the standard label template.

Analyze logs:

These are n8n container logs. What is causing the repeated connection refused errors and how do I fix it? [paste logs]

Infrastructure Q&A:

What node does the monitoring stack run on? What port does Uptime Kuma use internally?

Tip: Gremlin has no memory between sessions. Start each chat with the context line: "You are Gremlin, the NetGrimoire homelab AI. Our stacks run on Docker Swarm, node docker4, network netgrimoire, volumes at /DockerVol/."

---

Automated Workflows

Gremlin runs two automated workflows in n8n. Manage them at https://n8n.netgrimoire.com.

Forgejo Repo Audit

Runs: Every Monday at 06:00
What it does: Scans all YAML files in the services repo under swarm/ and swarm/stack/*/. Audits each file against NetGrimoire standards using qwen2.5-coder:7b.

For Swarm files it checks:

• Homepage labels (group, name, icon, href, description)
• Uptime Kuma labels (name, url)
• Caddy labels on exposed services
• Placement constraints
• Volume paths use /DockerVol/ convention
• Network references external netgrimoire overlay

For Compose files (no deploy block) it checks:

• Any exposed ports have a matching Caddyfile entry

On FAIL: ntfy notification to gremlin-audits with a summary, plus a full markdown report committed to Netgrimoire/Audits/ in the docs repo (visible in Wiki.js).

To run manually:

1. Open n8n → Gremlin — Forgejo Repo Audit
2. Click Execute Workflow

Uptime Kuma Alert Triage

Trigger: Webhook from Uptime Kuma on service DOWN
What it does: Receives the alert, sends it to llama3.2:3b for analysis, fires an urgent ntfy notification to gremlin-alerts with likely cause, immediate checks, and severity rating.

RECOVERED events send a simple plain notification — no AI involved.

---

ntfy Notifications

Subscribe to both topics in the ntfy app.

Topic	URL	When
gremlin-alerts	https://ntfy.netgrimoire.com/gremlin-alerts	Service DOWN triage, RECOVERED
gremlin-audits	https://ntfy.netgrimoire.com/gremlin-audits	Audit FAILs, doc commits

---

Uptime Kuma Webhook Setup

To connect Uptime Kuma to Gremlin triage:

1. Uptime Kuma → Settings → Notifications → Add Notification
2. Type: Webhook
3. Friendly Name: Gremlin Triage
4. URL: https://n8n.netgrimoire.com/webhook/gremlin-kuma-alert
5. Content Type: application/json
6. Save and assign to monitors

The Gremlin — Uptime Kuma Alert Triage workflow must be in Published state in n8n for the webhook to respond.

---

Audit Reports in Wiki.js

Full audit reports for any FAIL are automatically committed to the docs repo and appear in Wiki.js under Netgrimoire → Audits. Each report includes:

• Date, file path, service type
• Full Gremlin audit analysis
• Specific issues and recommended fixes
• VERDICT

Reports are named <service>-<date>.md — e.g. calibre-web-2026-04-01.md.

---

Troubleshooting

Symptom	Fix
Open WebUI shows no models	Check docker stack services gremlin — Ollama may be down. Run ollama list on docker4 to confirm models are loaded.
n8n workflow fails at Ollama node	Model name must match exactly. Verify with ollama list. Timeout may need increasing — set to 300000ms in node options.
No ntfy alert on DOWN event	Confirm kuma-triage workflow is Published in n8n. Check webhook URL in Uptime Kuma matches exactly.
Audit workflow runs but no FAILs	Check Executions tab in n8n — look at Filter node output count. Ollama may not be using expected VERDICT wording.
502 on n8n or Open WebUI	Caddy IP mismatch after redeploy. Restart Caddy: docker service update --force caddy_caddy from znas.
n8n won't start — permission denied	Run chown -R 1000:1000 /DockerVol/n8n on docker4 then docker service update --force gremlin_n8n from znas.

Key Commands

# All run on znas unless noted

# Check service status
docker stack services gremlin

# Restart a service
docker service update --force gremlin_<service>

# View logs
docker service logs gremlin_n8n --tail 50

# Check models (docker4)
docker exec $(docker ps -qf name=gremlin_ollama) ollama list

# Pull a model (docker4)
docker exec $(docker ps -qf name=gremlin_ollama) ollama pull <model>

# Full redeploy (from services/swarm/stack/Gremlin/ on znas)
./deploy.sh

---

Notes

• Gremlin is local-first. All inference runs on docker4 via Ollama. Works fully offline once models are pulled.
• n8n version 2.13.4. Workflow imports reset node configs — if reimporting, reconfigure Code node contents manually.
• Forgejo 11+ requires POST to create files, PUT with SHA to update. All Gremlin workflows handle this automatically.
• Wiki.js syncs from traveler/Netgrimoire repo. Allow a few minutes after a Gremlin commit for pages to appear.