Master control node for the Android VM fleet. Clones Android-x86 VMs from template 1301 on demand. Each clone gets a random MAC → random DHCP IP from the LAN router → auto-registers via adb (:5555) → gets a unique egress proxy from the NordVPN bank. Full live telemetry in the dashboard.

Quick commands

# spawn 3 fleet members
curl -X POST http://10.30.20.31:8080/api/spawn -H "Content-Type: application/json" -d '{"count":3,"name_prefix":"fleet"}'

# watch the job
curl -s http://10.30.20.31:8080/api/spawn/jobs

# list devices
curl -s http://10.30.20.31:8080/api/devices

# shell (whitelisted cmds)
curl -X POST http://10.30.20.31:8080/api/device/<MAC>/shell -H "Content-Type: application/json" -d '{"cmd":"getprop ro.build.fingerprint"}'

# screenshot
curl -X POST http://10.30.20.31:8080/api/device/<MAC>/screenshot -o shot.png

# reboot / kill (kill = destroy VM + release proxy)
curl -X POST http://10.30.20.31:8080/api/device/<MAC>/reboot
curl -X POST http://10.30.20.31:8080/api/device/<MAC>/kill

# add proxy
curl -X POST http://10.30.20.31:8080/api/proxies -H "Content-Type: application/json" -d '{"name":"nord-tokyo","host":"10.30.20.154","port":1080,"proto":"socks5"}'

# assign proxy to device
curl -X POST http://10.30.20.31:8080/api/proxies/4/assign -H "Content-Type: application/json" -d '{"mac":"bc:24:11:cb:6a:f7"}'

# direct adb (from CT704)
pct exec 704 -- adb connect 10.30.20.195:5555
pct exec 704 -- adb -s 10.30.20.195:5555 shell "pm list packages"

How pieces connect

Proxmox (clone/start/destroy via PVE API token)
  ↕
CT704 godhead (Flask :8080 + SQLite + adb + ws)
  ├─ scan 10.30.20.0/24:5555 every 10s ─▶ new devices auto-register
  ├─ adb metrics every 15s (cpu/mem/battery/net)
  ├─ proxy health every 60s → auto-assign → settings put global http_proxy on device
  └─ WS push → dashboard live cards + charts

How AI agents drive it

Agents = Hermes cron jobs on local GPU Ollama (light_reaper granite4.1:3b / shadow-death gemma4:26b). NEVER MacBook models, never LLMs on CTs.
Pattern: agent reads /api/devices → picks device(s) → calls shell/screenshot/spawn endpoints → acts (e.g. install APK, run app, tap via input — extend the whitelist regex in app.py for new cmds).
MCP: add a remote HTTP MCP in Hermes config (url http://10.30.20.31:8080/mcp) wrapping the same endpoints when needed.

Troubleshooting

Symptom	Fix
Device offline	`pct exec 704 -- adb connect <ip>:5555` manually; check VM status `qm status <vmid>`; reboot via VM
Never appears	DHCP lease? check router; ensure adb port open: `nc -z -w2 <ip> 5555`
Spawn job error	`curl /api/spawn/jobs` — free-vmid scan 1310+; check Proxmox storage space (local dir, full clone = 12GB each)
Proxy dead	`pct exec 680 -- gost` is the process; check nordvpn: `pct exec 680 -- nordvpn status`; then health loop auto-recovers
No egress IP shown	proxy assigned but check failed — verify from CT704: `curl -x socks5h://10.30.20.71:1080 https://api.ipify.org`
Boot hang at "Detecting Android-x86"	system.sfs rebuilt with wrong compression — MUST be gzip/128K blocks

Template surgery (when updating the image)

Pick a known-good running clone. 2. qm stop <vmid>. 3. qemu-nbd map its disk (NOT the base image — templates are immutable). 4. Extract /android-9.0-r2/system.sfs → unsquashfs → loop-mount system.img → edit build.prop / etc/init.sh → umount → mksquashfs -comp gzip -b 131072. 5. Write back, unmount, disconnect. 6. qm destroy 1301 --purge → qm clone <vmid> 1301 --full → set args (ip=dhcp, -vnc 5961) → qm template 1301.

Backups / state

/opt/android-fleet/{fleet.db, config.json} on CT704 — copy both before any surgery.
Template base: /var/lib/vz/images/1301/base-1301-disk-1.qcow2 (immutable, don't hand-edit).
Docs: Obsidian Hermes/android-fleet-godhead.md · fleet db mirrors to Teable if wired.