Built with AI — This project was co-developed by Gemini 2.5 Pro, Gemini 3.0 Pro (Preview), and Claude 4.5 Opus. It's a product of the vibe coding revolution. ✨

⚠️ Disclaimer

USE AT YOUR OWN RISK!

This codebase is mostly AI-generated and has not been fully audited by the author. While it works, there may be bugs, security issues, or unexpected behaviors. The author takes no responsibility for:

💥 Data loss
🔓 Security vulnerabilities
🐛 Bugs or unexpected behavior
🔥 Any damage to your infrastructure

Do not run this in production without thoroughly reviewing the code yourself.

✨ Features

🧠 AI Assistant — Natural language task execution and pipeline generation
🌐 DNS Management — Control both Namecheap and self-hosted Technitium DNS
🖥️ Proxmox VE Integration — Manage nodes, VMs, containers, and backups
💻 Remote Shell — Execute commands on your server via Telegram
🛡️ Granular RBAC — Fine-grained role-based access control with module visibility
📨 Messaging — Whisper to individual users or broadcast to everyone
📜 Audit Logging — Track all actions with powerful filtering
🔐 Encrypted Vault — Securely store API keys with AES encryption
🌍 Per-User Localization — Each admin can choose their own locale
🎛️ Interactive UI — Permission-aware inline keyboards for easy navigation

📦 Modules

🌐 Namecheap DNS (`/nc`)

Manage your Namecheap domain DNS records directly from Telegram.

Command	Description
`/nc`	List all domains you have access to
`/nc [domain]`	View/manage records for a specific domain
`/nc add [domain] [type] [host] [value]`	Add a new DNS record
`/nc edit [domain] [id] [value]`	Modify an existing record
`/nc del [domain] [id]`	Delete a record
`/nc import [domain]`	Upload a zone file
`/nc export [domain]`	Download zone file
`/nc diff [domain]`	Compare with Technitium
`/nc sync_from_tc [domain]`	Import records from Technitium
`/nc nuke [domain]`	⚠️ Delete ALL records

Permissions: Full access or granular domain-level access via {'domains': ['example.com']}

🌐 Technitium DNS (`/tc`)

Manage your self-hosted Technitium DNS server.

Command	Description
`/tc`	List all zones you have access to
`/tc [zone]`	View/manage records for a specific zone
`/tc create [zone]`	Create a new zone
`/tc delete [zone]`	Delete a zone
`/tc add [zone] [type] [host] [value]`	Add a new record
`/tc del [zone] [id]`	Delete a record
`/tc import [zone]`	Upload a zone file
`/tc export [zone]`	Download zone file
`/tc nuke [zone]`	⚠️ Delete ALL records

Permissions: Full access or granular zone-level access via {'zones': ['example.com']}

🖥️ Proxmox VE (`/px`)

Full control over your Proxmox cluster, nodes, VMs, and containers.

Command	Description
`/px`	Cluster overview with interactive menu
`/px vms`	List all VMs and containers
`/px node <name>`	View node details
`/px vm <node/vmid>`	View VM details
`/px ct <node/vmid>`	View container details
`/px start <node/vmid>`	Start a VM/container
`/px stop <node/vmid>`	Stop a VM/container
`/px shutdown <node/vmid>`	Graceful shutdown
`/px reboot <node/vmid>`	Reboot VM/container
`/px node shutdown <name>`	Shutdown a node
`/px node reboot <name>`	Reboot a node
`/px node wake <name>`	Wake-on-LAN for a node
`/px backups`	List backup jobs
`/px backup <id>`	View backup job details
`/px backup run <id>`	Run a backup job now

Permissions:

Full access: Manage entire cluster
Node access: {'nodes': ['pve1']}
VM access: {'vms': ['pve1/100']}

📨 Messaging (`/whisper`, `/broadcast`)

Send private or broadcast messages to other bot users via Telegram.

Command	Description
`/whisper <id_or_name> <message>`	Send a private message to a user
`/broadcast <message>`	Send a message to all users

