How do I use Termux Browser Pilot?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Termux Browser Pilot goto https://news.ycombinator.com and get the page title" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

Termux Browser Pilot v0.17.1

Real browser automation for Termux/Android. No root required.

Firefox (default) or Chromium on Xvfb — runs entirely on your phone. Firefox passes Cloudflare natively via TLS fingerprint. Chromium uses CDP stealth. Both use real device hardware info.

Features

Persistent daemon — browser stays running, sub-second commands
Passes Cloudflare — Firefox: instant TLS-based pass; Chromium: Turnstile handler
No automation framework — Firefox controlled via xdotool + clipboard JS execution
AI-friendly — --json flag on all commands for structured output
Real device fingerprint — auto-detects screen, GPU, CPU, arch, model
Human-like input — Bezier curve mouse, realistic typing, clipboard paste
Session persistence — auto-save/load cookies across restarts
Cookie management — get/set/save/load, Netscape format import/export
Network tracking — capture all request URLs, types, sizes (Chromium only)
Screenshots — viewport or full page PNG, PDF export
Accessibility tree — ARIA roles and names
Cross-device — auto-adapts to any Android device's real specs
Smart element targeting — find clickable elements by visible text
Idle timeout — auto-shutdown daemon after configurable inactivity
Tab management — open, close, switch between browser tabs
Proxy support — HTTP/SOCKS5 proxy for Firefox and Chromium
Request interception — block URLs/domains via JS fetch/XHR hooks
Multi-step macros — chain commands into reusable JSON scripts
Console log capture — capture console.log/warn/error/info output
Download management — auto-download files to ~/.tbp/downloads/
Network request log — capture URLs, types, durations, sizes
DOM mutation observer — watch for element changes in real-time
Element screenshot — capture specific elements by CSS selector
Drag and drop — smooth mouse drag between elements or by offset
Iframe support — list, eval, text, click inside same-origin iframes
File upload — set files on input[type=file] via JS DataTransfer
Geolocation spoofing — override navigator.geolocation coordinates
User agent switching — optional override (default: real browser UA)
Cookie injection — set cookies with domain, path, secure, SameSite
Local/session storage — get, set, remove, clear, list items
Clipboard access — read/write Xvfb system clipboard
Form auto-fill — fill all form fields from JSON spec
Lightweight — no Puppeteer/Playwright dependency

Quick Start

Install

bash setup.sh

# Or manually:
pkg install tur-repo x11-repo
pkg install firefox xorg-server-xvfb xdotool xclip openbox python3
pip install websockets  # only needed for Chromium mode

CLI (Daemon Mode — Recommended)

Browser starts once, stays running. Commands are instant.

# Navigate (auto-starts daemon on first command)
tbp goto https://example.com
tbp goto https://audiogames.net -cf    # Cloudflare bypass

# Read content
tbp text                               # Page text
tbp links                              # All links
tbp eval "document.title"              # Run JavaScript
tbp a11y                               # Accessibility tree

# Interact
tbp click "button.submit"              # Click element
tbp type "input[name=q]" "hello"       # Type into field
tbp press Enter                        # Press key
tbp scroll --down                      # Scroll page
tbp find "Sign In"                     # Find elements by text
tbp find "Submit" --role button        # Filter by role

# Tab management
tbp tab new                            # Open new tab
tbp tab new https://example.com        # New tab with URL
tbp tab close                          # Close current tab
tbp tab next                           # Next tab
tbp tab prev                           # Previous tab
tbp tab goto 2                         # Switch to tab 2

# Block requests
tbp block ads.example.com tracker.js   # Block URL patterns
tbp blocklist                          # List blocked patterns
tbp unblock ads.example.com            # Unblock pattern

# Macros (JSON scripts)
tbp macro workflow.json                # Run multi-step macro

# Console log capture
tbp console start                      # Start capturing logs
tbp console stop                       # Stop capturing logs
tbp console logs                       # Show captured logs
tbp console logs --clear               # Show and clear buffer
tbp console clear                      # Clear log buffer

# Downloads
tbp downloads                          # List downloaded files

