java-ngrok 2.3.12 API

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

ngrok is a reverse proxy that opens secure tunnels from public URLs to localhost. It's perfect for rapid development (test webhooks, demo local websites, enable SSH access), establishing ingress to external networks and devices, building production APIs (traffic policies, OAuth, load balancing), and more. And it's made even more powerful with native Java integration through the java-ngrok client.

Useful Links

• ngrok Documentation
• java-ngrok on Maven Central
• java-ngrok on GitHub
• Sponsor java-ngrok

Installation

java-ngrok is available on Maven Central.

If we want ngrok to be available from the command line, pyngrok can be installed using pip to manage that for us.

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

Integration Examples

• Spring
• Dropwizard
• Play (Scala)
• Java HTTP Server
• Java TCP Server and Client

ngrok Version Compatibility

java-ngrok is compatible with ngrok v2 and v3, but by default it will install v3. To install v2 instead, set the version with JavaNgrokConfig.Builder.withNgrokVersion(NgrokVersion) and CreateTunnel.Builder.withNgrokVersion(NgrokVersion).

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 us. So even though the Java process will terminate gracefully, ngrok will not. On a Unix-like system, we 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.