cto-legends · module specification · infrastructure · v0.1.3
legends-hetzner: Hetzner Cloud Stock Radar, CTO Sizing & Guarded Provisioning
Hetzner Cloud CLI toolkit with Cost-Optimized CX/CAX stock radar, Fractional CTO sizing, SHA-256 server plans, 10-check preflight, and VPS sniping.
GitHub Repository (https://github.com/avalonreset/legends-hetzner) · Handoff: cto-legends handoff legends-hetzner
legends-hetzner (v0.1.3) is a deterministic Python 3.11+ standard-library CLI wrapper and Fractional CTO capacity advisor built over the official hcloud CLI (shell=False, bounded subprocess timeouts, zero third-party pip dependencies, and no MCP server). It solves the core operational failure modes of agent-assisted Hetzner Cloud provisioning: choosing overpriced Regular Purpose (CPX) instances when Cost-Optimized (CX23-CX53 x86 and CAX11-CAX41 ARM64) capacity fluctuates in European datacenters (Falkenstein fsn1, Nuremberg nbg1, and Helsinki hel1), hitting Hetzner API rate limits with aggressive polling loops, or executing unreviewed server creations with mismatched SSH keys, deprecated images, or incompatible CPU architectures.
Architecturally, the module enforces a strict four-stage separation between live stock discovery (radar), offline immutable planning (server plan), 10-check live read-only preflight validation (server preflight), and single-invocation guarded execution (server create and server snipe). Every plan captures the active authentication context (planned_context), snapshots cloud-init user-data bytes with a SHA-256 digest, and computes a canonical sha256:<64hex> plan hash. Live provisioning requires both --approve and the matching --plan-hash, verifies post-creation state via API readback, and writes a token-redacted receipt that distinguishes confirmed creation from uncertain outcomes (uncertain_exists, uncertain_missing, uncertain_unknown).
Deterministic Execution Boundary
Why Raw Frontier LLM Prompts Cannot Replace Deterministic Execution
A raw Frontier LLM in a browser window or a static Markdown prompt file has no mechanism to inspect live Hetzner hypervisor stock, enrich older hcloud 1.61.0 JSON schemas with REST availability booleans, or prevent an autonomous agent from mutating cloud infrastructure on a hallucinated flag. Furthermore, Hetzner Cloud split server types into per-location availability on 2025-09-24, deprecated legacy shared-vCPU tiers on 2025-10-16, and removed the /v1/datacenters endpoints (HTTP 410 Gone) on 2026-10-01—changes that routinely cause raw LLMs to generate broken hcloud commands from stale pre-training weights.
- Two-Layer Capacity & REST Availability Enrichment: Hetzner's catalog indicator (locations[].available) is a cached boolean that lags behind the live placement scheduler (POST /v1/servers), and hcloud 1.61.0 omits available and category fields from CLI output entirely. legends-hetzner automatically enriches server-type catalogs via read-only REST calls to GET /v1/server_types and supports --allow-unavailable to test direct hypervisor placement only after all 9 non-capacity preflight checks pass.
- Cryptographic Plan Pinning & TOCTOU Elimination: server plan snapshots cloud-init user-data bytes (<= 32,768 bytes, verified #cloud-config or #!/ header) into the JSON plan alongside its user_data_sha256 digest and planned_context. At execution time, server create writes user-data to a private 0600 temporary file and re-verifies the SHA-256 digest before invoking hcloud, eliminating time-of-check to time-of-use (TOCTOU) file drift.
- Rate-Limit-Safe Jittered Sniping Bounds: Unbounded LLM shell loops hammer the Hetzner API and trigger HTTP 429 token throttling right as capacity opens. radar --watch and server snipe enforce a hard minimum --interval of 30 seconds (default 60s, consuming ~8% of the 3,600 req/hr quota), positive random --jitter (0..60s), and bounded --max-polls (1..120), aborting immediately on Poll 1 if any non-capacity check fails.
- XOR Authentication Hygiene & Subprocess Isolation: Every invocation enforces strict HCLOUD_TOKEN XOR --context NAME selection (exiting with code 2 AUTH_AMBIGUOUS if both are set or code 5 AUTH_MISSING if neither is present), strips HCLOUD_ENDPOINT, HCLOUD_HOST, and HCLOUD_DEBUG from child environments, and scrubs tokens from all stdout JSON and receipt files.
CLI Subcommands & Capability Surface
legends-hetzner radar [--germany-only] [--arch any|x86|arm] [--types cx43,cx33,cx23] [--watch] — Cost-Optimized Stock Radar & Fractional CTO Tier Ranking: Sweeps live cost_optimized server stock and project pricing across Falkenstein (fsn1), Nuremberg (nbg1), and Helsinki (hel1). Ranks available matches according to the Fractional CTO hardware ladder (cx43 8vCPU/16GB default -> cx33 4vCPU/8GB sweet spot -> cx23 2vCPU/4GB starter -> cx53 16vCPU/32GB consolidation ceiling -> cax31/cax21/cax11/cax41 Ampere Altra ARM64 alternatives) and emits in-place rescale rules.legends-hetzner server plan --name NAME --type TYPE --location LOC --image IMG --ssh-key KEY --out FILE — Offline SHA-256 Server Provisioning Plan: Generates an offline, reviewable JSON server plan without requiring cloud credentials. Records the target server type, location, image, required SSH keys (names or numeric IDs), labels, planned_context binding, timezone-aware ISO-8601 created_at timestamp, embedded cloud-init snapshot, and canonical sha256:<64hex> plan hash while refusing to overwrite existing files.legends-hetzner server preflight --plan FILE [--max-plan-age-hours 24] [--allow-unavailable] — 10-Check Read-Only Live Preflight Gate: Verifies plan integrity, context match, user-data digest, and plan age (default <= 24 hours) before executing 10 read-only checks against live Hetzner state: name_available, server_type_exists, location_exists, image_exists, ssh_keys_exist, location_supported, location_available, location_not_deprecated, image_not_deprecated, and arch_compatible. Passing --allow-unavailable bypasses only the cached catalog location_available=false flag while enforcing all 9 other checks.legends-hetzner server create --plan FILE --plan-hash sha256:... --approve [--dry-run] [--receipt FILE] — Single-Invocation Guarded Server Creation & Readback: Requires explicit --approve and a matching --plan-hash, validates that --receipt is writable before any network mutation, re-runs all live preflight checks, and executes at most one hcloud server create call (never retrying client-side). Confirms creation via live describe readback (matching server ID, name, type, location, and image) and writes a redacted JSON receipt.legends-hetzner server snipe --plan FILE --plan-hash sha256:... --approve [--interval 60] [--jitter 10] [--max-polls 30] — Rate-Limit-Safe Capacity Sniper: Polls read-only preflight at bounded, jittered intervals (--interval >= 30s) while scarce CX43/CX33/CX23 capacity reports unavailable. Fails fast on Poll 1 (exit 3) without sleeping if any non-capacity check fails, makes zero writes while waiting, and fires exactly one guarded server create call the moment confirmed location_available=true stock opens.legends-hetzner doctor [--live] | inventory | catalog | resources — Environment Readiness, Inventory & Attachable Knowledge Pack: Separates offline Python 3.11+ and hcloud binary verification (doctor) from live read-only location probing (doctor --live), server estate auditing (inventory), and catalog inspection (catalog --kind all|server-types|locations|images|ssh-keys). Also exposes a 16-file legends.knowledge-pack/v1 operations library and Ubuntu 24.04 minimal cloud-init baseline via resources.
Raw Frontier LLM vs. legends-hetzner Execution Matrix
- Hardware Sizing & Region Selection: Raw LLM (Hallucinates deprecated CPX11/CX21 SKU names, provisions 2x-cost CPX servers in US/EU without checking Cost-Optimized CX43/CX33/CX23 tiers, or mixes ARM64 CAX with x86 rescale plans.) vs. Module (Codifies the Fractional CTO tier ladder (cx43 -> cx33 -> cx23 -> cx53) across fsn1, nbg1, and hel1, enforcing same-location, same-architecture, and non-shrinking-disk rescale rules.) — legends-hetzner radar JSON output with live project pricing, available_matches, recommended_match, and cto_doctrine.
- Pre-Provisioning Validation: Raw LLM (Runs hcloud server create directly in a shell command, failing mid-flight on deprecated images (e.g., Debian 11/Fedora 42), removed --datacenter flags, or missing SSH keys.) vs. Module (Enforces 10 deterministic read-only preflight checks against live catalog arrays and rejects plans older than 24 hours or tampered JSON payloads (PLAN_TAMPERED, exit 2).) — legends-hetzner server preflight returns {passed: true, checks: [...], failures: []} or blocks with exit code 3.
- Scarce Capacity Sniping: Raw LLM (Writes naive while-true sleep-1 bash loops that exhaust the 3,600 req/hr Hetzner API quota or accidentally spin up multiple duplicate VPS instances on retry.) vs. Module (Enforces --interval >= 30s, random positive jitter (0..60s), bounded --max-polls (1..120), Poll-1 non-capacity fail-fast, and at most one hcloud server create execution.) — Redacted receipt JSON recording snipe poll metadata, plan_hash, readback verification, and exact status.
- Post-Write State & Error Honesty: Raw LLM (Assumes a CLI timeout or non-zero exit means no server was billed, prompting blind retries that leave orphaned billable instances running.) vs. Module (Never retries a create call; performs immediate post-create describe readback and classifies ambiguous states as uncertain_exists, uncertain_missing, or uncertain_unknown (exit 4).) — Exit code contract (0..5) and mandatory receipt inspection before any subsequent retry.
- Credential & Context Isolation: Raw LLM (Inlines HCLOUD_TOKEN in shell commands, leaks bearer strings into chat transcripts, or mixes ambient env tokens with named hcloud contexts.) vs. Module (Enforces HCLOUD_TOKEN XOR --context NAME, binds planned_context into the SHA-256 plan, strips custom endpoint/debug env vars, and scrubs tokens from all outputs.) — AUTH_AMBIGUOUS (exit 2), PLAN_CONTEXT_MISMATCH (exit 2), and automated release redaction unit tests.
Explicit Safety Boundaries & Exclusions
Operator FAQ
- Why does legends-hetzner prioritize CX43, CX33, and CX23 in fsn1, nbg1, and hel1 over CPX tiers?
- Hetzner Cloud's Cost-Optimized line (CX23-CX53 x86 and CAX11-CAX41 ARM64), available exclusively in Falkenstein (fsn1), Nuremberg (nbg1), and Helsinki (hel1), delivers more than double the RAM and vCPU per dollar compared to Regular Purpose (CPX) plans. Prioritizing x86 CX tiers (led by CX43 at 8 vCPU / 16 GB RAM / 160 GB NVMe) guarantees 100% linux/amd64 binary and container compatibility while preserving a clean in-place rescale path up the CX23 -> CX33 -> CX43 -> CX53 ladder.
- What is the difference between catalog availability and --allow-unavailable direct API placement?
- Hetzner's GET /v1/server_types endpoint exposes a cached locations[].available boolean that grays out tiers in the Web Console UI, whereas POST /v1/servers (invoked by hcloud server create) queries the live hypervisor placement scheduler directly. Passing --allow-unavailable to server preflight or server create still enforces all 9 non-capacity safety checks (name, type, location, image, SSH keys, location support, non-deprecation, and CPU architecture) while allowing a single guarded placement test against the live scheduler.
- How does server snipe protect my Hetzner account from rate limits and duplicate servers?
- server snipe rejects any --interval below 30 seconds (exit 2 RADAR_INTERVAL_TOO_LOW), adds positive random jitter (0..60s) to prevent synchronized polling spikes, bounds total attempts (--max-polls 1..120), and aborts immediately on Poll 1 (exit 3) if any non-capacity check fails. It performs zero writes while location_available is false and executes at most one hcloud server create invocation the moment confirmed capacity opens.
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.