# Network request log
tbp network start                      # Start logging requests
tbp network stop                       # Stop logging requests
tbp network logs                       # Show captured requests
tbp network logs --clear               # Show and clear
tbp network clear                      # Clear request log

# DOM mutation observer
tbp observe start                      # Start watching mutations
tbp observe stop                       # Stop watching mutations
tbp observe logs                       # Show captured mutations
tbp observe clear                      # Clear mutations

# Element screenshot
tbp screenshot-element "div.hero"      # Screenshot specific element
tbp screenshot-element "#logo" logo.png

# Drag and drop
tbp drag ".item" --target ".dropzone"  # Drag to element
tbp drag ".slider" --dx 100            # Drag by offset

# Iframe support
tbp iframe list                        # List all iframes
tbp iframe eval "iframe#f1" "document.title"  # JS in iframe
tbp iframe text "iframe#f1"            # Get iframe text
tbp iframe click "iframe#f1" "button"  # Click in iframe

# File upload
tbp upload "input[type=file]" photo.jpg  # Upload file (max 5MB)

# Geolocation spoofing
tbp geo set 40.7128 -74.0060           # Set to New York
tbp geo set 51.5074 -0.1278 -a 50      # London, 50m accuracy
tbp geo clear                           # Clear override

# User agent switching (default: real browser UA — override is optional)
tbp useragent set "Mozilla/5.0 (Windows NT 10.0; Win64; x64)"
tbp ua clear                            # Restore real UA
# Note: Overrides JS-side navigator.userAgent only.
# HTTP User-Agent header stays real (requires restart to change).

# Cookie injection
tbp cookie-set session_id abc123          # Simple cookie
tbp cs token xyz --domain .example.com    # With domain
tbp cs pref dark --max-age 86400 --secure # Secure + 1 day

# Local/session storage
tbp storage list                          # List localStorage
tbp storage get mykey                     # Get value
tbp storage set mykey myvalue             # Set value
tbp storage remove mykey                  # Remove key
tbp storage clear                         # Clear all
tbp storage list --type session           # sessionStorage

# Clipboard
tbp clipboard read                        # Read clipboard
tbp clip write "Hello world"              # Write to clipboard

# Form auto-fill (JSON file: [{selector, value}, ...])
tbp form-fill form_data.json              # Fill all fields

# Proxy support (on start)
tbp start --proxy socks5://127.0.0.1:1080

# Screenshots
tbp screenshot page.png
tbp screenshot page.png --full         # Full page

# AI-friendly JSON output
tbp goto https://example.com --json
tbp text --json
tbp links --json

# Session management
tbp status                             # Daemon status
tbp cookies --save session.json        # Save cookies
tbp cookies --load session.json        # Load cookies
tbp stop                               # Graceful shutdown

Python API

import asyncio
from src.pilot import Pilot

async def main():
    # Firefox (default) — passes Cloudflare natively
    async with Pilot() as p:
        await p.goto_cf("https://audiogames.net")
        print(await p.title())
        await p.screenshot("page.png")

    # Chromium mode with session persistence
    async with Pilot(browser="chromium", session_file="session.json") as p:
        await p.goto("https://example.com")
        await p.type("input[name=q]", "hello")

asyncio.run(main())

Daemon Client (Python)

from src.client import send_command
import asyncio

async def main():
    # Auto-starts daemon if not running
    r = await send_command("goto", {"url": "https://example.com"})
    print(r["data"]["title"])

    r = await send_command("text")
    print(r["data"]["text"])

    r = await send_command("screenshot", {"path": "shot.png"})

asyncio.run(main())

MCP Server (for Claude Code / AI Agents)

# Register with Claude Code
claude mcp add tbp -- tbp-mcp

