felhom.eu/documentation/pilot/PETI-tester-agreement.md

Felhom pilot — tester agreement (Peti)

The terms of the first external pilot: what Peti runs, what Felhom can and cannot do on his hardware, the honest limitations of the pilot, and his exit rights. Lives at felhom.eu/documentation/pilot/PETI-tester-agreement.md. Created 2026-07-09 (GL-7). Operator: Viktor. Tester: Peti.

This is the operator-side record of the bargain. The points in §3, §4 and §5 are what Peti is told and asked to acknowledge at onboarding; that conversation happens in Hungarian — this document is the English source of truth those points are drawn from.

---

1. What the pilot is

Peti runs Felhom as a guest on his own Proxmox server — the BYO-host model. He stays root on his hardware; Felhom is one LXC guest plus a narrow, non-root management footprint. This is not the appliance model (Felhom-owned hardware); the whole point of the pilot is to prove the BYO trust boundary on someone else's box.

Peti's box: an 80-core / 128 GB rack server already running his own workloads. The Felhom guest is capped at 12 cores / 32768 MiB (noisy-neighbour containment — the only thing standing between Felhom and his other guests, since we do not control the host).

Name: sajatfelhom.hu. The existing Cloudflare tunnel for that domain must be re-pointed at the new guest as part of onboarding (§7).

---

2. What runs on Peti's box

Component	Footprint	Privilege
Felhom guest (LXC)	one container in the felhom pool, capped 12c/32 GB	unprivileged LXC
Host agent	one binary + systemd unit on the host	non-root (felhom-agent user)
Sudoers allowlist	/etc/sudoers.d/felhom-agent	narrow, pct/vzdump/mount verbs only
PVE API token	scoped to the felhom pool + named storages only	Pool.*/VM.*/Datastore.* on those objects
Local API	binds vmbr0:8443 on his LAN	TLS + per-guest bearer token

Nothing else. In particular, on a BYO host the installer does not touch these appliance-only mechanisms:

• Break-glass is OFF. Felhom never runs chpasswd on root@pam and never vaults a host root credential to the hub. Peti's root password is his own and is never seen or changed.
• Out-of-band operator SSH is OFF (oob.enabled=false). Felhom opens no operator tunnel into his box.
• WireGuard tunnel DISCLOSURE (changed 2026-07-12, DR-tier-by-default decision 5): the install DOES enable an outbound WireGuard tunnel (wg_tunnel.enabled=true) — it is base infrastructure like the Cloudflare tunnel, carries the offsite/DR backup traffic, and is the future out-of-band management transport. It is strictly box-dials-out (no Felhom-side connection reaches back into the network; the peer has no inbound route), it is listed in the installer's typed host-mutation acknowledgement, and it can be disabled per-customer hub-side on request — with the honest consequence that the DR tier and offsite backup stop working without it.

These are asserted at install time (the byo config-write asserts oob/lan_resolver are off before the install is marked complete — wg_tunnel moved to the disclosed-default list in installer v1.15.0) and were live-validated on the demo host during the GL-6 drill.

---

3. What Felhom can and cannot do (the trust boundary)

Can: provision and manage its own guest, run backups of its own guest to the storages named in its ACL, report guest/host health to the hub, and — only with an operator signing key that Peti's box has pinned — apply a signed agent self-update. Every host action goes through the narrow sudoers allowlist, scoped to the felhom pool.

Cannot: read or modify Peti's other guests (the pool-scoped token is refused outside felhom); change his root password; open an inbound operator session; touch his DNS service (see F6 below); or reach storages outside its named ACL. The local API authorises every request strictly against the calling token's own guest — a token minted for one guest is refused for any other (localapi/server.go; spot-verified).

---

4. Honest limitations of the pilot

This is the data-sovereignty pitch stated plainly, not hidden:

• No offsite backup yet (local-only). Backups stay on Peti's own hardware. A dead or stolen box, or a dead backup drive with no second local target, loses data. The offsite tier (Tier-1/Tier-2 split + production WG endpoint) is a fast-follow, not part of this pilot. Local backups being green is asserted at onboarding (§7).
• Backups live on a physically removable drive on his own hardware (F2). This is the flip side of "no offsite" and is the sovereignty guarantee: his data never leaves his premises, and he can physically remove the drive. It also means the resilience of the backup is exactly the resilience of that one local drive/pool.
• The felhom pool membership is asserted at bring-up only, not continuously healed (F7). If something outside Felhom moves the guest out of the pool while it runs, Felhom won't silently re-grab it; a re-run (or --adopt-pool) repairs it. No autonomous host-level reassertion.
• Port 53 must be free on his host (F6). Felhom's guest DNS wants :53. If Peti already runs a DNS service there, the installer refuses and tells him — it will not stop, mask, or reconfigure a DNS service on a host Felhom does not own. He resolves the conflict; Felhom mutates nothing. This is checked before anything is written (§7 pre-flight).

