Jeena
40a9d1e2c6
Document how the host emulator is driven over adb from the agent container: the start script now boots headless by default and trusts remote adb keys via ADB_VENDOR_KEYS at launch, since the TV system image is a user build that blocks pushing keys to adb_keys after boot. AGENTS.md points to the new doc and fixes the stale SDK path.
60 lines
No EOL
2.9 KiB
Markdown
60 lines
No EOL
2.9 KiB
Markdown
# Agent container ↔ host emulator setup
|
|
|
|
How the testing loop between the JTube TV agent container and the host
|
|
emulator works, and what needs to exist again after a rebuild.
|
|
|
|
## Topology
|
|
|
|
- **Emulator**: runs on the **host** (`/opt/android-sdk`, launched by
|
|
`scripts/start-emulator.sh`). **Headless is the default**; set
|
|
`JTUBE_EMU_MODE=windowed` if you want the Qt window (e.g. for desktop
|
|
interaction testing). View it via scrcpy either way.
|
|
- **Agent container**: image `agent-container:latest`, container name pattern
|
|
`ac-<project>-<hash>`, launched with **`--network host`** — it shares the
|
|
host's network namespace. This is load-bearing: see below.
|
|
|
|
## Why host networking makes adb trivial
|
|
|
|
With `--network host`, the container's `localhost` *is* the host's localhost.
|
|
So inside the container:
|
|
|
|
- `adb connect 127.0.0.1:5556` → hits the host's socat bridge → emulator adbd.
|
|
- The adb **server** running on 127.0.0.1:5037 is also shared with the host,
|
|
so the container inherits whatever authorization the host adb server has.
|
|
No separate RSA handshake is needed. (Caveat: whoever's adb server grabs
|
|
port 5037 first owns it; all clients share it.)
|
|
|
|
## What must be (re)installed after a container rebuild
|
|
|
|
1. **`android-tools` in the container** (provides `adb`; installed into the
|
|
running container with `sudo pacman -S --noconfirm android-tools`, but that
|
|
is ephemeral). To make rebuilds self-sufficient, bake it into the
|
|
`agent-container` image at build time.
|
|
2. **Nothing else is needed for adb**: key handling is inherited from the
|
|
shared host adb server (see above). If the container is ever switched to
|
|
bridge networking, use `adb connect rutherford:5556` — remote keys are
|
|
handled by the emulator's `ADB_VENDOR_KEYS` (next section).
|
|
|
|
## Emulator-side facts (host)
|
|
|
|
- Ports: console `5600`, adbd `5601` (`-port 5600` ⇒ console+1), LAN bridge
|
|
`socat TCP-LISTEN:5556 → 127.0.0.1:5601` (0.0.0.0, so remote machines can
|
|
`adb connect rutherford:5556`).
|
|
- Remote key whitelisting: the TV system image is a user build — adb
|
|
`push`/`shell` writes to `/data/misc/adb/adb_keys` are blocked. The script
|
|
therefore builds `/tmp/jtube-adbkeys-combined` (host key + every
|
|
`/tmp/jtube-adbkeys/*.pub`) and launches the emulator with
|
|
`ADB_VENDOR_KEYS` pointing at it. To trust a new client: put its
|
|
`~/.android/adbkey.pub` into `/tmp/jtube-adbkeys/` **before** launching.
|
|
- Logs: `/tmp/jtube-emu.log` (QEMU) and `/tmp/jtube-emu-run.log` (script).
|
|
- Viewing: `scrcpy -s emulator-5600` on the host, or from any LAN machine:
|
|
`adb connect rutherford:5556 && scrcpy -s 127.0.0.1:5556`.
|
|
|
|
## Known quirks
|
|
|
|
- Emulator Qt toolbar (back/home buttons) is a detached XWayland window that
|
|
misbehaves on Hyprland — drive the emulator via scrcpy or adb instead.
|
|
- The TV image is a user build: no `adb root`.
|
|
- Under the Android TV AVD, keyboard input in the Qt window works, but the
|
|
reliable inputs are scrcpy (`b` = back, `h` = home) or
|
|
`adb shell input keyevent`. |