java-ngrok

KO | EN

gitlite — search

#typescript #ai-agents #ai #dsh-plugin #deepseek-harness #open-source #cli #claude-code #codex #developer-tools #react #windows

★ 60 Open GitHub ↗

A Java wrapper for ngrok; programmatic tunnels for ingress, webhooks, demos, and APIs

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

[![Version](https://img.shields.io/maven-central/v/com.github.alexdlaird/java-ngrok)](https://central.sonatype.com/artifact/com.github.alexdlaird/java-ngrok)
[![Java Versions](https://img.shields.io/badge/Java-11+-blue)](https://central.sonatype.com/artifact/com.github.alexdlaird/java-ngrok)
[![Coverage](https://img.shields.io/codecov/c/github/alexdlaird/java-ngrok)](https://codecov.io/gh/alexdlaird/java-ngrok)
[![Build](https://img.shields.io/github/actions/workflow/status/alexdlaird/java-ngrok/build.yml)](https://github.com/alexdlaird/java-ngrok/actions/workflows/build.yml)
[![Code Quality](https://api.codacy.com/project/badge/Grade/940d16178f8f4e8abfcf9bf2873894b3)](https://app.codacy.com/gh/alexdlaird/java-ngrok?utm_source=github.com&utm_medium=referral&utm_content=alexdlaird/java-ngrok&utm_campaign=Badge_Grade)
[![Docs](https://img.shields.io/badge/docs-passing-brightgreen)](https://alexdlaird.github.io/java-ngrok/)
[![GitHub License](https://img.shields.io/github/license/alexdlaird/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
// <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-config-file-tunnel")
        .build();
final Tunnel namedTunnel = ngrokClient.connect(createNamedTunnel);

// Open an Internal Endpoint that's load balanced
// <Tunnel: "https://some-endpoint.internal" -> "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. All `ngrok` features are available to you through this. For v3-specific Endpoints, 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

[![Version](https://img.shields.io/maven-central/v/com.github.alexdlaird/java8-ngrok)](https://central.sonatype.com/artifact/com.github.alexdlaird/java8-ngrok)
[![Java Versions](https://img.shields.io/badge/Java-8+-blue)](https://central.sonatype.com/artifact/com.github.alexdlaird/java8-ngrok)
[![Coverage](https://img.shields.io/codecov/c/github/alexdlaird/java-ngrok/1.4.x)](https://codecov.io/gh/alexdlaird/java-ngrok/tree/1.4.x)
[![Build](https://img.shields.io/github/actions/workflow/status/alexdlaird/java-ngrok/build.yml?branch=1.4.x)](https://github.com/alexdlaird/java-ngrok/actions/workflows/build.yml?query=branch%3A1.4.x)
[![Docs](https://img.shields.io/badge/docs-passing-brightgreen)](https://javadoc.io/doc/com.github.alexdlaird/java8-ngrok)
[![GitHub License](https://img.shields.io/github/license/alexdlaird/java-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!

java-ngrok

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README