# REPORT — agent v0.20.0: golden stacks-dir bind + per-guest hostname/CT + bake base-infra images (2026-06-11)

**Repo:** `felhom-agent` · **Version:** 0.20.0 · **Date:** 2026-06-11
**Pushed commit:** `1799fcd` · paired with `felhom-controller` v0.41.0 (`abbd948`) + golden rebake.

## What shipped (all in `configs/build-golden.sh` + the provision path; no change to proxmox/authz/token fences)

- **Section-G mount fix (load-bearing):** the in-guest controller writes app/infra compose stacks under
  `/opt/docker/stacks` *inside its container*, but the baked controller-bootstrap `docker run` never
  bind-mounted that path — so `docker compose up` (run by the GUEST daemon over the shared socket)
  resolved every relative bind source on the guest filesystem, silently creating empty dirs and breaking
  **every** bind-mounted stack (base infra AND customer apps). The bootstrap unit now `mkdir -p
  /opt/docker/stacks` and adds a **same-path host bind** `-v /opt/docker/stacks:/opt/docker/stacks` (a
  named volume would NOT fix this). Empirically confirmed on guest 9201 before writing the fix.
- **Per-guest container hostname (3A):** the bootstrap unit parses `customer.id` from
  `/etc/felhom-bootstrap/bootstrap.json` with a portable `sed` (NO jq in the golden) and passes
  `--hostname <customer-id>` to `docker run`. **Security-hardened** (flagged by the commit security
  review): the id is validated to a DNS-safe label (reject spaces/slashes/leading-dash) and passed via a
  quoted array, so a malformed/hostile id can't smuggle docker flags (e.g. `--privileged`) into the
  de-privileged run. Empty/invalid → no `--hostname` (fail-safe).
- **Per-guest CT/LXC name (3B):** `--selftest=provision` defaults `-hostname` to the DNS-safe-sanitized
  `-customer-id` when not given, so the bring-up's existing `SetConfig hostname` step names the CT
  meaningfully instead of inheriting the golden's `felhom-golden`. New `sanitizeHostname` (lowercase,
  collapse invalid → `-`, trim, ≤63).
- **Bake base-infra images:** the golden pulls the three PINNED, PUBLIC base-infra images
  (`traefik:v3.6.7`, `cloudflare/cloudflared:2026.6.0`, `gtstef/filebrowser:1.3.3-stable`) into its Docker
  storage so the controller's first-boot bring-up is OFFLINE-capable. A `docker manifest inspect` **hard
  gate** fails the bake early on a bad pin. Tags MUST match the controller's `internal/infra` constants.

## Live validation (demo host felhom-pve / PVE 9.2.2)

- Agent **v0.20.0** built (go1.26, ldflags `-X main.version=0.20.0`) and deployed to
  `/usr/local/bin/felhom-agent`; service active.
- **Golden rebaked** → `local:backup/vzdump-lxc-9100-2026_06_11-15_06_05.tar.zst` (877 MB, up from ~599 MB
  ≈ the three baked infra images). Controller `:0.41.0` pulled (digest `0a9d456…`) + all 3 infra pins
  resolved past the hard gate. `/etc/felhom-controller-image` reads `:0.41.0`.
- **Guest 9201 destroyed + re-provisioned** from the new golden: provision header `hostname=demo-felhom`;
  CT config `hostname: demo-felhom`; runtime hostname `demo-felhom`; controller `os.Hostname()` =
  `demo-felhom`. Back-half minted the per-guest token + attached the `mp9` bootstrap mount.
- After `pct reboot` + `systemctl restart felhom-agent`: the baked controller-bootstrap deployed the
  controller, which pulled its config and stood up the base stack — **4 containers running**, Health = OK,
  cloudflared tunnel registered, the `/opt/docker/stacks` bind resolving end-to-end.

## Notes
- The registry credential used for the bake was staged transiently as a 0600 file on the host and removed
  by the rebake; it is **stored out-of-band** and never committed.