https://github.com/alexdlaird/java-ngrok
A Java wrapper for ngrok
https://github.com/alexdlaird/java-ngrok
education ingress java localhost ngrok reverse-proxy tunnel tunneling webhook
Last synced: about 2 months ago
JSON representation
A Java wrapper for ngrok
- Host: GitHub
- URL: https://github.com/alexdlaird/java-ngrok
- Owner: alexdlaird
- License: mit
- Created: 2021-04-19T01:27:12.000Z (about 5 years ago)
- Default Branch: main
- Last Pushed: 2026-04-23T10:33:06.000Z (about 2 months ago)
- Last Synced: 2026-04-23T12:23:05.348Z (about 2 months ago)
- Topics: education, ingress, java, localhost, ngrok, reverse-proxy, tunnel, tunneling, webhook
- Language: Java
- Homepage: https://alexdlaird.github.io/java-ngrok/
- Size: 1.78 MB
- Stars: 56
- Watchers: 3
- Forks: 8
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Security: SECURITY.md
Awesome Lists containing this project
- awesome-java - Java Ngrok
- awesome-webhooks - java-ngrok - A Java wrapper for ngrok; programmatic tunnels and webhook testing. (Development Tools)
README
[](https://central.sonatype.com/artifact/com.github.alexdlaird/java-ngrok)
[](https://central.sonatype.com/artifact/com.github.alexdlaird/java-ngrok)
[](https://codecov.io/gh/alexdlaird/java-ngrok)
[](https://github.com/alexdlaird/java-ngrok/actions/workflows/build.yml)
[](https://app.codacy.com/gh/alexdlaird/java-ngrok?utm_source=github.com&utm_medium=referral&utm_content=alexdlaird/java-ngrok&utm_campaign=Badge_Grade)
[](https://alexdlaird.github.io/java-ngrok/)
[](https://github.com/alexdlaird/java-ngrok/blob/main/LICENSE)
`java-ngrok` is a Java wrapper for `ngrok` that manages its own binary, making `ngrok` available via a convenient Java
API.
[`ngrok`](https://ngrok.com) 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.
## Installation
`java-ngrok` is available
on [Maven Central](https://central.sonatype.com/artifact/com.github.alexdlaird/java-ngrok).
If you want `ngrok` to be available from the command
line, [`pyngrok`](https://pyngrok.readthedocs.io/en/latest/#installation)
can be installed using `pip` to manage that for you.
## Basic Usage
### Open a Tunnel
To open a tunnel, use the [`NgrokClient`](https://javadoc.io/doc/com.github.alexdlaird/java-ngrok/latest/com.github.alexdlaird.ngrok/com/github/alexdlaird/ngrok/NgrokClient.html)'s [`connect()`](https://javadoc.io/doc/com.github.alexdlaird/java-ngrok/latest/com.github.alexdlaird.ngrok/com/github/alexdlaird/ngrok/NgrokClient.html#connect(com.github.alexdlaird.ngrok.protocol.CreateTunnel))
method, which returns a [`Tunnel`](https://javadoc.io/doc/com.github.alexdlaird/java-ngrok/latest/com.github.alexdlaird.ngrok/com/github/alexdlaird/ngrok/NgrokClient.html#connect(com.github.alexdlaird.ngrok.protocol.CreateTunnel)),
and this returned object has a reference to the public URL generated by `ngrok`, which can be retrieved with
[`getPublicUrl()`](https://javadoc.io/doc/com.github.alexdlaird/java-ngrok/latest/com.github.alexdlaird.ngrok/com/github/alexdlaird/ngrok/protocol/Tunnel.html#getPublicUrl()).
```java
final NgrokClient ngrokClient = new NgrokClient.Builder().build();
// Open a HTTP tunnel on the default port 80
// .ngrok.io" -> "http://localhost:80">
final Tunnel httpTunnel = ngrokClient.connect();
// Open a SSH tunnel
// "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-config-file-tunnel")
.build();
final Tunnel namedTunnel = ngrokClient.connect(createNamedTunnel);
// Open an Internal Endpoint that's load balanced
// "http://localhost:9000">
final CreateTunnel createInternalEndpoint = new CreateTunnel.Builder()
.withAddr("9000")
.withDomain("some-endpoint.internal")
.withPoolingEnabled(true)
.build();
final Tunnel internalEndpoint = ngrokClient.connect(createInternalEndpoint);
```
The [`connect()`](https://javadoc.io/doc/com.github.alexdlaird/java-ngrok/latest/com.github.alexdlaird.ngrok/com/github/alexdlaird/ngrok/NgrokClient.html#connect(com.github.alexdlaird.ngrok.protocol.CreateTunnel))
method can also take
a [`CreateTunnel`](https://javadoc.io/doc/com.github.alexdlaird/java-ngrok/latest/com.github.alexdlaird.ngrok/com/github/alexdlaird/ngrok/protocol/CreateTunnel.html)
(which can be built through [its Builder](https://javadoc.io/doc/com.github.alexdlaird/java-ngrok/latest/com.github.alexdlaird.ngrok/com/github/alexdlaird/ngrok/protocol/CreateTunnel.Builder.html))
that allows you to pass additional properties that
are supported by `ngrok` (or [`withName()`](https://javadoc.io/doc/com.github.alexdlaird/java-ngrok/latest/com.github.alexdlaird.ngrok/com/github/alexdlaird/ngrok/protocol/CreateTunnel.Builder.html#withName(java.lang.String))
to use a tunnel defined in `ngrok`'s config
file), [as documented here](https://alexdlaird.github.io/java-ngrok/#tunnel-configuration).
> **Note:** `java-ngrok` unifies `ngrok`'s "tunnel" (v2) and "endpoint" (v3) concepts behind a single API:
> `connect()` returns a `Tunnel` and handles the differences for you through the `JavaNgrokConfig.configVersion` you
> set. Existing v2 code keeps working unchanged, and every v2 tunnel and v3 endpoint feature remains available.
> For v3-specific usage, see [Using v3 Endpoints](https://alexdlaird.github.io/java-ngrok/#using-v3-endpoints).
### `ngrok`'s API
The [`api()`](https://javadoc.io/doc/com.github.alexdlaird/java-ngrok/latest/com.github.alexdlaird.ngrok/com/github/alexdlaird/ngrok/NgrokClient.html#api(java.util.List)) method allows you to use the local
`ngrok` agent to make requests against [the `ngrok` API](https://ngrok.com/docs/agent/cli-api/), if you
have [set an API key](https://alexdlaird.github.io/java-ngrok/#setting-the-authtoken-or-api_key).
For example, here's how you would reserve a `ngrok` domain, then create a Cloud Endpoint with an associated traffic
policy:
```java
final NgrokClient ngrokClient = new NgrokClient.Builder().build();
final String domain = "some-domain.ngrok.dev";
final ApiResponse domainResponse = ngrokClient.api(
List.of("reserved-domains", "create",
"--domain", domain));
final ApiResponse endpointResponse = ngrokClient.api(
List.of("endpoints", "create",
"--bindings", "public",
"--url", String.format("https://%s", domain),
"--traffic-policy-file", "policy.yml"));
```
### Command Line Usage
Assuming you have also installed [`pyngrok`](https://pyngrok.readthedocs.io/en/latest/#installation), all features of
`ngrok` are available
on the command line.
```sh
ngrok http 80
```
For details on how to fully leverage `ngrok` from the command line,
see [`ngrok`'s official documentation](https://ngrok.com/docs/agent/cli/).
## Documentation
For more advanced usage, `java-ngrok`'s official documentation is available
[here on GitHub](https://alexdlaird.github.io/java-ngrok/), with additional API documentation on [javadoc.io](https://javadoc.io/doc/com.github.alexdlaird/java-ngrok/latest).
### Integration Examples
- [Spring](https://alexdlaird.github.io/java-ngrok/integration/#spring)
- [Dropwizard](https://alexdlaird.github.io/java-ngrok/integration/#dropwizard)
- [Play (Scala)](https://alexdlaird.github.io/java-ngrok/integration/#play-scala)
- [Docker](https://alexdlaird.github.io/java-ngrok/integration/#docker)
- [End-to-End Testing](https://alexdlaird.github.io/java-ngrok/integration/#end-to-end-testing)
### Java 8
[](https://central.sonatype.com/artifact/com.github.alexdlaird/java8-ngrok)
[](https://central.sonatype.com/artifact/com.github.alexdlaird/java8-ngrok)
[](https://codecov.io/gh/alexdlaird/java-ngrok/tree/1.4.x)
[](https://github.com/alexdlaird/java-ngrok/actions/workflows/build.yml?query=branch%3A1.4.x)
[](https://javadoc.io/doc/com.github.alexdlaird/java8-ngrok)
[](https://github.com/alexdlaird/java-ngrok/blob/main/LICENSE)
A Java 8-compatible build was previously maintained in the [`1.4.x`](https://github.com/alexdlaird/java-ngrok/tree/1.4.x)
branch. While it is no longer supported, it is available through the `java8-ngrok` artifact instead on [Maven Central](https://central.sonatype.com/artifact/com.github.alexdlaird/java8-ngrok).
For more details on what differs in the `java8-ngrok` dependency,
see [the "Java 8" section of the docs](https://javadoc.io/static/com.github.alexdlaird/java8-ngrok/1.4.19/overview-summary.html#java8).
## Contributing
If you would like to get involved, be sure to review
the [Contribution Guide](https://github.com/alexdlaird/java-ngrok/blob/main/CONTRIBUTING.md).
Want to contribute financially? If you've found `java-ngrok`
useful, [sponsorship](https://github.com/sponsors/alexdlaird)
would also be greatly appreciated!