lamda

Establishes secure gRPC communication channels between a Python client and an Android device server, enabling structured RPC calls for device automation. The architecture uses protocol buffers (protobuf) to define service interfaces and message schemas, allowing type-safe serialization of commands and responses across the network boundary. Connection management handles SSL/TLS encryption, session lifecycle, and automatic reconnection logic.

Parses Android's accessibility tree (UIAutomator2 hierarchy) to locate UI elements by XPath, text content, resource ID, or class type, then executes touch interactions (click, long-press, swipe) with pixel-perfect coordinates. The system maintains a cached hierarchy snapshot and computes element bounds dynamically, supporting both absolute and relative positioning. Interaction commands are translated to ADB input events or UIAutomator2 API calls depending on device state.

Provides a plugin architecture for registering custom tools and extensions that extend LAMDA capabilities. Extensions are Python modules that implement a standard interface and register themselves with the LAMDA client. Supports both built-in extensions (Frida, MITM proxy) and user-defined extensions. Extensions can hook into device lifecycle events, add new RPC methods, or provide custom UI automation strategies. Extension discovery and loading is automatic from configured extension directories.

Streams Android logcat output in real-time with filtering by package name, log level, and tag. Parses logcat events and provides callbacks for specific log patterns (crashes, errors, warnings). Supports persistent log capture to files and log rotation. Enables event-based automation by triggering actions when specific log patterns are detected (e.g., app crash, network error). Integrates with crash detection to automatically capture crash logs and stack traces.

Automatically detects device capabilities (Android version, screen size, installed apps, hardware features) and stores configuration in a device profile. Profiles are used for device allocation in multi-device scenarios and for adapting automation strategies to device capabilities. Supports manual capability definition and override for devices with non-standard configurations. Provides capability-based device filtering for test allocation (e.g., 'only run on Android 12+ devices with 6GB+ RAM').

Manages Android app installation, launching, stopping, and uninstallation through ADB package manager (pm) and activity manager (am) commands. Provides granular permission control by reading/writing manifest files and using pm grant/revoke commands. Supports app instrumentation for code coverage and performance monitoring by injecting instrumentation runners and collecting execution traces. Handles app state transitions (foreground, background, stopped) and monitors app crashes via logcat parsing.

Integrates with mitmproxy to intercept and modify HTTP/HTTPS traffic from Android apps by configuring device-level proxy settings and installing custom CA certificates. Supports request/response filtering, header injection, body modification, and traffic recording. The proxy can be configured globally via device properties or per-app through network configuration. Handles SSL/TLS certificate pinning bypass through Frida hooks or certificate installation.

Integrates Frida framework to inject JavaScript code into running Android processes for runtime hooking, method interception, and behavior modification. Supports hooking Java methods, native functions, and system calls to inspect arguments, modify return values, or redirect execution. Frida scripts are compiled to bytecode and injected into target processes via the Frida daemon running on the device. Supports both attach-mode (inject into running process) and spawn-mode (start process with hooks).

Executes arbitrary shell commands on the Android device via ADB shell, with support for reading/writing system properties (getprop/setprop), modifying system settings (settings get/put), and accessing SELinux contexts. Commands are executed in the device's shell environment with output captured and parsed. Supports both synchronous command execution with timeout and asynchronous execution with callback handlers. Provides helpers for common operations like changing system time, enabling developer options, or modifying network settings.

Captures device screenshots in PNG format via ADB screencap command and returns pixel data for analysis. Provides visual hierarchy inspection by parsing the accessibility tree and overlaying element bounds on screenshots. Supports OCR (Optical Character Recognition) for text extraction from screenshots, enabling text-based element detection when accessibility tree is unavailable. Screenshots can be annotated with element IDs, bounds, or text content for debugging.

Manages multiple Android devices as a pool, distributing automation tasks across devices for parallel execution. Provides device allocation logic (round-robin, least-busy, capability-based) and handles device lifecycle (connect, disconnect, reset). Supports device grouping by capabilities (screen size, Android version, installed apps) and task scheduling based on device requirements. Includes health monitoring to detect offline or unresponsive devices and automatic failover to healthy devices.

Exposes LAMDA capabilities as MCP server tools, enabling AI agents (Claude, other LLMs) to control Android devices through natural language instructions. Implements MCP tool definitions for UI automation, app management, and system control, with automatic parameter validation and error handling. Translates AI agent requests into LAMDA API calls and returns structured results for agent decision-making. Supports tool use chains where agents can sequence multiple LAMDA operations based on intermediate results.

Establishes SSH tunnels to Android devices for secure remote access, enabling LAMDA client connections through firewalls and NAT. Supports port forwarding to expose LAMDA server ports through SSH tunnels, with automatic tunnel establishment and reconnection. Provides SSH key-based authentication and password authentication options. Integrates with OpenVPN for additional network security and device access across geographically distributed networks.