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 tool that opens secure tunnels from public URLs to localhost, perfect for exposing local web servers, building webhook integrations, enabling SSH access, testing chatbots, demoing from your own machine, and more, and its made even more powerful with native Java integration through 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.
Basic Usage
All ngrok
functionality is available through the NgrokClient
. To open a tunnel, use the connect
method, which returns a Tunnel
, and this returned object has a reference to the public URL generated by ngrok
, which can be retrieved with getPublicUrl()
.
final NgrokClient ngrokClient = new NgrokClient.Builder().build();
// Open a HTTP tunnel on the default port 80
// <Tunnel: "https://<public_sub>.ngrok.io" -> "http://localhost:80">
final Tunnel httpTunnel = ngrokClient.connect();
// Open a SSH tunnel
// <Tunnel: "tcp://0.tcp.ngrok.io:12345" -> "localhost:22">
final CreateTunnel sshCreateTunnel = new CreateTunnel.Builder()
.withProto(Proto.TCP)
.withAddr(22)
.build();
final Tunnel sshTunnel = ngrokClient.connect(sshCreateTunnel);
// Open a named tunnel from the config file
final CreateTunnel createNamedTunnel = new CreateTunnel.Builder()
.withName("my_tunnel_name")
.build();
final Tunnel namedTunnel = ngrokClient.connect(createNamedTunnel);
The connect
method can also take a CreateTunnel
( which can be built through its Builder) that allows us to pass additional properties that are supported by ngrok
, as documented here.
ngrok
‘s Edge
To use ngrok
‘s Edge with java-ngrok
, first configure an Edge on ngrok’s dashboard (with at least one Endpoint mapped to the Edge), and define a labeled tunnel in the ngrok
config file that points to the Edge.
tunnels:
some-edge-tunnel:
labels:
- edge=my_edge_id
addr: http://localhost:80
To start a labeled tunnel in java-ngrok
, set withName(String).
final NgrokClient ngrokClient = new NgrokClient.Builder().build();
// Open a named tunnel from the config file
final CreateTunnel createNamedTunnel = new CreateTunnel.Builder()
.withName("some-edge-tunnel")
.build();
final Tunnel namedTunnel = ngrokClient.connect(createNamedTunnel);
Once an Edge tunnel is started, it can be managed through ngrok
‘s dashboard.
Command Line Usage
Assuming we have also installed pyngrok, all features of ngrok
are available on the command line.
ngrok http 80
For details on how to fully leverage ngrok
from the command line, see ngrok
‘s official documentation.
Documentation
For more advanced usage, java-ngrok
‘s official documentation is available at https://javadoc.io/doc/com.github.alexdlaird/java-ngrok.
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
Java 8 support is not actively maintained, but on a periodic basis, main
may be rebased in to the 1.4.x
branch, where a compatible build of this project exists for Java 8. To use it, include the java8-ngrok
dependency from Maven Central.
For more details on what differs in the java8-ngrok
dependency, see the docs.
Contributing
If you would like to get involved, be sure to review the Contribution Guide.
Want to contribute financially? If you’ve found java-ngrok
useful, sponsorship would also be greatly appreciated!