ngrok is a globally distributed reverse proxy commonly used for quickly getting a public URL to a service running inside a private network, such as on your local laptop. The ngrok agent is usually deployed inside a private network and is used to communicate with the ngrok cloud service.
This is the ngrok agent in library form, suitable for integrating directly into Java applications. This allows you to quickly build ngrok into your application with no separate process to manage.
To use ngrok-java
, you need to add the following to your pom.xml
:
<project>
<!-- your project definition -->
<dependencies>
<dependency>
<groupId>com.ngrok</groupId>
<artifactId>ngrok-java</artifactId>
<version>${ngrok.version}</version>
</dependency>
<dependency>
<groupId>com.ngrok</groupId>
<artifactId>ngrok-java-native</artifactId>
<version>${ngrok.version}</version>
<!-- automatically detect classifier, you can also pin manually -->
<classifier>${os.detected.classifier}</classifier>
<scope>runtime</scope>
</dependency>
</dependencies>
<build>
<extensions>
<extension>
<groupId>kr.motd.maven</groupId>
<artifactId>os-maven-plugin</artifactId>
<version>1.7.0</version>
</extension>
</extensions>
</build>
</project>
If you want to use jetty integration, also add:
<dependency>
<groupId>com.ngrok</groupId>
<artifactId>ngrok-jetty</artifactId>
<version>${ngrok.version}</version>
</dependency>
(Java 17+) If you wish to use ngrok listeners as a server socket, also add:
<dependency>
<groupId>com.ngrok</groupId>
<artifactId>ngrok-java-17</artifactId>
<version>${ngrok.version}</version>
</dependency>
For example of how to setup your project, check out ngrok-java-demo
If you use gradle as a build system, you need to add to your build the following:
plugins {
id("com.google.osdetector").version("1.7.3")
}
var ngrokVersion = "0.4.1"
dependencies {
implementation("com.ngrok:ngrok-java:${ngrokVersion}")
implementation("com.ngrok:ngrok-java-native:${ngrokVersion}:${osdetector.classifier}")
}
package com.ngrok.quickstart;
import com.ngrok.Session;
import com.ngrok.Http;
import java.io.IOException;
import java.nio.ByteBuffer;
public class Quickstart {
public static void main(String[] args) throws IOException {
// Session.withAuthtokenFromEnv() will create a new session builder, pulling NGROK_AUTHTOKEN env variable.
// You can get your authtoken by registering at https://dashboard.ngrok.com
var sessionBuilder = Session.withAuthtokenFromEnv().metadata("my session");
// Session.Builder let you customize different aspects of the session, see docs for details.
// After customizing the builder, you connect:
try (var session = sessionBuilder.connect()) {
// Creates and configures http listener that will be using oauth to secure it
var listenerBuilder = session.httpEndpoint().metadata("my listener")
.oauthOptions(new Http.OAuth("google"));
// Now start listening with the above configuration
try (var listener = listenerBuilder.listen()) {
System.out.println("ngrok url: " + listener.getUrl());
var buf = ByteBuffer.allocateDirect(1024);
while (true) {
// Accept a new connection
var conn = listener.accept();
// Read from the connection
conn.read(buf);
System.out.println(buf.asCharBuffer());
// Or write to it
conn.write(buf);
}
}
}
}
}
You may either:
- Copy
./toolchains.xml
into~/.m2/
, or - When running
mvn
, run asmvn --global-toolchains ./toolchains.xml
Log level is set from the your slf4j
implementation's configuration. This level must be assigned before creating a session, as it is read on creation.
As an example, to configure slf4j-simple
, you can do:
System.setProperty("org.slf4j.simpleLogger.log.com.ngrok.Runtime", "debug");
You can then log through the Runtime
API:
Runtime.getLogger().log("info", "myClass", "Hello World");
You may subscribe to session events from ngrok:
var builder = Session.newBuilder()
.stopCallback(new Session.StopCallback() {
@Override
public void onStopCommand() {
System.out.println("onStopCommand");
}
})
.updateCallback(new Session.UpdateCallback() {
@Override
public void onUpdateCommand() {
System.out.println("onUpdateCommand");
}
})
.restartCallback(new Session.RestartCallback() {
@Override
public void onRestartCommand() {
System.out.println("onRestartCommand");
}
});
These callbacks may be useful to your application in order to invoke custom logic in response to changes in your active session.
JARs are provided on GitHub and Maven Central for the following platforms:
OS | i686 | x64 | aarch64 | armv7 |
---|---|---|---|---|
Windows | ✓ | ✓ | ||
MacOS | ✓ | ✓ | ||
Linux | ✓ | ✓ | ✓ | |
Android | ✓ | ✓ |
- Check out our official docs
- Read about updates on our blog
- Open an issue or pull request
- Join our Slack community
- Follow us on X / Twitter (@ngrokHQ)
- Subscribe to our Youtube channel (@ngrokHQ)
This project is licensed under either of
at your option.
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in ngrok-java by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.