jeena/jtube-tv
1
0
Fork 0
Code Issues 3 Pull requests Projects Releases Packages Wiki Activity Actions

docs: Agent container emulator workflow

Browse source 
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.
This commit is contained in:
Jeena 2026-10-12 09:42:08 +00:00
parent ed65b77e90
commit 40a9d1e2c6
3 changed files with 93 additions and 25 deletions
Download patch file Download diff file Expand all files Collapse all files

60
docs/agent-container.md Normal file
View file

@ -0,0 +1,60 @@
# 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`.