Permissions:

whisper — Send private messages to individual users
broadcast — Send to all users (implies whisper)

Having the broadcast role automatically grants whisper access, but not the other way around.

🌍 Localization (`/locale`)

Each admin can set their preferred locale. The bot loads all available locales from the locales/ directory (e.g. en_US.json) and falls back to en_US for any missing keys.

Command	Description
`/locale`	Show your current locale and list all available locales
`/locale <code>`	Change your own locale (e.g. `/locale en_US`)

The root admin can also manage other users' locales via /admin locale (see Admin Management below).

Adding a new locale: Create a new JSON file in locales/ (e.g. it_IT.json) with the same keys as en_US.json. It will be automatically discovered.

💻 System Shell (`/exec`, `/sh`)

Execute shell commands on the host machine. Requires the 'exec' permision.

Command	Description
`/exec <command>`	Run a shell command
`/sh <command>`	Alias for `/exec`

Examples:

/exec df -h
/exec docker ps
/sh free -m

⚠️ Commands run with the bot process's permissions.

🛡️ Admin Management (`/admin`)

Manage bot users and their permissions.

Command	Description
`/admin list` or `/admins`	List all admins (paginated)
`/admin info <user>`	View user's permissions
`/admin roles`	List available modules
`/admin add <id> [nick] [modules]`	Add a new admin
`/admin del <user>`	Remove an admin
`/admin nick <user> <name>`	Set a nickname
`/admin locale <user>`	Show user's locale (root only)
`/admin locale <user> <code>`	Set user's locale (root only)
`/admin grant <user> <module>`	Grant full module access
`/admin grant <user> <module> <json>`	Grant granular permissions
`/admin revoke <user> <module>`	Revoke access

Shorthand grants:

/admin grant <user> zone example.com      # Technitium zone
/admin grant <user> domain example.com    # Namecheap domain
/admin grant <user> node pve1             # Proxmox node
/admin grant <user> vm pve1/100           # Proxmox VM
/admin grant <user> viewer proxmox        # Dashboard button visibility

The same shorthands work with /admin revoke.

📜 Audit Logs (`/audit`, `/logs`)

View and filter bot activity logs.

Command	Description
`/audit`	View audit log (paginated)
`/audit <time>`	Filter by age (e.g., `1h`, `7d`)
`/audit wipe`	Delete all logs (root only)
`/log <id>`	View specific log entry
`/log_channel <id>`	Set log broadcast channel

Advanced Filters:

/audit before=2025-01-01
/audit after=7d
/audit module=proxmox           # Supports regex! e.g., module=prox|tech
/audit from=admin
/audit action=create
/audit target=example.com
/audit limit=50

Multi-value & Negation:

Repeat filters for AND logic: from=a from=b
Prefix with ! to exclude: from=!admin

🔐 Vault (`/vault`)

Manage encrypted secrets storage. Root only.

⚠️ The vault is mostly meant to keep secrets safe at rest. While a best-effort approach is taken to remove the secrets from memory when the vault is locked (by clearing the vault state and triggering a manual garbage collection), this is not a security guarantee.

Command	Description
`/vault`	View vault status and manage secrets
`/unlock [password]`	Unlock the vault
`/lock`	Lock the vault

The vault stores sensitive API keys (Namecheap, Technitium, Proxmox tokens) encrypted with AES-256 using PBKDF2 key derivation.

🧠 AI Assistant (`/llm`)

A powerful agent capable of executing complex multi-step tasks using natural language. It can generate and execute pipelines of actions across different modules.

Command	Description
`/llm <instruction>`	Instruct the AI to perform a task
`/pl`	List saved pipelines
`/pl <name>`	Load a saved pipeline

Pipeline Management:

Review and edit generated steps before execution.
Save useful pipelines for later reuse.
Execute steps sequentially or in parallel.

Examples:

/llm create a new VM on pve1 named web-server and add a DNS record for it
/llm check disk usage on all nodes and alert me if > 80%

Requirements:

