Download & Install

The fastest way to put anything on the internet.

Select a Platform

JavaSDK

Get started with Java

Clone the ngrok Java SDK example:

git clone git@github.com:ngrok/java-sdk-example.git && cd java-sdk-example

Add the ngrok Java SDK to your pom.xml:

pom.xml

1<dependency>⋯2		<groupId>com.ngrok</groupId>3		<artifactId>ngrok-java</artifactId>4		<version>1.1.1</version>5</dependency>6<dependency>⋯7		<groupId>com.ngrok</groupId>8		<artifactId>ngrok-java-native</artifactId>9		<version>1.1.1</version>10		<classifier>${os.detected.classifier}</classifier>11		<scope>runtime</scope>12</dependency>

Add ngrok to your app:

App.java

1import com.ngrok.Session;2import java.net.URL;3 4 5void connectNgrok() throws Exception {⋯6		var session = Session.withAuthtokenFromEnv().connect();7		var forwarder = session.httpEndpoint()8				.forward(new URL("http://localhost:8085"));9		System.out.println("Available at: " + forwarder.getUrl());10}

Run your app

NGROK_AUTHTOKEN="<YOUR_AUTHTOKEN>" mvn compile exec:java

Don’t have an authtoken? Sign up for a free account.

Open your ngrok URL in a browser to see it working!

You’re all set. What’s next?

1String tp = """2on_http_request:3	# redirect users to Google to log in4	- actions:5		- type: oauth6			config:7				provider: google8 9	# allow logins *only* from acme.com10	- expressions:11		- "!actions.ngrok.oauth.identity.email.endsWith('@acme.com')"12		actions:13		- type: deny14""";15 16var forwarder = session.httpEndpoint().trafficPolicy(tp).forward(new URL("http://localhost:8085"));

1String tp = """2on_http_request:3	# verify webhook signatures from your provider4	- actions:5		- type: verify-webhook6			config:7				provider: github8				# access your signing key from a secure ngrok vault9				# no cleartext secrets in your policy, friend10				secret: ${secrets.get('webhook-vault', 'github-secret')}11""";12 13var forwarder = session.httpEndpoint().trafficPolicy(tp).forward(new URL("http://localhost:8085"));

1String tp = """2on_http_request:3	# redirect users to your OpenID provider to log in4	- actions:5		- type: openid-connect6			config:7				issuer_url: https://accounts.google.com8				# access your OIDC details from a secure ngrok vault9				client_id: ${secrets.get('auth-vault', 'oidc-client-id')}10				client_secret: ${secrets.get('auth-vault', 'oidc-client-secret')}11				scopes:12					- openid13					- email14""";15 16var forwarder = session.httpEndpoint().trafficPolicy(tp).forward(new URL("http://localhost:8085"));

1String tp = """2on_http_request:3	- actions:4		- type: basic-auth5			config:6				credentials:7					# add up to 10 username:password pairs, all stored safely in a vault8					- user01:${secrets.get('basic-auth-vault', 'password01')}9					- user02:${secrets.get('basic-auth-vault', 'password02')}10""";11 12var forwarder = session.httpEndpoint().trafficPolicy(tp).forward(new URL("http://localhost:8085"));

Inspect every detail of your traffic

Watch the flow in real time, then dig into the headers, body, latency, response, and more for every request.

Traffic inspector showing live request paths, client IPs, and status codes

Peruse the Java SDK quickstart

Follow along to embed ngrok into your app and use Traffic Policy for auth and traffic transformation.

Bring your own domain

Paid feature

Create a DNS CNAME record to use your own domain name for your endpoint URL.

1static void connectNgrok() throws IOException, InterruptedException {⋯2		try (var session = Session.withAuthtokenFromEnv().connect()) {⋯3				var forwarder = session.httpEndpoint()4						.domain("app.acme.com")5						.forward(new URL("http://localhost:8085"));6		}7}

Add load balancing

Endpoint Pooling lets you automatically distribute traffic among any number of replicas of your app. It isn't currently supported by the Java SDK — enable it with the ngrok agent CLI or config file.