# Or use .mcp.json (already included in repo)
# Tools: browser_goto, browser_text, browser_click, browser_type,
#        browser_screenshot, browser_a11y, browser_links, browser_eval,
#        browser_scroll, browser_hover, browser_press, browser_find,
#        browser_tab_*, browser_block, browser_unblock, browser_blocklist,
#        browser_macro, browser_wait, browser_wait_for, browser_cookies_*,
#        browser_console_*, browser_downloads, browser_network_*,
#        browser_observe_*, browser_mutations*, browser_screenshot_element,
#        browser_drag, browser_iframe_*, browser_upload, browser_geo_*,
#        browser_useragent_*, browser_cookie_set, browser_storage_*,
#        browser_clipboard_*, browser_form_fill, browser_status

Requires: pip install "mcp[cli]>=1.0" (or pip install termux-browser-pilot[mcp]).

Feature Reference

Command	Description
`goto URL [-cf]`	Navigate to URL. `-cf` for Cloudflare bypass
`back` / `forward` / `reload`	History navigation
`text [--selector S]`	Get visible page text
`html [--selector S]`	Get page HTML
`links [--limit N]`	List all links
`eval EXPRESSION`	Execute JavaScript
`title` / `url`	Get page title/URL
`find TEXT [--role R]`	Find interactive elements by visible text
`a11y`	Accessibility tree (ARIA roles and names)

Interaction

Command	Description
`click SELECTOR [--human]`	Click element. `--human` for Bezier curve
`type SELECTOR TEXT`	Type text into input
`press KEY`	Press keyboard key (Enter, Tab, Escape...)
`scroll [--up] [--amount N]`	Scroll page
`hover SELECTOR`	Hover over element
`drag SOURCE [--target T] [--dx N --dy N]`	Drag element

Tab Management

Command	Description
`tab new [URL]`	Open new tab
`tab close`	Close current tab
`tab next` / `tab prev`	Switch tabs
`tab goto INDEX`	Switch to tab 1-9

Screenshots & Export

Command	Description
`screenshot [PATH] [--full]`	Screenshot (viewport or full page)
`screenshot-element SELECTOR [PATH]`	Screenshot specific element
`pdf [PATH]`	Export page as PDF

Request Blocking

Command	Description
`block PATTERNS...`	Block URL patterns (domains/substrings)
`unblock PATTERNS...`	Remove blocked patterns
`blocklist`	List current blocked patterns

Console Log Capture

Command	Description
`console start`	Start capturing console.log/warn/error/info
`console stop`	Stop capturing (disables re-injection)
`console logs [--clear] [--limit N]`	Show captured logs
`console clear`	Clear log buffer

Network Request Log

Uses PerformanceObserver (passive, no conflict with URL blocker).

Command	Description
`network start`	Start logging network requests
`network stop`	Stop logging
`network logs [--clear] [--limit N]`	Show requests (URL, type, duration, size)
`network clear`	Clear request log

DOM Mutation Observer

Command	Description
`observe start`	Start watching DOM mutations
`observe stop`	Stop watching
`observe logs [--clear] [--limit N]`	Show mutations (childList, attributes, etc.)
`observe clear`	Clear mutation buffer

Iframe Support

Works with same-origin iframes only. Cross-origin iframes are listed but inaccessible.

Command	Description
`iframe list`	List all iframes (index, src, accessibility)
`iframe eval SELECTOR EXPRESSION`	Execute JS inside iframe
`iframe text SELECTOR [--inner S]`	Get text from iframe
`iframe click SELECTOR TARGET`	Click element inside iframe

File Upload

Sets files on <input type="file"> elements via JS DataTransfer API. Max 5MB.

Command	Description
`upload SELECTOR PATH`	Upload file to file input

Geolocation Spoofing

Overrides navigator.geolocation.getCurrentPosition and watchPosition. Re-injected automatically after page navigation. Saves/restores originals on clear.

Command	Description
`geo set LAT LNG [-a ACCURACY]`	Set geolocation (accuracy default: 100m)
`geo clear`	Restore real geolocation behavior

User Agent Switching

Default: real browser user agent. Override is optional and JS-side only (navigator.userAgent). HTTP User-Agent header sent to servers stays real. Re-injected after navigation. Restored on clear.

Command	Description
`useragent set UA_STRING`	Override navigator.userAgent
`useragent clear` / `ua clear`	Restore real user agent

