194 lines
199 KiB
Markdown
194 lines
199 KiB
Markdown
---
|
|
title: Gremlin — User Guide
|
|
description: How to use Gremlin — the NetGrimoire self-hosted AI agent
|
|
published: true
|
|
date: 2026-04-02T12:23:18.000Z
|
|
tags: gremlin, ai, guide, n8n, ollama
|
|
editor: markdown
|
|
dateCreated: 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
|
|
|
|
```bash
|
|
# 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.
|