Proxmox Infrastructure Guide

Quick reference for Claude Code on the Proxmox homelab infrastructure.

Full documentation: https://docs.bogocat.com | source

---

Intent-Based Operations

For infrastructure operations, use the Intent System instead of direct commands.

Check status: ./scripts/intent-config.sh status

Slash Commands

Command	Description	Risk
/intents:deploy-app <app>	Deploy to Kubernetes	High
/intents:observe-app <app>	View pods, logs, events	Read-only
/intents:check-logs <app>	View logs with filters	Read-only
/intents:scale-app <app> <n>	Scale replicas	Medium
/intents:restart-app <app>	Rolling restart	Low
/intents:migrate-schema <app>	Database migrations	Medium
/intents:scaffold-nextjs <name>	Create new Next.js app	Medium
/intents:verify-backups	Check Velero backup health	Read-only
/intents:deploy-music-display	Deploy to Raspberry Pi	Medium

Natural Language Mapping

User Says	Intent	Action
"deploy home-portal"	deploy-app	Execute directly
"show me logs"	check-logs	Ask which app first
"scale to 3"	scale-app	Ask which app first
"restart the app"	restart-app	Ask which app first
"what's running in money-tracker"	observe-app	Execute directly

Rules

1. Ask, don't guess - If app name or params unclear, ask for clarification
2. Slash commands > direct commands - Deterministic matching preferred
3. Log proposals - Use scripts/log-intent-proposal.sh for audit trail
4. Validate first - Use scripts/validate-proposal.sh before execution

When NOT to Use Intents

• One-off kubectl queries not covered by existing intents
• Development tasks (npm, editing code, git)
• Non-infrastructure operations

Toggle System

./scripts/intent-config.sh status   # View config
./scripts/intent-config.sh disable  # Fall back to direct commands
./scripts/intent-config.sh enable   # Re-enable intents

Config: /root/tower-fleet/intents/config.yaml Docs: /root/tower-fleet/intents/llm-rules.md

---

Project Structure

/root/projects/              # All Next.js apps
├── home-portal/            # Dashboard (K8s production)
├── money-tracker/          # Finance tracker (K8s production)
├── trip-planner/           # AI travel planning (K8s production)
├── rms/                    # Recipe system
├── tcg/                    # Trading card game
├── brainlearn/             # Educational videos
├── subtitleai/             # Subtitle generation
├── music-control/          # Music automation
├── notes-app/              # Note-taking
├── replyflow/              # Reply automation
├── vault-platform/         # Vault management
├── ai-providers/           # AI provider integrations
├── palimpsest-web/  -> /root/palimpsest/web   # RPG frontend
└── palimpsest-api/  -> /root/palimpsest       # RPG API

/root/tower-fleet/           # Infrastructure repo
├── docs/                   # Documentation (92k+ lines)
├── intents/                # Intent system
├── manifests/apps/         # K8s manifests
└── scripts/                # Deployment & utility scripts

/root/palimpsest/            # RPG monorepo
├── api/                    # FastAPI + Pydantic AI
├── web/                    # Next.js frontend
├── lib/                    # Shared vault logic
└── campaigns/              # Markdown vaults

/root/arr-stack/             # Media automation config

---

Quick Commands

# Intent system
./scripts/intent-config.sh status
./scripts/run-intent.sh intents/examples/observe-app.yaml --params app=home-portal

# Development
cd /root/projects/<app> && npm run dev
tmux attach -t <app>

# Kubernetes
kubectl get pods -n <app>
kubectl logs -n <app> -l app=<app> --tail=50

# Infrastructure
qm list                      # List VMs
ssh root@10.89.97.50         # arr-stack VM
kubectl get pods -n supabase-sandbox

---

Infrastructure Layout

Proxmox host: Development runs directly here (Node.js 22)

VMs: - VM 100: arr-stack (10.89.97.50) - VMs 201-203: k3s cluster

Kubernetes: 3-node k3s cluster for production

---

Development Patterns

See: App Conventions

Core stack: Next.js 16 + React 19 + TypeScript + Tailwind CSS v4 + Supabase

Key points: - Schema-based isolation: Each app has own Supabase schema (home_portal, money_tracker, etc.) - Production K8s apps use Authentik SSO (AUTH_MODE baked at Docker build time) - Never use Promise.all() with unbounded arrays - use batchAsync() utility

---

Deployment Workflows

Creating New Apps

Use: /intents:scaffold-nextjs <name>

Docs: Creating a New App

Deploying to Production

Use: /intents:deploy-app <app>

Docs: Production Deployment

Database Migrations

Use: /intents:migrate-schema <app>

Golden rule: NEVER create tables directly. Always use migrations.

Docs: Database Migrations

---

Git & Code Review

Commit format: type: brief summary - Types: feat, fix, docs, refactor, chore - NO emojis in commits - NO "Generated with Claude Code" footer

Review process: 1. Commit locally 2. Request review: "evaluate the code" 3. Fix P0 issues 4. Push after review

Docs: /root/GIT_PATTERNS.md

---

Documentation

Resource	Location
Full docs	https://docs.bogocat.com
Source	/root/tower-fleet/docs/
App conventions	app-conventions.md
Intent rules	llm-rules.md

Pattern: Reference docs rather than re-explaining documented topics.

---

MCP Tools

shadcn/ui Registry: Search 449+ components directly. - "Show me shadcn calendar components" - "How do I use the data table?"