---
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](data:image/png;base64,[encoded data, 196868 characters])

# 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.
