vm-cloud/README.md

vm-cloud

Hetzner Cloud operator CLI (vmc) with audit-ready receipts, plan/apply safety, and a tamper-evident local ledger.

Quick start

1. Install deps

npm install

2. Configure Hetzner token

Create ~/.env (recommended) or a project .env with:

HCLOUD_TOKEN=xxx

3. Run

# dev (runs TS directly)
npm run dev -- --help

# or
./bin/vmc --help

Commands

Read-only

vmc servers list
vmc snapshot servers
vmc research new "Hetzner Baseline YYYY-MM-DD"
vmc research append --from outputs/hetzner/servers-*.json

Mutations (safe)

All mutations:

• resolve server by id/name (exact first, partial only when unambiguous)
• require confirmation (or --yes)
• write a receipt to outputs/receipts/
• acquire a per-server lock (~/.cache/vm-cloud/locks/<id>.lock) to prevent concurrent ops

Plan (dry-run)

vmc servers labels <name|id> env=prod owner=ops --dry-run
# => outputs/plans/plan-*.json with SHA256+BLAKE3

Apply

vmc apply --plan outputs/plans/plan-*.json --yes --reason "change ticket / intent"

Ledger + verification

vmc verify receipt outputs/receipts/<file>.json --head --plan --sig
vmc verify chain --head --sig

Signing

vmc keygen
vmc sign receipt outputs/receipts/<file>.json

Merkle receipts

vmc merkle receipts
# => outputs/ledger/merkle-*.json (root over receipt blake3 chain)

Safety notes

• Never commit .env or outputs/ or node_modules/ (see .gitignore).
• Rotate any leaked tokens immediately.