OPENAI_API_KEY stored in the vault.
LLM_MODEL configured in .env (default: gpt-4o).

🔧 Configuration (`/config`)

Manage runtime configuration. Root only.

Command	Description
`/config` or `/cf`	View all config variables
`/get <name>`	Get a config value
`/set <name> <value>`	Set a config value

🛑 Root-Only System Commands

The following commands are restricted to the root admin (the user ID set as ROOT_ADMIN_ID):

Command	Description
`/unlock [password]`	Unlock the encrypted vault (deletes the message for security)
`/lock`	Lock the vault and wipe secrets from memory
`/reboot`	Restart the bot process, locking the vault first
`/stat`, `/stats`, `/status`	Show bot statistics (uptime, version, admin count, etc.)
`/startups`	List bot startup events (with pagination)
`/cf`, `/config`	List configuration variables (non-secret only)
`/get <name>`	View a configuration variable (non-secret only)
`/set <name> <value>`	Set a configuration variable (non-secret only)
`/log_channel <id>`	Set or view the audit log channel

Note:

Secret config values (API keys, tokens) cannot be viewed or set via /get or /set.
/unlock and /lock control access to all sensitive secrets in memory.
/reboot will cause the bot to lock the vault and restart itself (useful after config or code changes).

🛡️ RBAC Roles Reference

All available roles can be viewed in-bot with /admin roles.

Role	Key	Description
Admin Manager	`admin`	Manage users, roles, and permissions
Namecheap Admin	`namecheap`	Manage Namecheap domains (supports granular domain access)
Technitium Admin	`technitium`	Manage Technitium zones (supports granular zone access)
DNS Super Admin	`dns`	Implies `namecheap` + `technitium`
Proxmox Admin	`proxmox`	Manage Proxmox cluster (supports granular node/VM access)
Executor	`exec`	Execute shell commands
Audit Viewer	`audit`	View audit logs
Audit Trail	`audit_trail`	Flag: logs all of the user's interactions verbosely
Module Viewer	`viewer`	See dashboard buttons without interaction rights
Whisper	`whisper`	Send private messages to other users
Broadcaster	`broadcast`	Send messages to all users (implies `whisper`)

Role hierarchies:

dns implies namecheap + technitium
broadcast implies whisper

Module Viewer: The viewer role controls which module buttons appear on a user's dashboard. Users without any permission for a module (and without viewer access) will not see its button. This is purely cosmetic — the module's own RBAC checks still enforce access.

Grant visibility for a specific module: /admin grant <user> viewer proxmox
Grant visibility for all modules: /admin grant <user> viewer
Revoke: /admin revoke <user> viewer proxmox

🚀 Setup Guide

Prerequisites

🐍 Python 3.14+
📦 Poetry package manager
🤖 A Telegram Bot Token (from @BotFather)
📂 Access to the services you want to manage (Namecheap, Technitium, Proxmox)

1️⃣ Clone & Install Dependencies

git clone https://github.com/your-username/homelab-bot.git
cd homelab-bot

# Install Poetry if you don't have it
curl -sSL https://install.python-poetry.org | python3 -

# Install dependencies
poetry install

2️⃣ Configure Environment Variables

Create a .env file in the project root:

# 🤖 Telegram Bot Configuration
BOT_TOKEN=your_telegram_bot_token_here
ROOT_ADMIN_ID=your_telegram_user_id

# 🌐 Namecheap Configuration
NC_USERNAME=your_namecheap_username
NC_API_USER=your_namecheap_api_user
NC_CLIENT_IP=your_whitelisted_ip
NC_API_KEY=your_namecheap_api_key          # Will be moved to vault

# 🌐 Technitium Configuration
TECHNITIUM_URL=http://your-technitium-server:5380
TECHNITIUM_TOKEN=your_technitium_api_token  # Will be moved to vault

# 🖥️ Proxmox Configuration
PROXMOX_HOST=your-proxmox-host:8006
PROXMOX_USER=root@pam
PROXMOX_TOKEN_NAME=your_token_name
PROXMOX_TOKEN_VALUE=your_token_value        # Will be moved to vault
PROXMOX_VERIFY_SSL=false

