Hydra Engine

Installation

Download a release, or build the install yourself.

An install is headless Ghidra with the same packages, modules and paths (ghidra.*, Ghidra/Features/...), so your Ghidra scripts and extensions work unchanged. What it adds is the session module and its launcher. It doesn't include a JDK.

  • Windows x64 zips
  • JDK 25
  • Python 3.10+

Download a release

Each release carries three files:

FileWhat it is
hydra-engine-<version>-win_x86_64.zipThe headless install for Windows x64.
hydra-client-<version>.zipghidra_session.py on its own, stamped with the release, for tools that pin a client.
SHA256SUMSChecksums for both zips.
powershell
1Get-FileHash hydra-engine-12.3-hydra.2-win_x86_64.zip   # compare with SHA256SUMS2Expand-Archive hydra-engine-12.3-hydra.2-win_x86_64.zip C:\tools3python C:\tools\ghidra_12.3_DEV\Ghidra\Features\HeadlessSession\support\ghidra_session.py ensure

A version is the Ghidra version it's built on, then -hydra. and a counter: 12.3-hydra.2 is the second release on Ghidra 12.3 DEV.

Build from source

Linux and macOS install from source for now. The build uses the same JDK 25.

bash
1git clone https://github.com/RusticStack/hydra-engine.git2cd hydra-engine3./gradlew -I gradle/support/fetchDependencies.gradle -DnoEclipse   # once4./gradlew buildHeadless                                             # -> build/dist/ghidra_12.3_DEV

buildHeadless leaves out the window-only modules, help, javadoc and Python stubs, and checks that nothing it keeps depends on something it dropped. The full build, window included, is still ./gradlew buildGhidra.

How the JDK is found

The launcher takes the first JDK (not a JRE) that fits the install's Java range, looking in this order:

  1. --java, or java in config.json
  2. GHIDRA_SESSION_JAVA_HOME
  3. JAVA_HOME_OVERRIDE in the install's support/launch.properties
  4. JAVA_HOME
  5. the JDK Ghidra's own launcher saved for this version
  6. java on PATH

It reads each candidate's version from its release file, so checking costs no JVM start.

Check the install

Here and in the rest of the docs, $GS is the path to ghidra_session.py: Ghidra/Features/HeadlessSession/support/ inside the install.

bash
1python $GS version   # client version, protocol and release; needs no daemon2python $GS config    # effective configuration, JDK and install3python $GS ensure    # start the daemon and print its endpoint

Faster starts

On JDK 25 the launcher can load Ghidra's classes from an AOT cache. Build it once with a short training run:

bash
1python $GS aot --project /re/SmallProject

The cache is keyed by the JDK, the install and every jar on the classpath. After an update the daemon simply starts without it until you rebuild. Ghidra's extension-point scan is cached as well, automatically.

Pinning and upgrading

A tool that drives the daemon should pin a release: keep the engine and the hydra-client zip of the same release together. On every connection the client checks the engine's protocol and minClient, and refuses an engine it can't drive with IncompatibleError (exit code 4 on the command line).

  1. Read the release notes.
  2. python $GS stop the old daemon.
  3. Put the new engine and client side by side and point your tool at them.
  4. Run version, then ensure, and check what hello reports.

Projects saved by this build can't be opened by Ghidra 12.2 or 12.1.4. Opening a project read-only writes nothing; write to an older project only in a working copy.