Z2 Container Architecture

Host

Platform: Proxmox VE 8.x on Debian 12 (kernel 7.0.2-6-pve) Storage: WD 2TB enterprise (WDC WD2000FYYZ) via Ugreen USB 3.0 enclosure (Realtek 0bda:9201), mounted at /mnt/data (ext4) USB driver: usb-storage (UAS disabled via modprobe quirk at /etc/modprobe.d/usb-storage-quirks.conf)

Containers

All containers are unprivileged LXC (Debian 12), using local-lvm for rootfs.

VMID	Hostname	Owner	Cores	RAM	Rootfs	Auto-start
100	jimmy-neutron-postgres	jimmy-neutron	2	2048 MB	32G	yes
101	heimerdinger-nlp	heimerdinger	2	2048 MB	32G	yes
102	iroh-mail-poller	iroh	2	2048 MB	32G	yes
103	itachi-security	itachi	2	2048 MB	32G	yes
104	l-research	l	2	2048 MB	32G	yes
105	nujabes-audio	nujabes	2	2048 MB	32G	yes
106	minato-telegram	minato	2	2048 MB	32G	yes
107	orochimaru-transcripts	orochimaru	2	2048 MB	32G	yes
108	zoro-fitness	zoro	2	2048 MB	32G	yes
109	bulma-finance	bulma	2	2048 MB	32G	yes
110	hinata-desktop	jimmy-neutron	2	2048 MB	10G	yes
111	hinata-exit-node	jimmy-neutron	1	512 MB	8G	yes

CT110 runs Debian 13 (trixie). All other containers run Debian 12.

CT111 carries TUN passthrough (lxc.cgroup2.devices.allow: c 10:200 rwm + lxc.mount.entry for /dev/net/tun) and runs the Mullvad WireGuard tunnel (wg-quick@mullvad, relay gb-lon, DNS 10.64.0.1) plus Tailscale advertised as exit node (--advertise-exit-node --accept-dns=false). The WireGuard private key lives only at CT111 /etc/wireguard/private.key (0600). The Z2 host carries no WireGuard configuration.

Bind Mounts

CT100 — jimmy-neutron-postgres

Mount	Host path	Container path	Mode
mp0	/mnt/data/postgres-backup	/mnt/backup	rw
mp1	/mnt/data/shared	/shared	rw

CT101 — heimerdinger-nlp

Mount	Host path	Container path	Mode
mp0	/mnt/data/shared	/shared	rw
mp1	/mnt/data/hinata/mail-archive	/mail-archive	rw
mp2	/mnt/data/hinata/resources/email-intelligence	/email-intelligence	rw

CT102 — iroh-mail-poller

Mount	Host path	Container path	Mode
mp0	/mnt/data/shared	/shared	rw
mp1	/mnt/data/hinata/mail-archive	/mail-archive	rw

CT103 — itachi-security

Mount	Host path	Container path	Mode
mp0	/mnt/data/shared	/shared	rw

CT104 — l-research

Mount	Host path	Container path	Mode
mp0	/mnt/data/shared	/shared	rw

CT105 — nujabes-audio

Mount	Host path	Container path	Mode
mp0	/mnt/data/shared	/shared	rw
mp1	/mnt/data/hinata/media	/media	rw

CT106 — minato-telegram

Mount	Host path	Container path	Mode
mp0	/opt/jimmy-brain-ops/scripts	/opt/scripts	ro
mp1	/mnt/data/transcripts	/transcripts	rw
mp2	/opt/hinata-vault	/opt/vault	ro
mp4	/opt/telegram-gateway	/opt/telegram-gateway	rw

CT107 — orochimaru-transcripts

Mount	Host path	Container path	Mode
mp0	/mnt/data/transcripts	/transcripts	rw

CT108 — zoro-fitness

Mount	Host path	Container path	Mode
mp0	/mnt/data/zoro-fitness	/mnt/data/zoro-fitness	rw
mp1	/opt/hinata-sandpit	/root/Sandpit/hinata-sandpit	ro

CT109 — bulma-finance

Mount	Host path	Container path	Mode
mp0	/mnt/data/hinata/data/bulma	/root/data/bulma	rw
mp1	/opt/hinata-sandpit	/root/Sandpit/hinata-sandpit	ro
mp2	/mnt/data/shared	/shared	rw

CT110 — hinata-desktop

Mount	Host path	Container path	Mode
mp0	/mnt/data/hinata	/mnt/hinata	ro

Remote Desktop

VMID	Hostname	IP	Service	Port	Login user	Groups	Vaultwarden item
110	hinata-desktop	192.168.1.114 (DHCP)	xrdp (XFCE session)	3389 (LAN-only)	nnamdi	sudo	ct110-hinata-desktop

