chrome-headless (Termux + proot Debian)

Run local headless Chromium on Android (Termux) with a DevTools endpoint at 127.0.0.1:9222.

This project is primarily designed to support Pi's browser-tools skill: https://github.com/badlogic/pi-skills/tree/main/browser-tools

Requirements

• Android device with Termux
• Network access for first-time package installs
• Enough storage for Debian + Chromium packages

Install

1) Clone

git clone https://github.com/<you>/chrome-headless.git
cd chrome-headless

2) Install command into your PATH

make install

This installs chrome-headless to:

• $PREFIX/bin (Termux default), or
• ~/.local/bin when PREFIX is not set.

Re-run make install after pulling updates.

First-time runtime setup

chrome-headless install

This command is idempotent and will:

• install proot-distro (if missing)
• install Debian distro (if missing)
• install Chromium in Debian
• install fonts-noto-color-emoji for better screenshot parity

Usage

chrome-headless start
chrome-headless start --mobile
chrome-headless stop
chrome-headless restart
chrome-headless restart --mobile
chrome-headless status
chrome-headless logs

--mobile / --desktop may appear before or after start / restart.

Mobile profile defaults

• viewport: 412x915
• device scale factor: 2.625
• Android mobile user-agent

Environment overrides

CHROME_HEADLESS_PROFILE=mobile
CHROME_HEADLESS_WINDOW_SIZE=412,915
CHROME_HEADLESS_DEVICE_SCALE_FACTOR=2.625
CHROME_HEADLESS_USER_AGENT='Mozilla/5.0 ...'
CHROME_HEADLESS_PORT=9222

Paths and endpoints

• DevTools endpoint: http://127.0.0.1:9222/json/version
• Log file: ~/.cache/browser-tools/chromium-headless.log
• Chromium user data: ~/.cache/browser-tools/user-data

Troubleshooting

• chrome-headless status says stopped:
  • run chrome-headless logs
  • ensure chrome-headless install completed successfully
• Port conflict on 9222:
  • stop other DevTools instances
  • set CHROME_HEADLESS_PORT to another local port
• Slow first run:
  • package installation in proot can take several minutes

Development

Local checks:

bash -n chrome-headless
shellcheck chrome-headless

CI runs the same checks on pushes and pull requests.

License

GNU General Public License v3.0 (GPL-3.0). See LICENSE.