---

5. Exit rights (data sovereignty)

Peti can leave at any time and keep his data. The uninstaller:

• Keeps all drive data under /mnt/felhom-drives/*, the backup storage contents, the hub record, and any vaulted recovery credential — and prints a KEPT-vs-WIPED statement naming each, in both modes. Drives are unmounted (plain umount; a busy drive is warned, never force-unmounted).
• Removes only Felhom's own footprint: its guest, agent, sudoers, self-update artifacts, and config (including .bak* siblings that could hold a hub API key).
• Refuses to touch any guest that is not a Felhom guest (it targets only guests carrying the /etc/felhom-bootstrap bind mount).

Result: Peti walks away with his hardware untouched and his data on his own removable drives. This was live-validated twice on the demo host (two real uninstalls, drive data intact each time, host audit clean) during the GL-6 drill.

---

6. Pre-install checklist (confirm with Peti before day-0)

• PVE major version 9.x (the byo preflight refuses non-9.x unless forced).
• Port 53 is free on the host — no existing DNS service bound there (F6; preflight refuses otherwise).
• The felhom pool either does not exist or is Felhom's to use.
• VMID 9201 is free (or pick another; the installer auto-selects a free one if 9201 is taken).
• ⚠ OPEN — the backup target. felhom-pbs (the demo offsite datastore) is unreachable from Peti's LAN, so the default --acl-storages "local local-lvm felhom-pbs" is wrong for him. We must know whether Peti's server has a second disk/pool to use as the local backup target: - If yes → name it in --acl-storages (e.g. "local local-lvm <his-backup-storage>") so backups land on a different physical drive than the live guest — real local resilience. - If no (single pool) → backups land on the same pool as the guest; this is a degraded posture (one drive failure loses both live and backup) and must be stated to Peti explicitly. Resolve this before finalising the install command below.
• sajatfelhom.hu Cloudflare tunnel — confirm we can re-point it at the new guest (§7).
• Customer peti-felhom exists in the hub with real Gitea read creds filled in (git.username/git.token) — the artifact fetch needs them, or relies on the anonymous path.

---

7. The install command

Built from the hub's customer page (peti-felhom → Setup Command → BYO). The BYO shape is deliberately minimal — a fresh box auto-fetches the golden template from Gitea, so no --force-gitea-golden is needed:

sudo ./felhom-host-install.sh \
  --customer-id peti-felhom \
  --mode byo \
  --cores 12 \
  --memory 32768 \
  --acl-storages "local local-lvm <PETI-BACKUP-STORAGE>"

<PETI-BACKUP-STORAGE> is resolved by the §6 open question. Add --vmid/--node only if 9201 is taken or the host is multi-node. The command is download-then-run (the script is fetched and inspected, never piped straight into a shell).

Onboarding sequence:

1. Run pre-flight first: same command with --preflight-only — prints PASS/FAIL, writes no state. Confirms 9.x, :53 free, ACL storages exist, pool membership.
2. Run the install. Peti sees the host-mutation disclosure and types his hostname to acknowledge.
3. Claim the dashboard (customer-claim model, controller v0.122.0 + hub v0.50.0 — supersedes the old operator-set G9). The dashboard is NOT open before the customer claims it: an unclaimed box serves only the claim page. On the box's first report the hub emails a one-time claim code to Peti's registered address; he opens felhom.sajatfelhom.hu, enters the code, and sets his OWN password. The operator never sets or sees it. If the code didn't arrive, the "Új kód kérése" button (or the operator's "Kód újraküldése" on the hub customer page) emails a fresh one. Set the geo-restriction at onboarding as before. Onboarding is complete once Peti has claimed + logged in.
4. Re-point the sajatfelhom.hu Cloudflare tunnel at the new guest.
5. Verify local backups are green on his box (§4 — the honesty gate). Confirm a backup completes to <PETI-BACKUP-STORAGE> and a restore-test passes mount-parity.

---

8. Acknowledgement

At onboarding, Peti is asked to acknowledge (in Hungarian):

1. Felhom runs as a guest on his hardware; he stays root and Felhom never changes his root password or opens an inbound operator session.
2. There is no offsite backup in the pilot. His data stays on his premises on a removable drive; a lost box or a failed backup drive without a second local copy loses data.
3. He can uninstall at any time and keep his data and hardware; Felhom removes only its own footprint.
4. This is a pilot: rough edges are expected, and the honest limitations above are the trade for full data sovereignty.