Shared Paths

Host path	Purpose	Containers
/mnt/data/shared	Cross-container shared data	CT100, 101, 102, 103, 104, 105, 109
/mnt/data/transcripts	CLI transcript storage	CT106, 107
/opt/hinata-sandpit	Native git clone of /opt/hinata-sandpit-bare. Updated on every push by the bare repo's post-receive hook.	CT108, 109
/mnt/data/hinata/mail-archive	Email archive (4 accounts)	CT101, 102

Host Services

Port	Service	Unit	Purpose
5173	studio-preview	studio-preview.service	Vite dev staging of applications/hinata-studio (exact localhost replica, --host 0.0.0.0)
8080	hinata-collector (read API)	hinata-collector.service	Public FastAPI surface (uvicorn). Routers: bulma, events, football, leaderboard, mastery, musicmastery, sanji, shogi, zoro, allmight. Public via CT112 tunnel.
8090	collector-bulma	hinata-collector-bulma.service	Bulma write/ingest (split from former bulma+zoro twin)
8091	collector-events	hinata-collector-events.service	Events write/ingest
8092	collector-zoro	hinata-collector-zoro.service	Zoro fitness write/ingest. New 2026-06-12; /zoro/workouts, /zoro/summary, /zoro/posture, /zoro/posture/latest. EnvironmentFile=/etc/hinata/collector.env.
8093	collector-mastery	hinata-collector-mastery.service	Mastery write/ingest
8094	collector-musicmastery	hinata-collector-musicmastery.service	Musicmastery write/ingest
8095	collector-quiz	hinata-collector-quiz.service	Quiz write/ingest
8096	collector-brook	hinata-collector-brook.service	Brook write/ingest
8097	collector-housing	hinata-collector-housing.service	Housing write/ingest
8099	collector-allmight	collector-allmight.service	Health Auto Export receiver — Apple Health JSON (/v2/health) + GPX routes (/v2/workout-route) to /mnt/data/hinata/data/allmight/

Public ingress — CT112 hinata-edge

Field	Value
Container	CT112 hinata-edge
Tunnel ID	fe668023-b168-41f0-b3b0-5b3891239b65
Hostname	api.michael-engineer.dev
Origin	http://192.168.1.153:8080
Path regex	^/(events|mastery|musicmastery|football|leaderboard|bulma|sanji|zoro|allmight|shogi)
Catch-all	http_status:404
Config path	/etc/cloudflared/config.yml (CT112)
Sandpit mirror	z2-collector/cloudflared/ct112-hinata-edge-config.yml
Key gating	None (read API is keyless)

Twin-unit retirement

Field	Value
Retired unit	collector-bulma.service
Replacement pair	hinata-collector-bulma.service (:8090, bulma-only) · hinata-collector-zoro.service (:8092)
Pre-split backup	/opt/jimmy-brain-ops/scripts/collector-bulma.py.pre-split-20260612
Bulma script size	264 lines
Zoro script size	224 lines
EnvironmentFile	/etc/hinata/collector.env
Retired	2026-06-12

Zero-stub-endpoints ruling

Field	Value
Ruled	2026-06-12
Stripped endpoint	/healthz from collectors: brook, events, football, mastery, musicmastery, quiz, bulma, zoro
Stripped endpoint	/ping from app/main.py
Collateral	class LeaderboardEntryIn removed from collector-events.py, restored from collector-quiz.py:37
Verification	Symtable scan across 9 touched files
Outstanding caller	applications/hinata-studio/src/musicmastery/api.ts lines 174–182 (404 fleet-wide)

Stale duplicate residue

Path	State
/opt/hinata-z2/scripts/ (Z2 host)	Stale duplicate collector copies; live runtime path is /opt/jimmy-brain-ops/scripts/

USB Storage Quirk

The Ugreen USB enclosure (Realtek 0bda:9201) triggers UAS protocol abort errors under sustained I/O, causing container bind mount flaps. Fixed by forcing the usb-storage driver:

Config: /etc/modprobe.d/usb-storage-quirks.conf

options usb-storage quirks=0bda:9201:u

Applied via update-initramfs -u + reboot. Kernel confirms: UAS is ignored for this device, using usb-storage instead.

Known Failure Modes

Symptom	Cause	Resolution
lxc.hook.pre-start error on container start	Bind mount host source path missing	Correct mp* path in /etc/pve/lxc/[vmid].conf
I/O error inside container, host path accessible	Stale bind mount after USB device reset	Container reboot (pct reboot [vmid])
All containers lose bind access simultaneously	USB storage device flap	Host reboot to rebind all mounts

Cross-links: reference_z2-service-catalog · reference_container-storage-strategy