74 lines
4.0 KiB
Markdown
74 lines
4.0 KiB
Markdown
# Android Fleet Godhead — Operator Manual
|
|
|
|
Dashboard: http://10.30.20.31:8080 · CT704 · systemd: android-fleet
|
|
|
|
## What it is
|
|
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
|
|
|
|
```bash
|
|
# 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)
|
|
1. 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.
|