Sets cookies via document.cookie. Cannot set HttpOnly cookies (browser security). Values are URL-encoded automatically. Name must not contain =, ;, or newlines.

Command	Description
`cookie-set NAME VALUE [--domain D] [--path P]`	Set cookie
Options: `--max-age N`, `--secure`, `--samesite Strict\|Lax\|None`

Local/Session Storage

Command	Description
`storage list [--type local\|session]`	List all items
`storage get KEY [--type ...]`	Get value by key
`storage set KEY VALUE [--type ...]`	Set key-value pair
`storage remove KEY [--type ...]`	Remove key
`storage clear [--type ...]`	Clear all items

Clipboard Access

Reads/writes the Xvfb virtual display clipboard (not the phone clipboard). Useful for reading after a page copy, or setting before a Ctrl+V paste.

Command	Description
`clipboard read`	Read clipboard text
`clipboard write TEXT`	Write text to clipboard

Form Auto-fill

Fills multiple fields from a JSON file. Handles text inputs, selects, checkboxes, and radios. Dispatches input + change events (React/Vue compatible).

[
  {"selector": "#name", "value": "John Doe"},
  {"selector": "#email", "value": "john@example.com"},
  {"selector": "select#country", "value": "US"},
  {"selector": "#agree", "value": true}
]

Command	Description
`form-fill FILE` / `ff FILE`	Fill fields from JSON file (max 100)

CSS Injection

Inject, remove, and list custom stylesheets. Persists across scrolling and re-injects after navigation.

Command	Description
`css inject "RULES" [--id NAME]`	Inject CSS (text or file path)
`css remove [--id NAME]`	Remove stylesheet (or all)
`css list`	List injected stylesheets

Example: tbp css inject "body{background:#111;color:#eee}" --id darkmode

Wait+Action

Wait for an element to appear in the DOM, then automatically perform an action. Uses MutationObserver for efficient detection.

Command	Description
`waitact SELECTOR [--click]`	Wait then click (default)
`waitact SELECTOR --type TEXT`	Wait then type
`waitact SELECTOR --text`	Wait then get text

Timeout: Default 10s, max 120s. Uses --timeout flag.

Page Event Capture

Capture DOM events (click, submit, input, change, keydown) with target element info. Re-injects after navigation automatically.

Command	Description
`events start [--types click submit ...]`	Start capturing events
`events stop`	Stop and remove listeners
`events logs [--limit N] [--clear]`	Show captured events
`events clear`	Clear event log

Viewport/Window Resize

Control browser window dimensions for responsive testing.

Command	Description
`viewport set WIDTH HEIGHT` / `vp set`	Resize window
`viewport get` / `vp get`	Get current dimensions

Returns both window size (xdotool) and inner viewport (JS). Range: 100-7680 x 100-4320.

Page Search

Find text on the page with visual highlighting. Navigate between matches.

Command	Description
`search find "text" [--case-sensitive]`	Find and highlight all matches
`search next`	Go to next match
`search prev`	Go to previous match
`search clear`	Clear highlights

Highlights persist across scrolling. Current match shown in orange, others in yellow. Re-injects after navigation if search is active.

Shadow DOM Access

Query, read, and click elements inside shadow DOM boundaries. Recursively traverses all shadow roots to find elements.

Command	Description
`shadow query SELECTOR`	Find element (returns tag, id, text, attributes)
`shadow text SELECTOR`	Get text content from shadow element
`shadow click SELECTOR`	Click element inside shadow root

Response Body Capture

Capture fetch/XHR response bodies for API inspection and debugging. Bodies truncated to 10KB per response, max 500 entries.

Command	Description
`responses start`	Start capturing response bodies
`responses stop`	Stop capturing
`responses logs [--limit N] [--clear]`	Show captured responses
`responses clear`	Clear response log

Multi-tab Session Management

Save and restore all open browser tabs as named sessions. Sessions stored in ~/.tbp/sessions/{name}.json.

Command	Description
`session save NAME`	Save all open tabs
`session load NAME`	Restore tabs from session
`session list`	List saved sessions
`session delete NAME`	Delete a session

