Note
Termu-inator is a fork of
Termux Browser Pilot by
salviz and the Termux Browser Pilot contributors. The fork starts from
upstream main commit
b95eccd3d1abc188c3aa488a23c519ebacc99fcf.
This README and the tbp interfaces still describe the preserved upstream
baseline while Termu-inator is being modernized. See the
upstream baseline record and
attribution notice.
The fork's current position and next step are in STATUS.md; the plan is in task_plan.md.
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.
- Persistent daemon — browser stays running, sub-second commands
- Passes Cloudflare — Firefox: instant TLS-based pass; Chromium: Turnstile handler
- No geckodriver service — Firefox uses an owned loopback BiDi session plus X11 input
- AI-friendly —
--jsonflag 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
Use the fail-closed installer from a trusted checkout. It creates separate CLI and MCP venvs and uses Termux's native Android cryptography package.
bash setup.shThe installer refuses to overwrite existing environments. See the complete Termux installation and verification guide, including the Tailscale split-tunneling prerequisite and Hermes MCP path. Hermes and Codex observer/interactive profiles, Tailscale SSH stdio, and bounded artifact recovery are documented in the integration guide. Safe update, rollback, data-reset, DNS, ABI, and stdio diagnostics are in the operations and troubleshooting guide.
The MCP venv installs both the legacy tbp-mcp compatibility command and the
explicit compact-alpha tbp-mcp-v1 command. Keep the legacy path for current
device compatibility; select compact v1 only for the staged 14-tool contract
and follow the guide's separate Developer Mode availability/origin gates.
Compact v1 can also start a default-OFF, read-only shared view on Android
loopback with --shared-view. It shows cached browser state and a bounded
screenshot/trace summary, exposes no action or approval routes, and suppresses
page content during confidential takeover. See the installation guide for the
SSH local-forwarding pattern used from a Mac over Tailscale.
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 shutdownimport 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())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())# 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_statusUse ~/.venvs/termuinator-mcp-v1/bin/tbp-mcp. The supported extra pins
mcp==1.29.0 and intentionally omits MCP's CLI extra; see
docs/termux-install.md.
| 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) |
| 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 |
| 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 |
| Command | Description |
|---|---|
screenshot [PATH] [--full] |
Screenshot (viewport or full page) |
screenshot-element SELECTOR [PATH] |
Screenshot specific element |
pdf [PATH] |
Export page as PDF |
| Command | Description |
|---|---|
block PATTERNS... |
Block URL patterns (domains/substrings) |
unblock PATTERNS... |
Remove blocked patterns |
blocklist |
List current blocked patterns |
| 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 |
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 |
| 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 |
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 |
Sets files on <input type="file"> elements via JS DataTransfer API. Max 5MB.
| Command | Description |
|---|---|
upload SELECTOR PATH |
Upload file to file input |
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 |
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 |
| 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 |
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 |
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) |
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 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.
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 |
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.
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.
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 |
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 |
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).
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.
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.
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 |
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.
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).
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.
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).
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.
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.
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.
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.
| 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.
| Command | Description |
|---|---|
check SELECTOR |
Check a checkbox or radio |
check SELECTOR --action uncheck |
Uncheck |
check SELECTOR --action toggle |
Toggle |
| Command | Description |
|---|---|
input-value SELECTOR / iv |
Read current value of input/select/textarea |
Returns {value, tag, type}.
| Command | Description |
|---|---|
element-state SELECTOR / es |
Query element visibility/enabled/checked state |
Returns {visible, enabled, checked, editable, tag, type}.
| Command | Description |
|---|---|
bounding-box SELECTOR / bb |
Get element position and dimensions |
Returns {x, y, width, height, top, left, bottom, right, scrollX, scrollY}.
| 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.
| Command | Description |
|---|---|
set-content HTML |
Replace page with raw HTML (no navigation) |
set-content @file.html |
Load HTML from file |
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 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.
Chain commands into reusable JSON scripts (max 100 steps).
| Command | Description |
|---|---|
macro FILE |
Run macro from JSON file |
| 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 |
Be real, not fake. Firefox runs as the owned browser process without a
geckodriver or Marionette service. A browser-assigned loopback WebDriver BiDi
session provides navigation and JavaScript-backed observation; xdotool remains
responsible for X11-native input and ImageMagick captures the window. The
DevTools-console/clipboard evaluator is retained only when the Remote Agent is
unavailable. Enabling the Remote Agent makes navigator.webdriver observable,
so this is a reliability design rather than an anti-detection claim. Chromium
uses real device hardware info with only webdriver=false hidden.
CLI (cli.py) ──Unix socket──→ Daemon (daemon.py)
├── Pilot (unified API)
│ ├── BrowserPilot Xvfb + openbox WM + browser lifecycle
│ ├── NativeFirefoxSession loopback BiDi + X11 input (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)
| 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 |
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 |
| Feature | Firefox | Chromium |
|---|---|---|
| Cloudflare | Instant (TLS) | Turnstile handler |
| audiogames.net | PASS | FAIL |
| Network tracking | Not available | Full CDP tracking |
| JS execution | Loopback BiDi; console fallback | CDP Runtime.evaluate |
| Stealth needed | None | UA + WebGL + canvas |
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: loopback BiDi evaluation + X11 compatibility
│ ├── firefox_bidi.py # Bounded browser-owned WebDriver BiDi client
│ ├── 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
- 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
For the compact alpha, Tailscale DNS, native cryptography, update/rollback, and safe data handling, use the dedicated operations and troubleshooting guide. The notes below describe only the preserved legacy surface.
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 appliedMake sure the ca-certificates package is installed:
pkg install ca-certificatesIf the daemon fails to start, check the log:
cat ~/.tbp/daemon.logCommon fixes:
- Use
tbp stopfirst. If state remains, follow the identity-checked lifecycle procedure; do not kill unrelated Xvfb/browser processes or delete live sockets by pattern. - Ensure Xvfb is installed:
pkg install xorg-server-xvfb
MIT. The original upstream notice is preserved in LICENSE. See NOTICE.md for fork provenance and attribution.