android-fleet-godhead/README.md

Android Fleet Godhead

Autonomous Android VM fleet control node for Proxmox. Dashboard + REST API + WebSocket at http://10.30.20.31:8080 (LXC CT704, systemd android-fleet + android-harvest).

What it does

• Spawn on demand: clone from Android-x86 template VM 1301 (linked clones) → random MAC → LAN DHCP → auto-registration via adb :5555 → unique egress proxy. Zero IP assignment.
• ProxyFly engine: harvests proxifly.dev's free list every 25 min, live-tests each proxy, cleanliness-grades (ip-api hosting/proxy flags + Spamhaus DNSBL), dedupes by egress IP, and auto-assigns the best clean proxy to every device (pushed via settings put global http_proxy).
• Full device control: interactive xterm.js terminal (/ws/shell/<mac>), programmatic exec (POST /api/device/<mac>/exec, token-gated), screenshots, live hover previews, reboot/kill, onboarding (basics → IG → account via instagrapi + IMAP verification), existing-account login.
• Live dashboard: fleet cards with CPU/MEM/battery/net, 4 live charts, proxy bank with clean badges, IG accounts panel, event log.

Files

File	Purpose
app.py	Flask + flask-sock control node (discovery, adb, spawn, proxies, WS)
proxy_harvest.py	ProxyFly fetch → test → clean-grade → assign engine
onboard.py	Per-device phone setup + IG account pipeline
static/index.html	Dashboard (Tailwind + Chart.js + xterm.js, zero build)
docs/	MASTER_PROMPT.md + operator manual
*.service	systemd units

Deploy

# from repo root, on the godhead CT:
mkdir -p /opt/android-fleet
cp app.py proxy_harvest.py onboard.py config.json /opt/android-fleet/
cp -r static /opt/android-fleet/
cp android-fleet.service android-harvest.service /etc/systemd/system/
pip3 install --break-system-packages flask flask-sock requests pysocks instagrapi
apt-get install -y adb
systemctl daemon-reload && systemctl enable --now android-fleet android-harvest

Quick API

curl -X POST http://10.30.20.31:8080/api/spawn -H "Content-Type: application/json" -d '{"count":3}'
curl http://10.30.20.31:8080/api/devices
curl -X POST http://10.30.20.31:8080/api/device/<MAC>/exec \
     -H "Content-Type: application/json" -H "X-Auth-Token: <token>" -d '{"cmd":"getprop ro.build.version.release"}'

Secrets live in config.json (gitignored) — copy config.json.example.