Installing Damru — Full Setup Guide for Ubuntu and WSL2

Damru installs on Ubuntu 24.04 LTS (native Linux) or Ubuntu 24.04 inside WSL2 with Damru’s bundled WSL kernel — Redroid, the Android-in-Docker layer that powers all stealth sessions, requires Linux kernel support for binderfs that is only reliably present on these two tested paths.

Follow this guide top to bottom on a fresh host. The python -m damru install-deps command automates the Docker, ADB, binderfs, and iptables steps, so most users only need to run a handful of commands.

Supported Host Environments

Redroid is Linux-only. On Windows, Docker and Redroid must live inside WSL2. Native Windows Docker is not a supported Redroid backend.

Minimum System Requirements

Damru runs one full Android 14 container per worker. The default Redroid worker limit is 2 CPU cores and 2 GB memory per container.

Scaling rule: budget ~2 vCPU per active Redroid worker plus 1–2 vCPU for Docker, ADB, Python, and the host OS.

Current release artifact sizes:

• damru-redroid-latest.tar — ~1.2 GB as an exported Docker tarball; expands after docker load.
• chrome-apks.zip — ~3.3 GB; needed only for raw/unbaked Redroid, image baking, or APK rotation.

Step 1 — Prepare System Packages

Update the system and install the tools Damru needs:

sudo apt update && sudo apt upgrade -y
sudo apt install -y adb wget curl git jq python3-venv

On WSL2, these steps run inside your Ubuntu distro. Damru’s WSL kernel installer also writes dnsTunneling=true and networkingMode=NAT into %USERPROFILE%\.wslconfig to avoid a common DNS failure. Run wsl --shutdown after kernel or DNS changes, then reopen Ubuntu.

Step 2 — Install Docker and Enable Binderfs

Prefer python -m damru install-deps (Step 4); it handles Docker, binderfs, and iptables automatically. The manual steps below are for debugging or custom Linux images only.

Install Docker

curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh
sudo usermod -aG docker $USER

Log out and log back in, or run newgrp docker to apply group permissions before testing Docker.

Mount Binderfs (Required for Redroid)

Redroid needs Android’s binderfs kernel subsystem to run multiple containers. Without it, a second Redroid container may appear in ADB but fail Android userspace (zygote, system_server, Chrome/CDP):

sudo mkdir -p /dev/binderfs
sudo mount -t binder binder /dev/binderfs

To make binderfs persistent across reboots, add it to /etc/fstab:

binder    /dev/binderfs    binder    defaults    0    0

DamruPool(max_devices > 1, mode="auto") requires real binderfs support — not just the presence of /dev/binder, /dev/hwbinder, and /dev/vndbinder device nodes. Damru checks this before starting a multi-worker pool and will tell you to use max_devices=1 or boot a binderfs-enabled kernel if the check fails.

Step 3 — Download and Load the Pre-Baked Redroid Image

The recommended path is the pre-baked damru-redroid:latest Docker image. It already contains Chrome, WebView/TTS assets, custom fonts, native GPU/memory patches, and warm Chrome preferences. No separate Chrome APK bundle is required for normal use.

Option A — Automatic (Recommended)

python -m damru install-image

install-image searches for damru-redroid-latest.tar in the current directory, parent directory, project root, home directory, and ~/Downloads. It verifies the SHA-256 checksum and runs docker load inside Linux/WSL. If the tarball is not local:

python -m damru install-image --download

Option B — Manual Load

Download damru-redroid-latest.tar from damru.dev/assets/damru-baked.tar.gz, then load it:

sha256sum -c damru-redroid-latest.tar.sha256
docker load -i damru-redroid-latest.tar

For WSL2 users: copy or move the tarball inside your WSL distro before running docker load. Native Windows Docker is not used; Docker runs inside WSL.

Verify the Image

docker images | grep damru-redroid

You should see damru-redroid latest in the output.

Step 4 — Install Damru (Python Package)

Option A — Pip Install (Recommended)

sudo apt install -y python3-venv
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -U pip setuptools wheel
pip install git+https://github.com/akwin1234/damru.git

Use a virtual environment. Ubuntu 24.04 enforces PEP 668 externally-managed environments, so installing to system Python will fail.

Windows/older setuptools fix: if you hit AssertionError: ...distutils\core.py during install, upgrade packaging tools first:

python -m pip install -U pip setuptools wheel
pip install git+https://github.com/akwin1234/damru.git

Do not set SETUPTOOLS_USE_DISTUTILS=stdlib globally on modern Python.

Option B — Developer / Editable Install

git clone https://github.com/akwin1234/damru.git
cd damru
python3 -m venv venv
source venv/bin/activate
python -m pip install -U pip setuptools wheel
pip install -e .
python -m damru setup --skip-deps

When you import Damru, it verifies and applies the bundled Playwright crPage.js patch used to reduce CDP target discovery leaks.

Step 5 — Run Setup and Verify

python -m damru install-deps
python -m damru install-image
python -m damru setup
python -m damru check-env
python -m damru check preflight

install-deps is idempotent — on a fresh install it sets up Docker, ADB, binderfs, iptables, and Playwright. On later runs it rehydrates Docker and binderfs after WSL restarts without reinstalling packages.

