maarten
/
incus-contrib
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
incus-contrib/CLAUDE.md

5.0 KiB
Raw Blame History

CLAUDE.md - Project context for AI assistants

What this repository is

A collection of peripheral tools, scripts, and snippets for working with Incus, IncusOS, and the broader ecosystem (Operations Center, Migration Manager). Primarily targeting home lab environments but aiming for production-quality scripts.

Repository structure

incus-contrib/
├── CLAUDE.md              # This file -- behavioral rules + project overview
├── .claude/rules/         # Topic-specific context (auto-loaded by paths:)
├── .claude/skills/        # Slash commands: /screenshot, /proxmox-api
├── README.md              # Main overview
├── .gitignore
├── ansible/               # Ansible playbooks for AWX/Aether lifecycle hooks
│   ├── ansible.cfg
│   └── playbooks/
│       ├── post-deploy.yml    # Runs after Aether creates an instance
│       └── decommission.yml   # Runs before Aether deletes an instance
├── incusos/               # IncusOS installation tooling
│   ├── README.md
│   ├── incusos-iso        # ISO/IMG builder (wraps flasher-tool)
│   ├── incusos-seed       # Seed archive generator (Linux + macOS)
│   ├── incusos-proxmox    # Declarative Proxmox VM deployment + lab lifecycle
│   ├── deploy-awx         # AWX deployment + management on Incus cluster
│   ├── awx-manifests/     # K8s manifests for AWX Operator + instance
│   ├── helpers/
│   │   ├── proxmox-screenshot  # VMID -> PNG console screenshot
│   │   └── proxmox-api         # Authenticated API calls (handles ! in token)
│   ├── lab-test           # Guided lab validation (12 test phases)
│   ├── observe-deploy     # Single-VM deploy with console screenshots
│   ├── proxmox.yaml       # Proxmox connection (gitignored)
│   ├── TESTING.md
│   └── examples/          # Example seed + Proxmox YAML files
├── env                    # PROXMOX_TOKEN_SECRET + PROXMOX_ROOT_PASSWORD (gitignored)
└── notes/                 # Reference guides (clustering, networking, OC, AWX, etc.)

Capabilities you have

Proxmox VM screenshots

Take console screenshots during deploys to see boot progress or errors:

incusos/helpers/proxmox-screenshot VMID [/tmp/output.png]

Use the Read tool on the PNG to view it. USE THIS PROACTIVELY during deploy scenarios to monitor boot progress, diagnose hangs, and verify installs.

Proxmox API calls

Make authenticated API calls (handles the ! in automation@pve!deploy):

incusos/helpers/proxmox-api GET /nodes/pve/qemu/900/status/current --json
incusos/helpers/proxmox-api GET /nodes/pve/status --json
incusos/helpers/proxmox-api POST /nodes/pve/qemu/900/status/stop

Live AWX job output

Capture output while a job is running (don't just poll status):

curl -sk http://192.168.102.161:30080/api/v2/jobs/{JOB_ID}/stdout/?format=txt \
  -H "Authorization: Bearer $AWX_TOKEN"

Critical safety rules

  • Proxmox SSH is screenshots-only. Full rules in .claude/rules/proxmox-ssh-rules.md.
  • Never hard-stop VMs during first boot -- corrupts TPM permanently.
  • Boot timeout is 180s -- do not reduce (sysext download takes 30-120s).
  • No force_reboot in seeds for Proxmox -- causes crontab race condition.
  • VMID ranges: 400-499 (OC), 800-809 (single), 900-939 (clusters).

Coding conventions

  • Shell: bash with set -euo pipefail
  • Arithmetic: var=$((var + 1)) not ((var++)) (set -e safety)
  • Colors: support NO_COLOR=1 and TERM=dumb; use setup_colors() pattern
  • Flags: both short (-d) and long (--defaults)
  • Defaults: useful behavior with zero flags
  • Dry run: all scripts support --dry-run
  • Cert detection: files on disk first (~/.config/incus/client.crt), CLI second
  • Errors: include actionable remediation steps
  • No hardcoded package managers: say "install the Incus client" with a link

Technical context loading

Detailed technical context loads automatically from .claude/rules/ based on which files are being edited:

Rule file Loads when editing
incusos-scripts.md incusos-iso, incusos-seed, incusos-proxmox, helpers
proxmox-deployment.md incusos-proxmox, observe-deploy, helpers, examples
clustering.md lab-test, incusos-proxmox, clustering/production guides
operations-center.md OC guide, incusos-proxmox, OC example configs
networking-storage.md networking, storage, migration, UTM guides
awx-integration.md ansible/, deploy-awx, awx-manifests, AWX guide
proxmox-ssh-rules.md Always loaded (no paths filter)
lab-infrastructure.md incusos-proxmox, lab-test, examples

For deep reference, see the guides in notes/.

Git workflow

  • Main branch: master
  • Remotes:
    • origin: ssh://git@192.168.1.200:2222/maarten/incus-contrib.git (private Gitea)
    • aether: _gitea@code.sovereignprivatecloud.nl:maarten/incus-contrib.git
  • Push to both remotes when committing
  • Development happens on feature branches