Gradle Daemon Idle Timeout vs. Low-Traffic Build Schedules: Adaptive Retention Strategy

Answer to the Core Question

Gradle's daemon idle timeout is a fixed value that is negotiated when the daemon starts. Once a daemon is running, its org.gradle.daemon.idletimeout cannot be changed by subsequent builds or by a plugin. Therefore an adaptive policy must be implemented outside the daemon: either by choosing a different timeout for each new daemon launch or by explicitly stopping daemons during predicted quiet windows.

Confirmed Facts

• The default idle timeout is 3 hours (10800000 ms) and is set via org.gradle.daemon.idletimeout in gradle.properties or as a -D system property.
• When a build starts, Gradle looks for an existing daemon that matches the Gradle version, Java runtime, and JVM arguments. If none is found, a new daemon is launched with the timeout value supplied for that invocation.
• Passing a different -Dorg.gradle.daemon.idletimeout per invocation will cause a new daemon to be created if the value differs from any currently running daemon's timeout.
• There is no documented Gradle-specific failure mode caused by a daemon living for days; the main retention cost is the committed heap, metaspace, JIT code cache, and file-watcher resources.

Practical Adaptive Approach

Because the daemon can't be re-tuned at runtime, the adaptation must happen at launch time or via explicit --stop commands. A lightweight wrapper script can:

1. Record the timestamp of each build in a small state file under $GRADLE_USER_HOME/.gradle/build-timestamps.
2. Compute a rolling median or a chosen percentile of the gaps between the last N builds (e.g., N = 10).
3. Clamp the computed value between a safe floor (e.g., 30 min) and the default 3 h.
4. Invoke Gradle with -Dorg.gradle.daemon.idletimeout=<computed-ms> only when a new daemon will be launched (i.e., when no matching daemon is found).

On CI or scheduled environments, the timeout can be set directly from the known cron/trigger interval, bypassing the timestamp calculation. Additionally, a cron job or CI pre-step can run ./gradlew --stop during predictable quiet windows to ensure no daemon lingers beyond its intended life.

Risks and Caveats

• Setting a very low timeout on a shared machine can increase churn: each build will spin up a fresh daemon, discarding warm caches and potentially raising overall memory usage if builds overlap.
• Each distinct timeout value spawns a separate daemon; over time this can lead to multiple idle daemons consuming memory across Gradle versions and users.
• A plugin that attempts to modify org.gradle.daemon.idletimeout mid-build will have no effect on the already running daemon and may unintentionally create a new one.

Verification Steps

# Check current daemon status
./gradlew --status

# Stop all daemons (useful after a quiet period)
./gradlew --stop

# Observe memory after idle period
jcmd <daemon-pid> VM.native_memory summary

To test the adaptive wrapper, set a short timeout (e.g., -Dorg.gradle.daemon.idletimeout=120000), run a build, wait 2 minutes, and confirm the daemon exits via --status.

Missing Diagnostic Detail

To fine-tune the heuristic, could you share the typical distribution of your build intervals? Knowing whether builds cluster in hourly bursts or are spread over days will help decide the floor and percentile used for the timeout calculation.