Note: Tab detection uses Ctrl+1-9 shortcuts (max 9 tabs).

HTTP Header Injection

Inject custom headers into all fetch() and XMLHttpRequest calls. Headers persist across requests and re-inject after navigation. Useful for auth tokens, API keys, or custom tracking headers.

Command	Description
`headers set Name:Value [...]`	Set one or more custom headers
`headers list`	List active custom headers
`headers clear`	Remove all custom headers and restore original fetch/XHR

Note: Headers are injected JS-side only (via fetch/XHR interception). They do not affect initial page load requests or non-JS resource fetches.

Page Performance Metrics

Get timing and resource metrics from the Performance API.

Command	Description
`perf`	Show page performance metrics

Returns: first byte time, DOM interactive, DOM content loaded, load complete, DOM element count, script/stylesheet/image/iframe counts, JS heap memory usage.

Element Attributes

Read, set, or remove HTML attributes on elements.

Command	Description
`attr get SELECTOR [--name NAME]`	Get one or all attributes
`attr set SELECTOR NAME VALUE`	Set an attribute
`attr remove SELECTOR NAME`	Remove an attribute

Browser Profile Management

Save and restore browser state (cookies + localStorage + URL) as named profiles. Profiles are stored in ~/.tbp/profiles/<name>/.

Command	Description
`profile save NAME`	Save current state as named profile
`profile load NAME`	Load saved profile (cookies + localStorage)
`profile list`	List all saved profiles
`profile delete NAME`	Delete a saved profile

Profile names: Alphanumeric, hyphens, and underscores only.

Element Highlight

Visual debugging — outline matching elements with colored borders.

Command	Description
`highlight add SELECTOR [--color red] [--label TEXT]`	Highlight elements
`highlight clear [SELECTOR]`	Remove highlights (all or specific)

Highlights persist across navigation (re-injected after goto).

PDF Export Options

Extended PDF export with layout control.

Option	Description
`--landscape`	Landscape orientation
`--scale 0.1-2.0`	Scale factor
`--margin-top/right/bottom/left N`	Margins in inches
`--page-ranges '1-3'`	Specific pages
`--no-background`	Skip background graphics

Example: tbp pdf report.pdf --landscape --scale 0.8 --margin-top 0.5

Save/restore authentication via cookies — auto-navigates to saved URL.

Command	Description
`auth save NAME`	Save cookies + URL as auth session
`auth load NAME`	Restore cookies and navigate to saved URL
`auth list`	List saved auth sessions
`auth delete NAME`	Delete auth session

Sessions stored in ~/.tbp/auth/ with 0o600 permissions.

Network Throttling

Simulate slow connections by adding latency to fetch/XHR requests.

Command	Description
`throttle set --preset 3g`	Apply throttle preset
`throttle set --latency 500`	Custom latency (ms)
`throttle clear`	Remove throttling
`throttle get`	Show current config

Presets: 3g (400ms), slow-3g (2000ms), fast-3g (150ms), offline (reject all).

Annotated Screenshot (AI-First)

Screenshot with numbered badges on interactive elements + legend mapping numbers to CSS selectors.

Command	Description
`annotate [--path FILE] [--selector CSS] [--max N]`	Labeled screenshot

AI workflow: annotate → read legend → click using selector from legend.

Page Audit

One-command structured page health report.

Command	Description
`audit`	Full page health report

Returns: elements, links (total/external/broken), images (alt/broken), forms, headings, meta, scripts, page size, load time, console errors.

Response Mocking

Return fake responses for matching URL patterns. Useful for testing without real backends.

Command	Description
`mock set PATTERN BODY [--status N] [--content-type CT]`	Add mock
`mock clear [PATTERN]`	Remove mock(s)
`mock list`	List active mocks

Mocks persist across navigation (re-injected after goto). Max 50 mocks.

DOM Snapshot & Diff

Save page state, perform actions, then diff to verify changes.