setup runs dependency setup by default and writes a working config.py. Pass -y for non-interactive mode:

python -m damru setup -y

For scripted non-interactive installs where sudo cannot prompt, pass the password on stdin:

printf '%s\n' 'your-sudo-password' | python -m damru setup -y --sudo-password-stdin

For a specific WSL distro and user:

python -m damru setup -y --wsl-distro Ubuntu --wsl-username your-wsl-user

Global Configuration

Damru uses damru/config.py. OS-specific templates are included:

• Windows / WSL2: copy damru/config.py.windows and rename it to config.py.
• Native Linux: copy damru/config.py.linux and rename it to config.py.

Key Settings

WSL2 settings (Windows auto-mode):

# damru/config.py
WSL_DISTRO = "Ubuntu"
WSL_USERNAME = "your-wsl-user"
WSL_PASSWORD = ""  # kept for compatibility; setup uses wsl -u root

Chrome APK path (needed only for raw/unbaked Redroid):

CHROME_APK = None  # auto-searches chrome-apks/ in the project root
# Or specify an absolute path:
# CHROME_APK = "/home/damru/chrome-apks/145.0.7632.75"

Pool settings:

MODE = "auto"                          # "auto" manages Docker containers
NUM_DEVICES = 10                       # concurrent containers
REDROID_IMAGE = "damru-redroid:latest" # Docker image to use

Proxy, timezone, and locale:

PROXY = None       # optional SOCKS5/HTTP proxy for Python-side checks
HTTP_PROXY = None  # optional Android system HTTP proxy as host:port
TIMEZONE = None    # auto-derived from proxy exit when unset
LOCALE = None      # auto-derived from proxy country when unset

Leave TIMEZONE and LOCALE as None — Damru resolves them from the active proxy exit at session start and rechecks through Chrome after CDP connects.

Docker Storage (WSL2 Users)

Redroid container images and layers are stored in the WSL ext4.vhdx virtual disk on your C: drive by default, which can fill up quickly. To move Docker data to a secondary drive:

1. Open WSL: wsl -d Ubuntu
2. Stop Docker: sudo service docker stop
3. Move existing data: sudo mv /var/lib/docker /mnt/d/docker-data
4. Symlink it back: sudo ln -s /mnt/d/docker-data /var/lib/docker
5. Start Docker: sudo service docker start

Raw APK Bundle (Advanced — Image Baking Only)

Normal users do not need the APK bundle — the baked image already has everything. Use the bundle only when baking a custom image, recovering from an APK asset error, or working with unbaked raw Redroid containers.

python -m damru install-apks --download

install-apks downloads the Chrome/WebView/TTS APK bundle (~3.3 GB), extracts it to /home/damru/chrome-apks on Linux/WSL, copies Damru’s shipped magisk.apk as the local resetprop source, and validates the top-level APKs and Chrome split-APK folders.

Expected bundle layout after extraction:

chrome-apks/
  148.0.7778.178/
    base.apk
    split_chrome.apk
    google_trichrome_library.apk
    webview.apk
    vanadium_trichrome_library.apk
  google_tts.apk
  espeak.apk
  rhvoice.apk
  magisk.apk

Chrome rotation only uses version folders that include a matching webview.apk or TrichromeWebView.apk. Folders without a matching WebView asset are skipped by random rotation and reported by check preflight.

Troubleshooting Common WSL2 Errors

Binderfs device not found

docker: Error... no such device

sudo mkdir -p /dev/binderfs
sudo mount -t binder binder /dev/binderfs

Docker iptables / network failure

python -m damru fix-wsl

Damru selects a Docker-compatible iptables backend (nft on native Linux, legacy on most WSL kernels where Docker’s addrtype NAT rule fails through nft).

Missing WSL kernel module (xt_addrtype not found)

python -m damru fix-wsl

If the module is still missing, see the WSL2 Kernel Notes in the upstream repo. Damru falls back to a no-iptables/no-bridge Docker mode for WSL hosts that lack Docker bridge/NAT support.

Permission denied on Docker socket

sudo usermod -aG docker $USER
# Restart WSL after running this

If Docker works with sudo but check-env still reports a socket permission failure, open a new login shell or reconnect SSH to pick up the new group.

DNS failures inside Docker or WSL

python -m damru fix-internet

fix-internet repairs WSL/Docker/Android DNS state for one worker or all online workers.

Verifying ADB Device Detection

After loading the image and starting a container, check ADB:

adb connect localhost:5555
adb devices
# Expected: localhost:5555    device

Damru auto-detects virtual devices only: TCP Redroid endpoints (127.0.0.1:5600, 127.0.0.1:5601, …) first, then emulator-* serials. Physical-looking USB serials are refused by default. Set DAMRU_ALLOW_PHYSICAL=1 only for an intentionally disposable test device.

On WSL2, Redroid workers appear as wsl:127.0.0.1:5600, wsl:127.0.0.1:5601, etc. On native Linux they appear as 127.0.0.1:5600, 127.0.0.1:5601, etc.

Related

• Getting Started — quickstart: first AsyncDamru session in minutes
• CLI Reference — all python -m damru subcommands
• Python API — AsyncDamru, Damru, DamruPool, and device helpers