cto-legends · module specification · infrastructure · v0.2.1
legends-coolify: Self-Hosted Coolify PaaS Inspection, Env Hygiene & Backup Auditing
Read-only Coolify PaaS CLI for self-hosted app inventory, secret-free env key inspection, backup schedule audits, deployment history, and runbooks.
GitHub Repository (https://github.com/avalonreset/legends-coolify) · Handoff: cto-legends handoff legends-coolify
legends-coolify (v0.2.1) is a zero-dependency Python 3.11+ standard-library inspection CLI and source-cited operational runbook suite for self-hosted Coolify PaaS estates. When AI coding agents interact directly with a live Coolify API via raw curl commands or generic HTTP wrappers, they routinely dump plaintext environment secrets into LLM context windows, mistake a running Docker container status for verified application health, or treat an enabled backup schedule as proof of a restorable database backup. legends-coolify eliminates those failure modes by enforcing a strictly read-only, schema-validated inspection boundary.
Architecturally, the module's HTTP transport (legends_coolify.client.Client) locks every request to a compiled regex allowlist of GET-only endpoints (/api/health, /api/v1/version, /api/v1/applications, /api/v1/databases, /api/v1/services, /api/v1/servers, /api/v1/projects, and bounded UUID detail routes), requires a clean HTTPS origin (no credentials, path, query, or fragment), disables HTTP redirects (NoRedirect), ignores ambient proxy environment variables (ProxyHandler({})), caps responses at 8 MiB, and scrubs the active COOLIFY_API_TOKEN from every stdout and stderr payload.
Deterministic Execution Boundary
Why Raw Frontier LLM Prompts Cannot Replace Deterministic Execution
Giving a raw Frontier LLM a Coolify API token and asking it to inspect your self-hosted platform via ad-hoc curl or Python snippets exposes production secrets and produces silent inventory errors. Coolify's /applications/{uuid}/envs endpoint returns raw secret values alongside variable keys, its /deployments endpoints include verbose build logs that can leak credentials, and paginated or malformed API responses can trick a naive script into reporting zero resources as a healthy estate.
- Structural Secret-Value & Build-Log Exclusion: In env_summary(), legends-coolify extracts only the variable key and boolean lifecycle flags (is_preview, is_runtime, is_buildtime)—never emitting variable values even for keys marked public. Similarly, deployment_summary() whitelists only UUID, status, normalized outcome, commit SHA, commit message, and timestamps, stripping raw build logs before output.
- Hardened HTTPS-Only No-Redirect Transport: The custom urllib opener combines ProxyHandler({}) and a NoRedirect handler that refuses all HTTP 3xx redirects, ensuring Bearer tokens are never silently forwarded across protocol downgrades, untrusted reverse-proxy redirects, or ambient system proxies.
- Strict Pagination & Envelope Integrity Checks: records() and deployment_window() validate response shapes before returning data: if a list endpoint returns a paginated wrapper or unexpected keys, or if /deployments/applications/{uuid} returns a window inconsistent with total_count, skip (0..100000), and take (1..50), the CLI raises CoolifyError (exit 1) rather than reporting a partial list as complete.
- O_EXCL Atomic Private Report Creation: When writing reports via --out PATH, preflight_out() and write_report() reject symlinks before any network call and open the destination with os.O_WRONLY | os.O_CREAT | os.O_EXCL | O_NOFOLLOW (mode 0600), verifying inode/device identity on cleanup so existing files are never overwritten or followed through links.
CLI Subcommands & Capability Surface
legends-coolify doctor [--live] [--out PATH] — Dual-Gate Live Readiness Verification: Offline doctor verifies Python 3.11+ runtime readiness and cryptographic integrity of all manifest-pinned package resources without network access. Running doctor --live requires both an OK response from /api/health and an authenticated, schema-valid UUID resource list from /api/v1/applications (plus optional /api/v1/version), proving real API token scope rather than mere web-server reachability.legends-coolify inventory | health [--out PATH] — Multi-Kind Estate Inventory & Partial-Failure Honesty: inventory queries all five Coolify resource collections (applications, databases, projects, servers, services), while health targets runtime workloads (applications, databases, services). Both parse compound container states (e.g., running:healthy vs exited:unhealthy) into structured booleans, explicitly report per-endpoint collection errors as status: partial (exit 1), and warn that container state does not prove business-level application health.legends-coolify env --uuid APPLICATION_UUID [--out PATH] — Zero-Value Environment Variable Hygiene Audit: Inspects an application's configured environment variables via /api/v1/applications/{uuid}/envs and emits values_included: false with each variable's key, is_preview, is_runtime, and is_buildtime flags. Allows coding agents to audit missing configuration keys or build-time vs. runtime scoping without exposing production API keys or database passwords.legends-coolify backups --uuid DATABASE_UUID [--out PATH] — Database Backup Schedule & Restore-Proof Separation: Reads configured backup schedules for a target database (/api/v1/databases/{uuid}/backups), reporting schedule UUID, enabled state, cron frequency, and save_s3 status. Always sets execution_success_verified: false and restore_verified: false in the JSON output so agents never conflate a cron schedule with a verified backup rehearsal.legends-coolify deployments [--uuid APP_UUID --limit 10 --skip 0 | --deployment-uuid DEPLOY_UUID] — Running Queue & Bounded Deployment History Windows: Supports three distinct read-only inspection modes: active queue inspection (/api/v1/deployments), single deployment verification (--deployment-uuid with strict response UUID matching), and paginated application history (--uuid with bounded --limit 1..50 and --skip 0..100000, returning total_count, returned_count, and has_more).legends-coolify plan --uuid APP_UUID | resources — Advisory Deployment Checklist & Empire Knowledge Pack: plan verifies the target application UUID against live state and emits an unexecuted (executed: false) 7-point Fractional CTO deployment and rollback checklist covering immutable image/commit pinning, restorable database and persistent-volume backups, forward/backward schema compatibility, and single-writer migration discipline. resources resolves absolute paths to the agent recipe and the versioned knowledge/coolify/pack.json library.
Raw Frontier LLM vs. legends-coolify Execution Matrix
- Environment Variable Inspection: Raw LLM (Calls GET /api/v1/applications/{uuid}/envs and prints the full JSON response, leaking database URLs, JWT secrets, and third-party API keys into the conversation transcript.) vs. Module (Strips all secret values in code (env_summary), outputting only variable key names and is_preview / is_runtime / is_buildtime booleans with values_included: false.) — JSON schema check and unit tests proving secret values and bearer tokens are never emitted on stdout or stderr.
- Health & Backup Interpretation: Raw LLM (Sees container status 'running' or backup schedule 'enabled: true' and tells the operator that production is healthy and backups are safe.) vs. Module (Separates container status from application health (application_health_verified: false) and backup schedule existence from restore proof (restore_verified: false).) — Explicit boolean flags embedded in every doctor --live, health, and backups JSON payload.
- API Surface & Mutation Safety: Raw LLM (Can issue POST/PATCH/DELETE calls to restart services, trigger unintended redeployments, or follow HTTP redirects that leak Bearer headers.) vs. Module (Hardcodes GET-only requests against a strict regex allowlist (allowed_path), blocks all query parameters except bounded deployment history skip/take, and disables redirects/proxies.) — Client.get() raises CoolifyError before network I/O on any non-allowlisted route or parameter.
- Incomplete Collection Handling: Raw LLM (Treats HTTP 403/404 or truncated pagination on one resource type as an empty array, producing false-clean infrastructure audits.) vs. Module (Records per-endpoint failures in errors{}, sets report status to 'partial', exits with code 1, and rejects inconsistent deployment history windows.) — Non-zero exit code (1) on partial inventory or malformed API envelopes.
- Private Report Persistence: Raw LLM (Redirects output with > report.json, silently clobbering prior audit snapshots or writing sensitive UUIDs inside tracked repository folders.) vs. Module (Creates reports exclusively via O_CREAT | O_EXCL | O_NOFOLLOW (0600 permissions) and refuses existing paths or symlinks before network access.) — preflight_out() and write_report() inode-verified atomic file creation.
Explicit Safety Boundaries & Exclusions
Operator FAQ
- Why is legends-coolify strictly read-only instead of wrapping deployment or restart endpoints?
- Self-hosted PaaS mutations carry high blast radius—restarting a stateful service, triggering an unreviewed build, or rolling back an application container after an irreversible database schema migration can cause immediate downtime. legends-coolify gives AI agents a safe, repeatable inspection and pre-deployment planning procedure while reserving actual mutations for Coolify's official UI, CLI, or API under explicit operator execution.
- How does legends-coolify prevent production secrets from leaking into AI agent transcripts?
- First, the CLI never accepts tokens on the command line and scrubs the active COOLIFY_API_TOKEN from all stdout and stderr JSON. Second, the env subcommand strips all variable values inside Python before formatting output (values_included: false), returning only key names and boolean scope flags (is_preview, is_runtime, is_buildtime). Third, deployment summaries exclude raw build logs and HTTP error handlers omit upstream response bodies.
- Why does legends-coolify refuse HTTP URLs, redirects, and ambient proxy variables?
- Sending a Coolify Bearer token over plaintext HTTP or allowing an HTTP client to follow a 301/302 redirect across origins can expose credentials to an unverified endpoint. Client initializes urllib with ProxyHandler({}) and a custom NoRedirect handler, enforcing a clean https:// origin with full TLS certificate verification on every call.
All 19 CTO Legends Packages (1 Router + 18 Modules)
cto-legends (v0.2.5) — Single-skill Python CLI router and isolated environment manager that resolves 18 SHA-256-pinned modules on demand without MCP startup bloat.legends-empire (v0.3.2) — SHA-256 Markdown knowledge foundation with recoverable NTFS and POSIX transactions, .raw/ evidence quarantine, and read-only vault stewardship.legends-hetzner (v0.1.3) — Hetzner Cloud CLI toolkit with Cost-Optimized CX/CAX stock radar, Fractional CTO sizing, SHA-256 server plans, 10-check preflight, and VPS sniping.legends-coolify (v0.2.1) — Read-only Coolify PaaS CLI for self-hosted app inventory, secret-free env key inspection, backup schedule audits, deployment history, and runbooks.legends-cloudflare (v0.1.1) — Zero-dependency Cloudflare DNS CLI enforcing SHA-256 preview-first single-record upserts, exact-ID deletes, setting preservation, and API readback.legends-astro (v0.2.1) — Astro v7 migration CLI that extracts HTML and WordPress source contracts, scaffolds Content Layer collections, and verifies dist/ build parity.legends-gohighlevel (v0.3.0) — Python 3.11+ GoHighLevel CLI for API v2 CRM, Workflows v3, Agent Studio AI, and 5-layer agency RBAC/1.05x rebilling with SHA-256 preview and readback.legends-geogrid (v0.2.2) — Circular-lattice Google Maps rank tracker, GBP name-stuffing audit workbench, and 18-page vector PDF strategy studio for coding agents.legends-dataforseo (v0.1.6) — Zero-dependency Python API and CLI for DataForSEO v3 SERP, Maps, GBP, and keyword research with offline previews and evidence banking.legends-firecrawl (v0.3.2) — Agent-first CLI wrapper (lfc and lax) for official Firecrawl web extraction and Alexandria queries with full local JSON evidence banking.legends-github (v0.2.1) — Deterministic Python CLI for GitHub repository audits, DataForSEO keyword and SERP demand, 20-topic synthesis, non-destructive READMEs, and OG checks.legends-grant (v0.3.0) — Standard-library Python CLI for 56-jurisdiction US grant discovery, SQLite evidence banking, qualification checks, and proposal verification.legends-jev (v0.2.1) — Zero-dependency Python CLI for TypeSafe Jev 1.14 optical recognition (OCR), storefront signage checks, pixel bounding boxes, and typed UI decisions.legends-obs (v0.1.2) — Guarded Windows OBS Studio CLI over WebSocket v5 for hardware encoder planning, pre-mutation rollback snapshots, and FFprobe-verified recording canaries.legends-captions (v0.1.1) — Deterministic video caption QA and ASS rendering CLI with contextual ASR repair, NeMo Forced Aligner word timing, spoken acronym locks, and proof frames.legends-yt-dlp (v0.1.2) — Paced yt-dlp orchestration CLI with SHA-256 binary verification, channel item ledgers, opt-in Mullvad Lockdown guards, and Parakeet/NFA word-level search.legends-stable-audio-3 (v0.1.3) — Hardware-aware Stable Audio 3 CLI for VRAM-calibrated local Medium batches, guarded Large REST jobs, cue-trimmed streaming mixes, and float WAV mastering.legends-hyperyap (v0.1.1) — Offline desktop dictation runtime running INT8 ONNX NVIDIA Parakeet TDT 0.6B v2 locally with CUDA-first inference, active-window paste, and terminal hooks.legends-ambient-intelligence (v0.1.1) — Passive audio pipeline CLI for SHA-256 deduplicated USB recorder ingest, offline Whisper/NeMo Parakeet ASR, rollover recovery, and vault distillation.