Hydra Lab: Microsoft's Self-Hosted Cloud Testing Framework for Mobile

Center-Agent Design and How Device Pools Form

Hydra Lab separates its responsibilities into two distinct roles. The center is a Spring Boot Java service that manages test task queues, stores results, and serves the web portal. Agents are lightweight processes that run on machines with physical devices attached. An agent registers with the center using an agent ID and a secret generated from the portal's auth page, then continuously reports device status back to the center.

This separation allows teams to attach new hardware without restarting or reconfiguring the center. A team in one office can run an agent against its own Android devices while another team runs a separate agent against iOS hardware, and both pools appear together in the same portal. The center routes incoming test requests to the agent that holds the target device.

The README does not document how the system handles reconnection when an agent drops off the network mid-test. Teams running agents over unreliable connections should verify that behavior before depending on it in CI pipelines. The wiki covers agent setup in detail, but that documentation lives outside the repository itself.

Supported Frameworks and the Platform Coverage Matrix

The README provides an explicit matrix of what runs where. Appium with Java is the broadest option, covering Android, iOS, Windows, and browser targets. Espresso covers Android only. XCTest covers iOS only. Maestro covers Android and iOS. Python Runner covers all four platforms.

That matrix has a real gap for Windows native testing. The only options for Windows are Appium and Python Runner. If a team writes Espresso tests and wants to reuse any of that work on iOS, it cannot: Espresso does not appear in the iOS column.

Beyond scripted test types, Hydra Lab supports Monkey test and a smart exploratory test mode. The README describes both as case-free test automation, which means no authored test cases are needed. A Monkey run fires random UI events and watches for crashes. These are useful for early-stage apps before any test scripts exist, but they do not confirm specific user flows behave correctly.

The current supported environments for the agent process itself are Windows, macOS, and Linux, plus a Docker option documented separately in the agent subdirectory README.

Running the First Test with the Uber Docker Image

The Uber image bundles both a center instance and an agent instance into a single container, giving the shortest path from zero to a running portal. The README breaks this into three steps.

First, pull the image:

docker pull ghcr.io/microsoft/hydra-lab-uber:latest

The README notes this pull step as necessary: skipping it risks running a locally cached image with a stale latest tag if one exists on the machine.

Then run it on port 9886:

docker run -p 9886:9886 --name=hydra-lab ghcr.io/microsoft/hydra-lab-uber:latest

After the container starts, navigate to http://localhost:9886/portal/index.html#/. The Runner tab lists connected devices. From there you select a test type, pick a device from the pool, and click Run. Completed test results appear in the Task tab on the left navigator.

One constraint applies here: the Uber image supports only Espresso and Instrumentation tests for Android. Maestro, Appium, and XCTest are not available through the Uber image. Teams that need those modes must build the center and agent separately from source.

Building Center and Agent Separately from Source

To get beyond what the Uber image supports, you run the center and agent as separate Java processes built from the repository. The README states up front that JDK 11, npm, and Android SDK platform tools must be on the path before any build command runs.

Building the center involves compiling the React frontend first, then building the Spring Boot jar:

cd react
npm ci
npm run pub
cd ..
gradlew :center:bootJar
java -jar center/build/libs/center.jar

After the center starts, visit http://localhost:9886/portal/index.html#/auth to generate the agent ID and secret.

Building the agent requires the Android client APK, which is also built from source:

cd android_client
./gradlew assembleDebug
cp app/build/outputs/apk/debug/app-debug.apk ../common/src/main/resources/record_release.apk
cd ..
cp agent/application-sample.yml application.yml
gradlew :agent:

The README notes that if building the Android client is not possible (for example, without the Android SDK), a prebuilt APK is available from the releases page. The sample YAML file for the agent has three placeholders that must be replaced: the agent name, the registered agent ID, and the agent secret from the center portal.

The README also documents a known Node issue: if the npm build fails with a digital envelope error, set the NODE_OPTIONS environment variable to --openssl-legacy-provider and restart the terminal.

Limitations That Matter Before You Deploy

The documentation strategy is a real constraint. Almost every advanced procedure, from setting up agents to triggering tests from a CI pipeline, lives in the project wiki rather than in the repository. The README is a tour and a quick start; the wiki is the actual reference. Teams that need documentation to work offline or that want to snapshot it alongside the code will find this difficult.

The storage default is the local file system, which the README calls out as insufficient for production. The recommended replacement is Azure Blob Storage, a specific Microsoft cloud service. No other object storage providers are mentioned. A team that wants to self-host completely on AWS or GCP will need to investigate compatibility independently.

The Uber image restricts Android testing to Espresso and Instrumentation. For a team evaluating Hydra Lab before investing in the full source build, this means the evaluation does not cover the full capability set.

JDK 11 is a specific requirement. The README does not say whether newer JDK versions work. Teams running modern JVM toolchains may need to maintain a parallel JDK 11 installation specifically for Hydra Lab.

Hydra Lab vs. Firebase Test Lab

Firebase Test Lab is the direct comparison point for teams deciding whether to build a device cloud or use a hosted one. Firebase Test Lab is a managed service from Google: Google owns the device pool, handles all hardware maintenance, and charges per minute of device time. You upload your APK or IPA and a test script, and Google runs the test.

Hydra Lab inverts that model entirely. You own the devices, run the infrastructure, and pay for neither per-minute charges nor test limits. For a team with dozens of physical devices from previous QA work, that difference is significant. For a team without existing hardware, buying, maintaining, and housing a device pool to avoid cloud costs is unlikely to pay off at typical test volumes.

The other axis is access. Firebase Test Lab requires outbound internet connectivity. Hydra Lab can run entirely on an internal network, which matters for apps that test against staging environments or internal APIs that are not exposed to the internet. The wiki documents how to trigger tests from external CI systems, but the center itself can run behind a firewall.

Maintenance Status and License

The repository is published under the MIT license and sits under the Microsoft organization on GitHub. The last push was on 2026-09-17, and the repository is not archived. A support email is listed in the README at [email protected], and the project accepts bug reports via GitHub issues.

The repository contains a CHANGELOG.md and a TODO.md in the root, which suggest ongoing work, but the README does not document a release cadence. There are no GitHub releases in the repository. Teams that want to pin to a known-good version will need to pin to a specific commit hash rather than a release tag.

The ThirdPartyNotices.xml file at the repository root documents third-party dependencies and their licenses. Teams subject to license auditing should review that file before adopting Hydra Lab. The MIT license on the project itself permits commercial use without restriction, but dependencies may carry their own terms.

Editorial conclusion

Teams that already own test hardware and want to bring test execution in-house should look at Hydra Lab. The center is a Spring Boot Java service requiring JDK 11, npm, and Android platform tools; the build process is not lightweight. Teams without a device inventory will find the capital cost of building a lab exceeds any savings over a hosted service. Before committing, verify that your primary test framework appears in the supported platform matrix, because Espresso only covers Android, and the Uber image only runs Espresso and Instrumentation tests. The README recommends Azure Blob Storage for production artifact storage, so a cloud dependency survives even in a self-hosted deployment.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. microsoft/HydraLab on GitHub
4. README