Command	Description
`snapshot take NAME`	Capture page state
`snapshot diff NAME1 NAME2`	Compare two snapshots
`snapshot list`	List snapshots
`snapshot delete NAME`	Delete snapshot

AI workflow: snapshot take before → actions → snapshot take after → snapshot diff before after.

Double-click

Command	Description
`dblclick SELECTOR` / `dbl`	Double-click element (dispatches dblclick event)
`dblclick SELECTOR --human`	Use xdotool double-click

Command	Description
`select SELECTOR --value V`	Select option by value
`select SELECTOR --label L`	Select option by visible text
`select SELECTOR --index N`	Select option by index

Dispatches change + input events for React/Vue compatibility.

Check / Uncheck

Command	Description
`check SELECTOR`	Check a checkbox or radio
`check SELECTOR --action uncheck`	Uncheck
`check SELECTOR --action toggle`	Toggle

Input Value

Command	Description
`input-value SELECTOR` / `iv`	Read current value of input/select/textarea

Returns {value, tag, type}.

Element State

Command	Description
`element-state SELECTOR` / `es`	Query element visibility/enabled/checked state

Returns {visible, enabled, checked, editable, tag, type}.

Bounding Box

Command	Description
`bounding-box SELECTOR` / `bb`	Get element position and dimensions

Returns {x, y, width, height, top, left, bottom, right, scrollX, scrollY}.

Scroll To Element

Command	Description
`scroll-to SELECTOR` / `st`	Scroll element into view (default: center)
`scroll-to SELECTOR --block start`	Align to top

Block options: center, start, end, nearest.

Set Page Content

Command	Description
`set-content HTML`	Replace page with raw HTML (no navigation)
`set-content @file.html`	Load HTML from file

Dialog Handling (alert/confirm/prompt)

Auto-handle browser dialogs without blocking. Monkey-patches window.alert/confirm/prompt. Re-injects after navigation.

Command	Description
`dialog handle`	Enable auto-accept for dialogs
`dialog handle --reject`	Auto-dismiss dialogs
`dialog handle --prompt-text "answer"`	Set prompt response
`dialog dismiss`	Shortcut for reject mode
`dialog logs [--limit N] [--clear]`	Show captured dialog messages
`dialog clear`	Clear dialog log

Wait for Response

Wait for a fetch/XHR response matching a URL pattern.

Command	Description
`waitfor-response PATTERN` / `wr`	Wait for matching response
`waitfor-response PATTERN --timeout 30`	Custom timeout (1-120s)

Enables response capture automatically if not already active.

Multi-step Macros

Chain commands into reusable JSON scripts (max 100 steps).

Command	Description
`macro FILE`	Run macro from JSON file

Session & Lifecycle

Command	Description
`start [--proxy URL] [--idle-timeout N]`	Start daemon
`stop`	Graceful shutdown
`status`	Show daemon status (PID, URL, uptime)
`cookies [--save F] [--load F] [--clear]`	Manage cookies
`downloads` / `dl`	List downloaded files
`kill`	Force-kill everything

Design Philosophy

Be real, not fake. Firefox runs as a normal browser — no geckodriver, no Marionette, no WebDriver flags. Controlled via xdotool (X11 native input) and clipboard-based JS execution through the Web Console. Chromium uses real device hardware info with only webdriver=false hidden.

Architecture

CLI (cli.py) ──Unix socket──→ Daemon (daemon.py)
                                ├── Pilot (unified API)
                                │    ├── BrowserPilot        Xvfb + openbox WM + browser lifecycle
                                │    ├── NativeFirefoxSession xdotool + clipboard JS (persistent profile)
                                │    ├── CDPSession          WebSocket CDP (Chromium)
                                │    ├── PageCommands        navigate, eval, text/html/links
                                │    ├── InputCommands       click, type, scroll, Bezier mouse
                                │    ├── ScreenshotCommands  PNG, full-page, PDF
                                │    ├── CookieCommands      get/set/save/load/export/import
                                │    ├── NetworkTracker      request capture (Chromium only)
                                │    ├── Accessibility       a11y tree
                                │    └── CloudflareHandler   Turnstile (Chromium only)
                                ├── DeviceInfo              auto-detect screen/GPU/CPU/model
                                └── Stealth                 CDP-level UA/platform (Chromium)

