Overview (java-ngrok 2.4.1 API)

java-ngrok is a Java wrapper for ngrok that manages its own binary, making ngrok available via a convenient Java API.

Useful Links

Getting Around

NgrokClient - Get started using java-ngrok, most common uses cases just require the default client behavior
JavaNgrokConfig - Configure the NgrokClient, NgrokProcess, NgrokInstaller, and other parts of java-ngrok
NgrokProcess - Advanced usage of the ngrok process
NgrokAgent - Interact with the running ngrok agent

Java 8

A Java 8-compatible build was maintained in the 1.4.x branch, but it is not actively supported. To use it, include the java8-ngrok dependency from Maven Central.

The Process API was introduced in Java 9, so certain convenience methods around managing the ngrok process are not available in the Java 8 build. For instance, without the Process API, java8-ngrok cannot teardown the external ngrok process for you. So even though the Java process will terminate gracefully, ngrok will not. On a Unix-like system, you can remedy this with:

Runtime.getRuntime().addShutdownHook(new Thread(() -> {
    try {
        // Java 8 doesn't properly manage its child processes, so ensure it's killed
        Runtime.getRuntime().exec("killall -9 ngrok");
    } catch (final IOException e) {
        LOGGER.error("An error occurred while shutting down ngrok", e);
    }
}));

But killall is not available on all platforms, and even on Unix-like systems this workaround is limited and has side effects.

Modules
Module	Description
com.github.alexdlaird.ngrok	This module contains a Java wrapped for `ngrok` that manages its own binary.