dorker 0.1.3

Install

Requires Rust 1.85+ and ~/.cargo/bin on your PATH.

cargo install dorker

Verify:

dorker --help

git clone https://github.com/cesarferreira/dorker.git
cd dorker
cargo install --path . --locked
# or
make install-release

Debug install (faster compile, larger binary):

make install

Run without installing:

make build-release
./target/release/dorker

Quickstart

Requires the Android SDK (emulator, platform-tools) and an installed system image (dorker pull installs one). macOS Apple Silicon and Linux x86_64 with KVM are validated. No Docker needed.

dorker doctor                                   # check your setup
dorker pull android:35                          # install a system image if missing
dorker run -d --name test android:35            # boots a headless emulator
dorker ps
dorker exec test "getprop ro.build.version.sdk"
dorker install test ./app-debug.apk
dorker screenshot test shot.png                 # waits up to 10s for a non-blank frame (--wait 0 to skip)
dorker logs test                                # add -f to follow
dorker stop test
dorker start test                               # cold boots again, keeps its data
dorker rm test

Describe your environment in a Dorkerfile

A Dorkerfile (next to your app, like a Dockerfile) declares the Android environment: the base image, resources, the APK to install, settings, and a snapshot to start from.

# Dorkerfile
FROM android:35                 # Android 35 system image (install it with: dorker pull)

MEMORY 2GB                      # guest RAM
CPUS 2
DISK 4GB
DEVICE pixel_7
RESOLUTION 1080x2400
HEADLESS true                   # no emulator window

INSTALL ./app/build/outputs/apk/debug/app-debug.apk   # path is relative to this file's folder

SETTING window_animation_scale 0        # make UI tests faster and less flaky
SETTING transition_animation_scale 0
SETTING animator_duration_scale 0

SNAPSHOT ready                  # save a snapshot, so instances start in a few seconds
CMD launch com.example.app      # open this app once an instance is ready

Then build the image once and run it as many times as you like:

dorker pull                                 # installs the Dorkerfile's FROM image if it is missing
dorker build -t myapp:latest .              # reads ./Dorkerfile, writes Dorkerfile.lock
dorker run -d --name t1 myapp:latest        # starts from the snapshot in a few seconds
dorker screenshot t1 shot.png               # the app is already open
dorker test t1 --runner com.example.app.test/androidx.test.runner.AndroidJUnitRunner
dorker rm -f t1                             # throw it away

dorker run --rm myapp:latest                # or: foreground, removed when you press Ctrl-C

An identical rebuild is a cache hit (instant), and every dorker run gets its own isolated copy, so instances never share state. To try it without your own app, use the sample:

examples/basic/make-apk.sh                  # builds a tiny sample APK (needs Android build-tools + a JDK)
dorker build -t basic examples/basic
dorker run -d --name b1 basic && dorker exec b1 "pm list packages | grep dorker"
dorker rm -f b1

Every directive is documented in docs/dorkerfile.md. More examples: examples/basic, examples/instrumentation and examples/counter-app, a real Gradle app with Espresso tests (./dev.sh runs Gradle, dorker build, run, a screenshot and the tests). The example APKs are not committed: build them with each example's make-apk.sh (or Gradle for the counter app).

Each instance gets its own private AVD under ~/.dorker (override with DORKER_HOME). Your existing AVDs are never touched. dorker run --rm removes the instance when it stops. ps, images and doctor accept --json.

Measured on an Apple M4 Pro, API 35, 2GB: cold boot about 15s, snapshot restore about 4s. Host memory is about 2.5GB after a cold boot and 3.3GB after a restore. Details and caveats: docs/benchmarks.md.

Test, benchmark, automate

dorker init                                   # starter Dorkerfile
dorker test t1 --runner com.example.test/androidx.test.runner.AndroidJUnitRunner
dorker test t1 --runner ... --class com.example.FooTest#bar
dorker bench myapp:latest --runs 3 --json     # boot, restore, launch, disk, idle usage
dorker bench android:35 --baseline            # also time the plain official emulator