Auto-Detected Device Info

Property	Source	Example
Model	`getprop ro.product.model`	SM-S918B
Screen	DPI ratio + model DB	1080x2316
GPU	`/sys/kernel/gpu/gpu_model`	Adreno740v2
CPU cores	`os.cpu_count()`	8
RAM	`/proc/meminfo`	11GB
Architecture	`uname -m`	aarch64

Test Results (2026-02-24)

All 5 test sites pass with Firefox (default):

Site	Result	Notes
example.com	PASS	Navigation, JS eval, links, text, scroll
bot.sannysoft.com	PASS	Navigation, scroll
audiogames.net	PASS	CF bypassed via TLS fingerprint
nowsecure.nl	PASS	CF bypassed via TLS fingerprint
platform.openai.com	PASS	Form filling, clipboard paste input

Firefox vs Chromium

Feature	Firefox	Chromium
Cloudflare	Instant (TLS)	Turnstile handler
audiogames.net	PASS	FAIL
Network tracking	Not available	Full CDP tracking
JS execution	Console + clipboard	CDP Runtime.evaluate
Stealth needed	None	UA + WebGL + canvas

File Structure

termux-browser-pilot/
├── cli.py                 # CLI entry point (daemon + legacy commands)
├── setup.sh               # One-command installer
├── pyproject.toml          # Python packaging
├── src/
│   ├── pilot.py           # Main unified API + session persistence
│   ├── daemon.py          # Persistent browser daemon (Unix socket)
│   ├── client.py          # Daemon client (send commands)
│   ├── native.py          # Firefox: xdotool + clipboard JS execution
│   ├── browser.py         # Xvfb + browser lifecycle
│   ├── cdp.py             # CDP WebSocket client (Chromium)
│   ├── commands.py        # Page commands (navigate, eval, text, html)
│   ├── input.py           # Keyboard/mouse + Bezier human-like input
│   ├── screenshot.py      # Screenshot/PDF capture
│   ├── stealth.py         # Anti-detection (Chromium only)
│   ├── cookies.py         # Cookie management + Netscape import/export
│   ├── cloudflare.py      # CF Turnstile handler (Chromium)
│   ├── network.py         # Network tracking (Chromium only)
│   ├── accessibility.py   # A11y tree access
│   ├── device.py          # Real device detection
│   ├── gpu.py             # WebGL renderer spoofing
│   ├── lock.py            # Session lock (single-instance)
│   ├── _utils.py          # Shared utilities (JS escaping, binary checks)
│   └── mcp_server.py      # MCP server for Claude Code integration
└── .mcp.json              # Claude Code auto-discovery config

Requirements

Termux on Android (aarch64)
Firefox mode: firefox, xorg-server-xvfb, xdotool, xclip, openbox, python3
Chromium mode: chromium, xorg-server-xvfb, mesa, python3, websockets>=12.0
openbox (lightweight WM) is required for reliable keyboard shortcut routing in Xvfb

Troubleshooting

SSL Certificate Errors (Firefox)

If Firefox shows "Warning: Potential Security Risk Ahead" on HTTPS sites, it means Firefox isn't using Termux's system CA certificates. The daemon automatically fixes this on startup (v0.17.2+), but if you're on an older version or have an existing profile, add this to ~/.tbp/firefox_profile/user.js:

user_pref("security.enterprise_roots.enabled", true);

Then restart the daemon:

tbp stop
tbp goto https://example.com   # auto-starts with fix applied

Make sure the ca-certificates package is installed:

pkg install ca-certificates

Daemon Won't Start

If the daemon fails to start, check the log:

cat ~/.tbp/daemon.log

Common fixes:

Kill stale processes: pkill -f Xvfb; pkill -f firefox; rm ~/.tbp/daemon.pid ~/.tbp/daemon.sock
Ensure Xvfb is installed: pkg install xorg-server-xvfb

License

MIT