Skip to content

Home

Jump to bottom
akwin1234 edited this page Jun 20, 2026 · 7 revisions

Documentation (docs/)

Part of Damru — the open-source, Android-native stealth browser automation framework (Redroid + Playwright + CDP) for web scraping, automation testing, and anti-bot / fingerprinting research.

Documentation index for the Damru open-source browser automation framework.

Welcome to the Damru knowledge base. This directory holds project documentation, architecture plans, roadmaps, and research notes.

Contents

  • CLI setup: Run python -m damru setup for guided first-run configuration, python -m damru install-deps for Linux/WSL dependencies, python -m damru install-image to load the baked Redroid image, python -m damru install-apks --download for raw Chrome/WebView/TTS APK assets plus Damru's shipped resetprop source when baking or using unbaked Redroid, python -m damru fix-wsl/fix-internet for safe Docker/binderfs/netfilter/DNS repair, python -m damru force-profile --device <slug> for applying a named profile to a running worker, python -m damru check-env to verify setup details, and python -m damru check preflight --json for fast read-only readiness checks across VPS/VM fleets. Preflight checks Docker, ADB, binder/binderfs, image/assets, resources, ports, config, and WSL kernel state without installing, mounting, starting containers, or editing networking.
  • APK assets: The raw APK bundle contains Chrome split-APK folders and matching per-version WebView/TTS/resetprop support APKs. Random profile actions rotate only through folders that include a matching WebView APK, and explicit --chrome-version selection fails if the matching WebView asset is missing.
  • WebView Shell support: python -m damru force-profile --browser-package org.chromium.webview_shell applies the normal Damru Android profile plus WebView-specific command-line and app_webview/pref_store hardening for WebView harness validation. For custom apps that embed system WebView, use the aligned baked image/APK bundle, apply force-profile --no-chrome, then launch the app manually. Chrome CDP remains the primary automation path.
  • Local UI: python -m damru ui starts the experimental localhost dashboard for setup health, worker actions, Work Lab URL/screenshot/quick-check flows, browser viewer, native viewer command copy, gallery cleanup, and inline logs. Work Lab URL launch uses stealth-open-url in default reattach mode: reuse/apply Damru stealth, detach CDP for first navigation, open with Android Chrome, then reattach CDP for inspection and manual automation. The backend is allowlisted and local-only by default; use it for setup/debugging/manual inspection, not as the stable automation API.
  • Current validation: On June 4, 2026, disposable Ubuntu WSL2 with Damru's bundled WSL kernel and native Ubuntu 24.04 VPS were both tested with fresh/reset setup flows, preflight, unit tests, two Redroid workers, quick-check, and open-url https://example.com. Debian 13 VPS was tested separately; Docker worked, but Redroid multi-container support failed because the stock Debian VPS kernel had CONFIG_ANDROID_BINDERFS disabled.
  • PROOF.md: Sanitized WSL/native Linux verification notes plus proof assets: Android screen recording, Example.com proof, and individual site screenshots for Amazon, Foot Locker/DataDome, Fingerprint Pro, Sannysoft, and CreepJS.
  • BROWSERS_BENCHMARK_REPORT.md: Sanitized external techinz/browsers-benchmark report showing a 10/10 Damru Redroid proxy-mode bypass run, with proxy credentials and IPs removed. The upstream benchmark project is credited for target definitions, checker structure, and report shape; Damru provides the Redroid adapter.
  • DEVICE_PROFILES.md: Full generated reference for the 155 Android device profiles available in damru/devices.py, including the latest 104-profile regional expansion validated on WSL Redroid. Default random selection uses the 100-profile premium pool; medium and experimental profiles are opt-in.
  • VIEWER.md: Optional screenshot, video recording, and scrcpy live-view workflows.
  • UI.md: Local dashboard guide with screenshots for Dashboard, Setup, Workers, Work Lab, Settings, and Logs.
  • WSL_KERNEL.md: WSL2 kernel requirements for Docker bridge/NAT networking and Redroid binderfs.
  • Image baking: Use python -m damru install-apks --download, then python -m damru bake-image --image damru-redroid:latest inside Linux/WSL2, then docker save damru-redroid:latest -o damru-redroid-latest.tar. The tarball is ignored by Git; keep damru-redroid-latest.tar.sha256 with the release artifact. The APK installer downloads the Chrome/WebView/TTS bundle to /home/damru/chrome-apks on Linux/WSL and copies Damru's shipped magisk.apk there when raw Redroid needs standalone resetprop. Keep the full bundle root together; do not deduplicate version-matched Trichrome library splits across Chrome folders. The bake/install path replaces the system WebView provider with the matching version and fixes WebView APK permissions/cache so Android does not reject it as a writable dex file.
  • AUTOMATION_GAPS_PLAN.md: Current automation status and roadmap, including what setup/check/repair flows already exist and what remains for later fleet or storage work.
  • Architecture notes: The README and Python API document the current CDP, Android prop, GPU, memory, proxy, WSL, and Redroid layers. Deeper internals should be added as focused docs when the implementation stabilizes.
  • CONTRIBUTING.md: Guidelines for contributing to the Damru ecosystem.

Keep this index focused on current user-facing docs. Historical notes should clearly say when they are no longer the recommended setup path.

FAQ

What is Damru? Damru is the first open-source, Android-native browser automation framework — it runs real Android (Redroid) in Docker and drives Chrome via the Chrome DevTools Protocol (CDP) with OS-level fingerprint spoofing, for authorized web scraping, automation testing, and anti-bot / fingerprinting research.

Which platforms are supported? Ubuntu 24.04 LTS is the only officially supported host — both native Linux and Ubuntu WSL2 with Damru's bundled WSL kernel pass all smoke tests. Debian 13 kernels currently lack CONFIG_ANDROID_BINDERFS, so they are not supported for Redroid multi-container pools.

Does Damru use JavaScript injection for spoofing? No. Damru's "Zero JS Injection" approach applies all spoofing at the OS level (resetprop, iptables), binary level (Vulkan/GLES patching), and protocol level (CDP). No Object.defineProperty hacks are used, eliminating the most detectable fingerprinting vector.

How do I get started? Install with pip install git+https://github.com/akwin1234/damru.git, then run python -m damru setup for guided first-run configuration. See PYTHON_API.md for the full API reference and the main README for the step-by-step deployment guide.

What anti-bot systems has Damru bypassed in documented tests? Damru achieved a 10/10 (100%) bypass rate against Google Search, Cloudflare, DataDome, Amazon, Ticketmaster/Imperva, Akamai, PerimeterX/HUMAN, Kasada, and Reddit. Full results are in the Browser Benchmark Report.

Related

Keywords: Android browser automation · stealth automation · antidetect · web scraping · Redroid · Playwright · CDP · fingerprinting research

📖 Documentation

📜 Project Metadata

Clone this wiki locally