# Intro
FIRERPA is an **all-in-one device control platform** for Android. The server runs directly on the device, **requiring no extra runtime dependencies**, and **works across multiple Android generations, with or without root**. The PC side orchestrates everything through a Python client library, consolidating capabilities such as UI automation, remote operations, traffic capture, hook-based reverse engineering, network proxy, distributed networking, AI Agent / **MCP** and more into a single service and API. Compared with piecing together self-written scripts and various operation tools like Appium, mitmproxy, frida-server, adb, uiautomator2, FIRERPA’s advantage lies in: **same origin capabilities, unified configuration, connected chains, and suitability for long-term multi-device operation and engineering management**.
```{hint}
This document introduces the platform positioning and core capabilities of FIRERPA. To install and get started, continue reading the [Quick Start](./quick-start.md) chapter.
```
## Remote Desktop & Real‑time Screen Casting
FIRERPA provides a browser‑based remote desktop that lets you view and control the device screen in real time without installing dedicated clients on the PC, supporting both LAN and cross‑network access. The screen casting pipeline supports both **MJPEG** and **H.264** encoding, with software and hardware encoding backends. You can adjust frame rate (up to 60 fps), resolution scaling, bit rate and quality according to device compute power and network conditions, significantly reducing bandwidth and improving smoothness in weak networks. It also supports **WebRTC** transport with configurable STUN/TURN servers to improve NAT traversal and end‑to‑end latency, making it suitable for public‑network and cross‑region remote debugging.
Remote desktop supports **concurrent multi‑user access**, facilitating collaborative troubleshooting, demonstrations, and training. It provides **bidirectional clipboard** sharing and **real‑time audio** streaming (Android 10+), and integrates operations like terminal, drag‑and‑drop file upload, directory browsing and download within the same web interface — daily operations can be done over a single port. The built‑in **visual layout inspector** highlights elements, enables Tab‑key traversal, shows coordinates and RGB values, and exports the XML layout tree. You can verify selectors and automation logic directly inside the remote desktop, drastically shortening the “look at the UI → write script” loop.
The remote desktop and RPC interfaces support **TLS end‑to‑end encryption** and service certificate access control, and you can define a custom WebUI login password to reduce exposure risks. Remote desktop capabilities can also be embedded into your own web application via WebSocket (real‑time video, touch, terminal, keys, etc.) and integrated cross‑origin through an `allow_origin` configuration, making it ideal for productizing real‑device control.
## UI Automation
FIRERPA provides a complete selector‑based automation system that supports common matching methods like text, resourceId, description, scrollable, and also **child / sibling** chain positioning to handle repetitive elements, complex hierarchies, or controls without distinct features. At the element level it supports fine‑grained operations such as screenshot, wait for appearance/disappearance, corner/center coordinate retrieval, and exists checks. It supports Unicode input, step‑based swipes, fling for quick page turning, scroll‑to‑bottom, and other interactions. It can **coexist with other accessibility services** on Android 8.0+ and enhances WebView node discovery, boosting automation success rates in hybrid apps.
**Watcher** can monitor UI changes in real time and automatically perform clicks, key presses, or counting when predefined conditions are met — useful for automatically dismissing protocol dialogs, update prompts, ad pages, and other interrupting flows. It supports combining multiple selector conditions, independent start/stop of watchers, and counting how many times a fleeting screen appears.
**Virtual Display** is one of FIRERPA’s differentiating features: you can create an independent background display on the device, run apps and automation scripts inside the virtual screen **without affecting normal use of the main screen** — for example, the virtual screen auto‑processes messages in the background while you watch videos or manually operate on the main screen. The virtual screen API is highly consistent with the main device API; existing `d.xxx` scripts can be smoothly switched to `vd.xxx`. Watchers can also be limited to a virtual display. The WebUI supports **multi‑screen display and switching**, allowing you to operate or view different Displays from the remote desktop, ideal for background keep‑alive, parallel tasks, and “foreground manual + background machine” hybrid scenarios.
For scenarios without a standard View tree (e.g., games, custom‑drawn UIs), FIRERPA provides **OCR** and **image matching** capabilities. OCR supports paddleocr, easyocr, and custom HTTP backends. In cluster deployments, recognition compute can be centralized on a server to avoid reloading models on each PC, with GPU acceleration and multiple text matching modes. Image matching runs **on the device** using template matching or SIFT, consuming no PC resources; SIFT is more robust to rotation, scaling, and lighting changes. It also offers **multi‑finger touch** capabilities, supporting trajectory recording, replay, code construction, and binary persistence, allowing expression of complex gestures and pressure values.
Architecturally, FIRERPA adopts a C/S model. Compared with solutions like AutoJS that run scripts solely on the device, FIRERPA is better suited for **centralized scheduling, version management, and cluster control**. It is more lightweight than Appium and offers **better stability** than uiautomator2 in multi‑device scenarios. FIRERPA is positioned as a **functional superset** of common Android automation approaches — automation, packet capture, hooking, and operations can be chained with code on the same platform, rather than switching between multiple tools.
## Packet Capture & MITM
FIRERPA offers **one‑click MITM packet capture**: automatically installs system‑level CA certificates, configures the proxy, handles Android version differences, and automatically restores the device network state on exit — no manual certificate installation or proxy switching required. It supports global capture, per‑package capture, real‑time packet modification, a shared mitmweb interface, and can route **international traffic** through a specified upstream HTTP proxy for capture. Built‑in **QUIC downgrade** reduces QUIC’s impact on capture. Even when PC and device can only communicate through a single FIRERPA port (e.g., ADB connect, frp forwarding), capture can still be performed, adapting to harsh network topologies.
Beyond one‑click scripts, all MITM‑related capabilities are also accessible through APIs: system‑level CA installation/removal works with formats from mitmproxy, Fiddler, Charles, etc. Capture flows can be embedded into automation pipelines and completed in the same task alongside UI operations and Frida hooks. A Windows `startmitm.exe` is provided without requiring Python, lowering the environment barrier.
## Networking, Proxy & Mesh
FIRERPA provides complete proxy capabilities on the device side, supporting **HTTP / HTTPS / SOCKS5 / Shadowsocks** (multiple encryption algorithms). It can proxy per app (including multi‑profile users), supports DNS proxy, UDP proxy, LAN bypass, coexistence with OpenVPN, and can **auto‑connect** a preset proxy when the service starts. Proxy capabilities support **IPv6 and UDP**, adapting to more complex network environments.
**Device HTTP bridge proxy (tunnel2)** provides reverse proxy: after pointing your PC or browser’s HTTP proxy to the phone, traffic is forwarded through the phone’s network exit, making the external IP the same as the phone’s, with optional Wi‑Fi or 4G (rmnet) as the outbound interface. This suits joint debugging, international business, multi‑device IP pools, etc.
Built‑in **OpenVPN client** supports certificate, username/password, and mixed authentication modes and can coexist with the system proxy. An **OpenVPN Docker image** and configuration generation script are provided to automatically produce device‑side connection code and auto‑start configuration, reducing errors when writing OpenVPN configs manually. A built‑in **frp client** can forward device services to a public server with `fwd.*` configuration, supporting encryption and TLS.
**mDNS service discovery** is provided: when enabled, services like remote desktop can be accessed via `{device_id}.local` domain names, with optional TXT metadata (model, ABI, device ID, etc.) for easy bulk discovery and management on the LAN.
## Frida & Reverse Engineering
FIRERPA **includes the latest Frida built‑in**, so there’s no need to deploy frida‑server separately. Frida commands can be used directly in the remote desktop terminal without cumbersome `-U`, `-H` flags. It integrates open‑source hiding patches and proprietary stealth capabilities, with continuous iteration to counter detection. Connections use token authentication and are securely accessed through the FIRERPA port. Objection patches and a Frida 17.x java‑bridge wrapper tool are provided to reduce migration costs caused by official changes.
**Frida script persistence** is supported: scripts can be automatically re‑injected after an app crashes or exits. YAML offline persistence, directory monitoring, and hot‑reload are supported. Frida RPC can be **mapped as Python methods** and supports **HTTP + JSON‑RPC 2.0** remote invocation, executing in JVM threads, UI main thread, or pure JS contexts. Data emitted by a script via `emit` can be reported to **HTTP / Redis / RabbitMQ (MQTT)**, carrying device and app metadata, with support for zlib compression, HTTP retry, and MQTT TLS.
## ADB, SSH & Built-in Terminal
FIRERPA provides a **built‑in ADB service independent of the system ADB**, allowing high‑privilege ADB connections over the network **without enabling Developer Mode**, helping to avoid “Developer options” type detections. A Magisk module can pre‑install `adb_keys` for default authorization. A built‑in **SSH service** and `ssh.sh` / `scp.sh` helper scripts facilitate remote shell and file transfer.
The **built‑in terminal** comes pre‑installed with common analysis tools like strace, ltrace, tcpdump, scapy, fsmon, frida‑tools, MemDumper, and integrates Python ecosystem libraries such as Crypto, cv2, unicorn, capstone, keystone, redis, grpc. sqlite3 supports **wxsqlite / sqlcipher / sqlcrypto**, providing a path to read encrypted databases like those of WeChat, WeCom, Alibaba apps, etc. The built‑in terminal is unified with remote desktop, SSH, and ADB, allowing analysis and self‑control to be performed directly on the device, reducing back‑and‑forth between PC and device.
## Distributed & Multi‑Device Management
FIRERPA’s **Starlink Platform (Hub + hub-bridge)** provides a centralized multi‑device access solution, supporting unified management and **P2P** access for both local and remote devices, ideal for “device at home, person away” and multi‑machine collaboration. Hub v3 uses **SAPI** for unified requests and can connect to both local and remote devices simultaneously. Besides Hub, two additional self‑hosted solutions — **frp forwarding** and **OpenVPN networking** — are supported, with complete documentation and Docker accompaniments.
Since v9.0, **P2P Bridge endpoint interconnection** and a **built‑in distributed task system** are supported; since v7.50, a networking subscription service is available, eliminating the need to self‑host frp/OpenVPN. The overall design targets **bulk device, always‑online, unattended** scenarios such as cloud phone pools, real device farms, and emulator clusters.
## AI / MCP / Agent
FIRERPA **includes an MCP server** (API path `/mcp/`), using the **streamable-http** protocol, supporting tool calls, resource read, prompts, progress notifications, and logging. It can integrate with MCP clients such as **Claude, Cursor**, etc. Official MCP extension modules are provided, and custom plugins can be placed under `~/modules/extension`.
The built‑in **`agent` command** connects to any OpenAI‑compatible API + tool call, driving device operations in **natural language**, with **Vision** mode support. An **OpenAI semantic task executor** is also provided, which can be combined with **crontab** to schedule AI tasks, embedding large model capabilities into real‑device automation pipelines.
## System‑Level Control & Extensions
FIRERPA offers **160+ Python APIs** covering app operations, file I/O, command execution, device status, WiFi, proxy, OpenVPN, shutdown/reboot, service logs, and more. `setprop` can write **`ro.*`** read‑only system properties; the Settings API can read/write brightness, developer mode, and other system settings. **SELinux** support includes domain creation, permissive toggling, and fine‑grained allow/disallow rules. The full API works with multi‑profile apps, silent permission granting/revoking, launching unexported activities, and disabling apps to save resources.
**Binary patching** (hex wildcards, glob paths, dry‑run), along with collection of **runtime metrics** such as disk, battery, CPU, memory, network I/O, are provided. WAV audio playback and internal storage APIs are supported. **tflite‑runtime** is integrated on the device and can use hardware acceleration for on‑device inference.
A **virtual Debian environment** can run a full Debian distribution with apt inside the device, allowing compilation of BPF, deployment of OpenSSH, and execution of arbitrary Python dependencies, breaking the limitation that the built‑in terminal cannot use pip/apt.
## Deployment, Security & Governance
FIRERPA supports multiple deployment methods: **one‑click APP deployment** (root or Shizuku), **auto‑start Magisk module**, manual extraction, and **ROM integration** — all designed for **7×24** always‑on operation. The APP can **auto‑generate service certificates**; Magisk zip files can pre‑package properties configuration, lamda.pem certificate, and adb_keys. All behavior is centrally managed through an **ini‑format service configuration**: port, WebUI parameters, certificates, OpenVPN, gproxy, frp, tunnel2, cron, sshd, adb, mdns, etc. The WebUI supports visual editing, raw text mode, and hot‑reload of services via “Reload Service”, as well as loading configurations from a remote file server.
Dual‑identity operation (root and shell) is supported. It covers arm64, armeabi‑v7a, x86, x86_64 architectures and is compatible with real devices, emulators like LDPlayer/Nox, Redroid, WSA, AVD, cloud phones, and other environments. Uninstall follows a clean path, leaving no junk files scattered across the system. An **API exclusive lock** prevents multiple clients from competing for the same device. The privacy policy clearly states that no personal private data such as contacts, SMS, or location is collected, and **offline authorization** is supported.
## Continuous Evolution
FIRERPA has been continuously evolving for over **6 years**, covering Android 14–16 compatibility fixes, with ongoing iteration in areas like multi‑user remote desktop, standardized touch API, MCP protocol, Frida versioning and stealth, proxy IPv6/UDP, P2P Bridge, distributed tasks, and more.
FIRERPA’s core advantage is not a single feature, but the integration of **remote desktop (WebRTC/H.264/multi‑user), UI automation (including Virtual Display, Watcher, OCR, image matching, multi‑finger touch), one‑click capture, built‑in Frida, full‑stack proxy and VPN/frp/P2P networking, ADB/SSH/built‑in terminal, AI MCP/Agent, system‑level control, virtual Debian, persistent KV, script encryption** and more on the same Android device, within the same service and the same Python client. This allows security testing, compliance analysis, protocol reconstruction, bulk management, and automation to be completed in **one pipeline** rather than repeatedly stitching together multiple tools.