unraid-docker-manager/.planning/PROJECT.md

Unraid Docker Manager

What This Is

A conversational Telegram bot that lets you manage Docker containers on your Unraid server using natural language. Think JARVIS for your homelab — ask questions, get status updates, and control containers all from your phone without needing to open a laptop.

Core Value

When you get a container update notification or notice a service is down, you can immediately investigate and act from your phone through a natural conversation.

Requirements

Validated

(None yet — ship to validate)

Active

• Send a message to the bot and receive a response
• Ask about container status ("how's Plex doing?")
• Start a container by name
• Stop a container by name
• Restart a container by name
• Update a container (pull new image, recreate)
• View container logs with configurable line count (default 50)
• Ask conversational questions ("what's using the most memory?")
• Bot only responds to your Telegram user ID

Out of Scope

• Taking over Unraid notifications — keep existing notification system, this bot is for control
• Deploying new containers — manage existing only, not create new ones
• Local LLM — N100 can't handle it well, using Claude API instead
• Proactive monitoring/notifications — bot is reactive (you ask, it answers) for v1

Context

Environment:

• Unraid server with Intel N100 CPU, 32GB RAM
• n8n already running and mostly unused — will use as orchestration layer
• Multiple Docker containers running various services (Plex, Sonarr, etc.)

Current workflow:

• Unraid sends notifications when container updates are available
• Currently need laptop/desktop to act on updates or troubleshoot
• Want to be able to respond immediately from phone

User scenarios:

1. Get update notification → open Telegram → "update plex" → done
2. Notice service not responding → "check sonarr logs" → see errors → "restart sonarr"
3. Curious about system → "what containers are running?" or "what's using the most resources?"

Constraints

• Platform: Must run on Unraid (Docker-based deployment)
• Orchestration: Use n8n for workflow orchestration (already running)
• LLM: Claude API for natural language understanding
• Auth: Single user only — verify Telegram user ID
• Logs: Support configurable line count, default to 50 lines

Key Decisions

Decision	Rationale	Outcome
Use Claude API over local LLM	N100 CPU can't run LLMs fast enough for good UX	— Pending
Use n8n for orchestration	Already running, handles Telegram webhooks, reduces new infrastructure	— Pending
Manage existing containers only	Keeps scope focused, deployment is complex and rarely needed from mobile	— Pending
Single user auth via Telegram ID	Simple security model, only one person needs access	— Pending

---

Last updated: 2026-01-28 after initialization