# 🧠 AI Configuration
OPENAI_API_KEY=sk-...                       # Will be moved to vault
LLM_MODEL=gpt-4o                            # Optional, default: gpt-4o

# 📜 Optional: Log Channel
LOG_CHANNEL_ID=                              # Telegram channel ID for audit logs

3️⃣ Set Up the Encrypted Vault

The vault securely stores your sensitive API keys. Run the setup wizard:

poetry run python setup_vault.py

This will:

Read NC_API_KEY, TECHNITIUM_TOKEN, PROXMOX_TOKEN_VALUE, and OPENAI_API_KEY from .env
Ask you to create a master password (min 8 characters)
Encrypt and store the secrets in the database

After setup, you can remove the sensitive keys from .env — they're now safely stored in the encrypted vault.

4️⃣ Run the Bot

# Run with vault unlock prompt at startup
poetry run python main.py --unlock

# Or run without unlocking (limited functionality)
poetry run python main.py

You can also unlock the vault later via Telegram with /unlock <password>.

🐳 Docker Deployment

A Dockerfile is included for containerized deployment:

# Build the image
docker build -t homelab-bot .

# Run with persistent data
docker run -d \
  --name homelab-bot \
  -v $(pwd)/data:/app/data \
  -v $(pwd)/.env:/app/.env:ro \
  homelab-bot

Note: You'll need to pass the vault password at startup or unlock via Telegram.

🔒 Security Considerations

Vault Encryption — API keys are encrypted with AES-256 (Fernet) using PBKDF2HMAC with 480,000 iterations
RBAC — Granular permissions prevent unauthorized access; the viewer role controls dashboard button visibility without granting interaction rights
Audit Trail — All actions are logged with user, timestamp, and details
Root Admin — Only the ROOT_ADMIN_ID can access vault and critical operations

Recommendations:

🔐 Use a strong vault password
🚫 Don't expose the bot to untrusted users
📋 Regularly review audit logs
🔄 Keep the bot and dependencies updated

📁 Project Structure

homelab-bot/
├── main.py              # Entry point
├── setup_vault.py       # Vault setup wizard
├── pyproject.toml       # Poetry dependencies
├── Dockerfile           # Container deployment
├── locales/
│   └── en_US.json       # English (US) locale strings
├── core/
│   ├── config.py        # Settings & environment
│   ├── strings.py       # Per-request locale-aware string lookups
│   ├── vault.py         # Encrypted secrets manager
│   ├── rbac.py          # Role-based access control
│   ├── middleware.py     # Telegram middlewares
│   ├── decorators.py    # Permission decorators
│   └── logging.py       # Audit logging utilities
├── modules/
│   ├── admin/           # User & permission management
│   ├── audit/           # Audit log viewing
│   ├── general/         # Start, help, cancel handlers
│   ├── llm/             # AI Assistant & Pipelines
│   ├── messaging/       # Whisper & broadcast messaging
│   ├── namecheap/       # Namecheap DNS client
│   ├── proxmox/         # Proxmox VE client
│   ├── system/          # Shell execution
│   ├── technitium/      # Technitium DNS client
│   └── vault/           # Vault management UI
└── data/                # SQLite database (persistent)

🤝 Contributing

This is a personal project, but PRs are welcome! Please:

🍴 Fork the repository
🌿 Create a feature branch
✅ Test your changes
📝 Submit a pull request

📄 License

MIT License — See LICENSE for details.

🙏 Acknowledgments

🤖 Gemini 2.5 Pro, Gemini 3.0 Pro (Preview) & Claude 4.5 Opus — For doing most of the heavy lifting
📚 aiogram — Excellent Telegram bot framework
🗃️ Piccolo — Async ORM for SQLite
🔐 cryptography — Vault encryption

Built with 💜 and AI vibes

README.md Unescape Escape

🏠 HomeLab Bot