dorker test prints a summary, preserves the raw instrumentation output and logcat under the instance directory, and exits 7 if anything failed. See examples/instrumentation for a runnable example.

Tests

cargo test                          # unit, CLI and fake-SDK lifecycle/failure tests (no emulator needed)
cargo test -- --ignored --test-threads=1   # end-to-end: boots real emulators (~2 min)

Use it from AI agents

dorker mcp is a Model Context Protocol server: an agent can start instances, install apps, run commands, take screenshots, read logs and run tests, all with structured results.

claude mcp add dorker -- dorker mcp

See docs/mcp.md for the tools, other clients and security notes. The same operations are available to scripts as --json on run, start, exec, install, screenshot, test, ps, images, doctor and bench.

Diagnostics

dorker -v <command> (or DORKER_VERBOSE=1) prints what dorker decides and runs to stderr: the located SDK, the boot mode and why, the exact emulator command line and environment, state transitions and timings. Each instance also keeps its raw emulator output in ~/.dorker/instances/<id>/emulator.log.

Exit codes

dorker exec returns the guest command's own exit status.

See docs/architecture.md for design and limitations.

Limitations

• Platform: validated on macOS Apple Silicon (primary) and Linux x86_64 with KVM (Ubuntu 24.04, an Azure VM with nested virtualisation; unit tests and the full emulator end-to-end suite pass). Linux arm64 and bare-metal Linux are untested; Windows is unsupported. Linux is slower in our measurements (cold boot about 29s, snapshot restore about 9s; see docs/benchmarks.md).
• System images are installed on request, not automatically. dorker pull android:35 runs the SDK's sdkmanager (needs the command-line tools and may prompt for licences); dorker run/build print this command when an image is missing. The download path itself was only verified for the already-installed and nonexistent-package cases, not a real multi-GB download.
• Snapshots are strict. A change of emulator version, system-image revision, memory or CPUs invalidates an image's snapshot. dorker then cold boots (about 15s) and says so. Snapshots are host-specific and not portable between machines.
• Memory: a 2GB guest used about 2.5GB of host memory after a cold boot and 3.3GB after a snapshot restore on macOS (3-3.7GB on Linux). Idle CPU is dominated by Android background work and takes about a minute to settle.
• Builds take about 45s because dorker reboots the guest to persist provisioned state.
• CMD only supports launch <package>. dorker start always cold boots (about 14s) because restoring the image snapshot would roll back the instance's data. There is software rendering (swiftshader_indirect) is the default; GPU <mode> in the Dorkerfile selects another, but none was faster for snapshot restore in our measurements (see docs/benchmarks.md) and no automatic test-APK discovery.
• Concurrency: creating instances concurrently is safe, and stop, rm and start on the same instance are serialised by a per-instance lock (the second command waits up to 60s, then exits 8).
• Orphans: emulator processes that dorker started but lost track of (CLI killed mid-start) are reported by dorker ps, not adopted or killed automatically.
• examples/basic and examples/instrumentation use tiny hand-built APKs; examples/counter-app is the realistic one.

Development

Common tasks via the Makefile:

make              # check + build + test
make build        # debug build
make build-release
make install      # install debug binary
make install-release
make run ARGS="doctor"
make check        # cargo check + clippy
make fmt          # format
make lint         # fmt check + clippy
make test
make clean
make demo         # install + show --help

Releasing (requires cargo-release and git-cliff):

make release                  # default minor bump
make release LEVEL=patch      # patch bump
make release LEVEL=major      # major bump

The pre-release hook regenerates CHANGELOG.md with git-cliff from your conventional-commit history (grouped into Features, Bug Fixes, etc. per cliff.toml) and commits it alongside the version bump. Pushing the resulting v* tag triggers the release workflow, which builds the multi-platform binaries and publishes a GitHub Release whose notes are generated by git-cliff from the same config.

License

MIT