legends-hetzner

skill
Guvenlik Denetimi
Uyari
Health Uyari
  • License — License: MIT
  • Description — Repository has a description
  • Active repo — Last push 0 days ago
  • Low visibility — Only 6 GitHub stars
Code Gecti
  • Code scan — Scanned 12 files during light audit, no dangerous patterns found
Permissions Gecti
  • Permissions — No dangerous permissions requested

Bu listing icin henuz AI raporu yok.

SUMMARY

legends-hetzner: Hetzner Cloud & VPS stock radar (CX43/CX33/CX23), Fractional CTO sizing, 10-check preflight & hash-locked provisioning CLI for coding agents

README.md

legends-hetzner

release
checks
python
hcloud
license

Hetzner Cloud and VPS stock radar (CX43/CX33/CX23 and CAX), Fractional CTO sizing advisor, 10-check read-only preflight gate, SHA-256 hash-locked provisioning CLI, and rate-limit-safe capacity sniper for coding agents.

Agent Handoff

Install or update legends-hetzner via cto-legends (https://github.com/avalonreset/cto-legends): run `cto-legends install legends-hetzner --apply`, then `cto-legends handoff legends-hetzner` and follow the returned JSON recipe to verify `legends-hetzner`.

Three Pillars: Cost-Optimized stock radar, 10-check preflight & sizing, Hash-locked create & snipe

Why legends-hetzner exists

Most agent-driven cloud setups treat server provisioning as ad-hoc shell improvisation:

  1. Defaulting to 2x pricier tiers or retired instance names: Without live hypervisor stock data, coding agents guess retired Hetzner instance names from training data or fall back to Regular Purpose (CPX) servers that cost more than twice as much per GB of RAM when Cost-Optimized CX43, CX33, CX23, or CAX tiers are open in Germany (fsn1, nbg1) or Finland (hel1).
  2. Failing mid-create or spinning up duplicate billable servers: Running raw hcloud server create commands without an immutable plan or read-only preflight fails midway on missing SSH keys, deprecated OS images, CPU architecture mismatches, or removed --datacenter flags. Worse, when a network call times out, an unconstrained agent retries the command and creates duplicate billable VPS instances.
  3. Triggering API rate-limit bans while polling sold-out stock: When scarce Cost-Optimized capacity is temporarily out of stock, improvised 1-second shell loops hammer the Hetzner Cloud API and exhaust the 3,600 requests/hour quota right before capacity opens.

legends-hetzner wraps the official hcloud CLI in a Python 3.11+ standard-library runtime (zero third-party pip dependencies, no PowerShell dependency, and no ambient daemon) that separates live discovery from infrastructure writes. Every server creation is locked behind an offline sha256:<64hex> plan, verified by 10 read-only preflight checks, executed in at most one guarded hcloud invocation with immediate readback verification, and paired with an optional 16-file operations knowledge pack for legends-empire.

Ask in plain english

Once cto-legends is installed, you ask your coding agent in plain english. It sweeps live European stock, writes an immutable SHA-256 server plan, verifies all 10 read-only preflight checks, and provisions or snipes capacity with a redacted readback receipt:

Say the job in plain words

Architecture: live CX stock radar, 10-check preflight, and hash-locked sniping

How live CX stock radar, 10-check preflight, and hash-locked sniping work

1. Cost-Optimized stock radar and Fractional CTO sizing doctrine (CX vs CAX)

Hetzner Cloud's Cost-Optimized (cost_optimized) line is hosted in three European locations: Falkenstein (fsn1, Germany), Nuremberg (nbg1, Germany), and Helsinki (hel1, Finland). Regular Purpose (CPX) and General Purpose (CCX) lines cost more than twice as much per GB of RAM. When running against older hcloud binaries (such as 1.61.0) that omit locations[].available and category from CLI JSON output, legends-hetzner automatically enriches server-type catalogs via hardened read-only REST (GET /v1/server_types with redirects disabled and ambient proxies ignored).

Priority Server Tier Arch Specs (vCPU / RAM / NVMe) CTO Role & Sizing Guidance
1 (Default) cx43 x86 8 vCPU · 16 GB · 160 GB Ideal Fractional CTO Default. Best price-to-headroom balance for a consolidated single-server stack (legends-coolify, reverse proxy, websites, databases, and workers) with 100% linux/amd64 compatibility.
2 (Sweet Spot) cx33 x86 4 vCPU · 8 GB · 80 GB Budget Sweet Spot. Delivers 2x the CPU and RAM of a cpx22 fallback at less than half the monthly cost; supports clean in-place rescale from an 80 GB cpx22 or 40 GB cx23 in the same location.
3 (Starter) cx23 x86 2 vCPU · 4 GB · 40 GB Entry Starter Seat. Sufficient for a lightweight static or staging stack (configure a 4 GB swapfile and NODE_OPTIONS=--max-old-space-size=2048 to prevent Node build OOMs) while waiting to rescale up to cx33 or cx43.
4 (Ceiling) cx53 x86 16 vCPU · 32 GB · 320 GB Single-Box Consolidation Ceiling. Consolidating onto one cx43 or cx53 is strongly preferred over running multiple small Hetzner VPS instances.
5-8 (ARM64) cax31 / cax21 / cax11 / cax41 arm 2-16 vCPU · 4-32 GB · 40-320 GB Ampere Altra ARM64 Alternatives. Non-hyperthreaded ARM64 cores when x86 tiers are unavailable and every workload supports linux/arm64 (cannot rescale in-place into x86 CX tiers).

2. SHA-256 server plans and the 10-check preflight gate

Before any server can be created, legends-hetzner server plan writes an offline JSON plan pinned by a canonical sha256:<64hex> content hash, binding your target --context (or HCLOUD_TOKEN mode), server tier, location, OS image, SSH keys, and cloud-init user-data digest (refusing symlinks and existing output files fail-closed). legends-hetzner server preflight then verifies 10 read-only checks against live project state:

Surface legends-hetzner Command What It Verifies or Executes
Environment Readiness doctor [--live] Distinguishes offline Python 3.11+ and hcloud binary readiness from a live read-only Hetzner Cloud location probe.
Inventory & Catalog inventory, catalog Audits existing servers and live server-types, locations, images, and ssh-keys with automatic secret token redaction.
Stock Radar & Watch radar [--watch] Sweeps live cost_optimized capacity across fsn1, nbg1, and hel1, ranks open tiers by Fractional CTO priority, and optionally watches at jittered intervals (>= 30s).
Immutable Plan & 10-Check Gate server plan, server preflight Verifies 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.
1-Shot Create & Capacity Sniper server create, server snipe Requires explicit --approve and matching --plan-hash, polls sold-out tiers safely (--interval >= 30s, default 60s + jitter), executes at most one create call, verifies via live readback, and writes a redacted receipt.
Packaged Runbooks resources Returns absolute paths to the installed agent recipe, Ubuntu 24.04 cloud-init baseline, and 16-file legends.knowledge-pack/v1 operations library.

3. Direct placement tests (--allow-unavailable) and rate-limit-safe sniping (server snipe)

  • Cached catalog flag vs live placement scheduler: Hetzner's catalog availability flag (available=false) is a cached indicator that grays out tiers in the Web Console UI, while the live placement scheduler behind hcloud server create (POST /v1/servers) evaluates real-time hypervisor capacity at creation time. When all 9 non-capacity preflight checks pass, you can test direct API placement with --allow-unavailable (previewing first with --dry-run).
  • Rate-limit-safe capacity sniper: When live placement reports resource_unavailable, server snipe enforces a strict 30-second minimum polling floor (--interval 30..3600, default 60s) with positive random jitter (--jitter 0..60, default 10s) and bounded --max-polls (1..120, default 30), consuming roughly 8% of Hetzner's hourly API quota and aborting immediately on Poll 1 if any non-capacity check fails.

Ad-hoc cloud commands vs legends-hetzner

Comparison: Ad-hoc cloud commands & console clicks vs Hash-locked VPS engine // legends-hetzner

Quick start

# 1. Configure a named hcloud context (or export HCLOUD_TOKEN; never combine both)
hcloud context create my-project
legends-hetzner --context my-project doctor --live
legends-hetzner --context my-project inventory

# 2. Sweep live Cost-Optimized x86 stock and Fractional CTO recommendations
legends-hetzner --context my-project radar --germany-only --types cx43,cx33,cx23
legends-hetzner --context my-project catalog --kind ssh-keys

# 3. Create an immutable, SHA-256 hash-pinned server plan offline
legends-hetzner --context my-project server plan \
  --name example-app --type cx43 --location fsn1 \
  --image ubuntu-24.04 --ssh-key my-key --out ./server-plan.json

# 4. Run the 10-check read-only preflight gate
legends-hetzner --context my-project server preflight --plan ./server-plan.json

# 5. Preview guarded creation (or pass --allow-unavailable when catalog availability lags)
legends-hetzner --context my-project server create \
  --plan ./server-plan.json --plan-hash sha256:REVIEWED_HASH \
  --approve --dry-run --receipt ./receipt.json

# 6. Poll sold-out capacity at rate-limit-safe jittered intervals (>= 30s)
legends-hetzner --context my-project server snipe \
  --plan ./server-plan.json --plan-hash sha256:REVIEWED_HASH \
  --approve --dry-run --receipt ./snipe-receipt.json \
  --interval 60 --jitter 10 --max-polls 30

Reference

Exit-code contract, receipt statuses, and Empire knowledge shelf

All commands emit structured JSON on stdout and sanitized diagnostics on stderr (see docs/CLI-CONTRACT.json):

Exit Code Constant Meaning
0 OK Command succeeded (doctor, inventory, catalog, radar, server plan, server preflight, server create, server snipe, resources).
1 LOCAL_OR_CLI_ERROR Missing hcloud binary, non-zero hcloud exit on read-only probes, timeout, or invalid JSON output.
2 PLAN_OR_USAGE_ERROR Invalid CLI flags, tampered or stale plan file (> 24h), hash mismatch, missing --approve, ambiguous auth, or unsafe poll interval (< 30s).
3 PREFLIGHT_BLOCKED One or more live preflight checks failed (name_available, location_available, arch_compatible, etc.), or a --watch / snipe window completed without open stock.
4 CREATE_OR_UNCERTAIN hcloud server create failed or returned an ambiguous result (uncertain_exists, uncertain_missing, uncertain_unknown); inspect the receipt and readback before retrying.
5 AUTH_MISSING Live provider command invoked without HCLOUD_TOKEN or --context NAME.

The module also ships a 16-file legends.knowledge-pack/v1 operations library under knowledge/hetzner/ (cto-sizing-and-sniping.md, preflight.md, ssh-bootstrap.md, coolify-boundary.md, backups-restore.md, troubleshooting.md, and audit templates). Its suggested attachment path in a selected legends-empire vault is wiki/library/legends-hetzner/hetzner. Installing legends-hetzner never modifies a vault automatically; see docs/KNOWLEDGE-PACK.md and knowledge/hetzner/vault/index.md.

Agent setup (via cto-legends) and standalone installation

Agent setup (via cto-legends)

Part of cto-legends. cto-legends is the single registered router skill; this repository vendors a byte-exact copy at skills/cto-legends/SKILL.md.

Run cto-legends handoff legends-hetzner and read the returned installed recipe and task-readiness checks. If the module is missing, preview setup with cto-legends install legends-hetzner, perform the authorized setup, then repeat the handoff. Use cto-legends check-updates to compare your installed version with the catalog and published release. See docs/AGENT-RECIPE.md for the standalone recipe.

The separate official hcloud CLI must be installed using its documented Windows, macOS, or Linux instructions. This module never silently installs or upgrades external binaries.

python -m pip install -e .
legends-hetzner doctor
legends-hetzner resources
Repository layout, verification, and scope limits
Operator / Coding Agent
  -> legends-hetzner radar (live CX/CAX stock matrix + REST enrichment + CTO tier ranking)
  -> legends-hetzner server plan (offline JSON plan + SHA-256 content hash)
  -> legends-hetzner server preflight (10 live read-only safety checks)
  -> legends-hetzner server create / snipe (single guarded hcloud invocation + readback receipt)
python -m unittest discover -s tests -v
python scripts/check_release.py --strict

This is a focused Hetzner Cloud server toolkit, not a wrapper for every Hetzner product. It does not administer Hetzner Robot bare-metal servers, manage billing, modify DNS records (use legends-cloudflare), inspect Coolify applications (use legends-coolify), or replace full Terraform/OpenTofu state reconciliation.

Contributing, security, and license

See CONTRIBUTING.md, CODE_OF_CONDUCT.md, SECURITY.md, SUPPORT.md, PRIVACY.md, CITATION.cff, and THIRD_PARTY_NOTICES.md.

Independent software by Benjamin Samar (Avalon Reset), released under the MIT License. Not affiliated with or endorsed by Hetzner Online GmbH.

Message Avalon Reset

GitHub Star List: The complete cto-legends collection on one page. Bookmark or star the router and every module from a single GitHub list.

Specification & benchmarks on cto-legends.com:

Yorumlar (0)

Sonuc bulunamadi