NgrokClient (java8-ngrok 1.4.20 API)

java.lang.Object
- com.github.alexdlaird.ngrok.NgrokClient

public class NgrokClient
extends java.lang.Object

A client for interacting with ngrok, its binary, and its APIs. Can be configured with JavaNgrokConfig.

Basic Usage

Open a Tunnel

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 in its Tunnel.getPublicUrl() method.

 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() method can also take a CreateTunnel (which can be built through its Builder), which allows us to pass additional tunnel configurations that are supported by ngrok (or CreateTunnel.Builder.withName(String) to use a tunnel defined in ngrok`'s config file), as documented here.

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).

Note: ngrok v2's default behavior for http when no additional properties are passed is to open two tunnels, one http and one https. This method will return a reference to the http tunnel in this case. If only a single tunnel is needed, call CreateTunnel.Builder.withBindTls(BindTls) with BindTls.TRUE and a reference to the https tunnel will be returned.

`ngrok`'s API

The api() method allows us to use the local ngrok agent to make requests against the ngrok API, if we have set an API key. For example, here we reserve a ngrok domain, then create a Cloud Endpoint with an associated traffic policy:

 final NgrokClient ngrokClient = new NgrokClient.Builder().build();

 final String domain = "some-domain.ngrok.dev";
 final ApiResponse domainResponse = ngrokClient.api(
     Stream.of("reserved-domains", "create",
         "--domain", domain).collect(Collectors.toList()));
 final ApiResponse endpointResponse = ngrokClient.api(
     Stream.of("endpoints", "create",
         "--bindings", "public",
         "--url", String.format("https://%s", domain),
         "--traffic-policy-file", "policy.yml").collect(Collectors.toList()));

`ngrok`'s Edge

Note: ngrok has deprecated Edges and will sunset Labeled Tunnels on December 31st, 2025. See this issue for more details.

To use ngrok's Edges 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 CreateTunnel.Builder.withName(String).

 final NgrokClient ngrokClient = new NgrokClient.Builder().build();

 // Open the Edge tunnel that is defined in 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.

Get Active Tunnels

It can be useful to ask the ngrok client what tunnels are currently open. This can be accomplished with the getTunnels() method, which returns a list of Tunnel objects.

 [<Tunnel: "https://<public_sub>.ngrok.io" -> "http://localhost:80">]
 final List<Tunnel> tunnels = ngrokClient.getTunnels();

Close a Tunnel

All open tunnels will automatically be closed when the Java process terminates, but we can also close them manually with disconnect(String).

 // The Tunnel returned from methods like connect(), getTunnels(), etc. contains the public URL
 ngrokClient.disconnect(publicUrl);

Expose Other Services

Using ngrok we can expose any number of non-HTTP services, for instances databases, game servers, etc. This can be accomplished by using java-ngrok to open a tcp tunnel to the desired service.

 final NgrokClient ngrokClient = new NgrokClient.Builder().build();

 // Open a tunnel to MySQL with a Reserved TCP Address
 // <NgrokTunnel: "tcp://1.tcp.ngrok.io:12345" -> "localhost:3306">
 final CreateTunnel mysqlCreateTunnel = new CreateTunnel.Builder()
         .withProto(Proto.TCP)
         .withAddr(3306)
         .withRemoteAddr("1.tcp.ngrok.io:12345")
         .build();
 final Tunnel mysqlTunnel = ngrokClient.connect(mysqlCreateTunnel);

We can also serve up local directories via ngrok's built-in fileserver.

 final NgrokClient ngrokClient = new NgrokClient.Builder().build();

 // Open a tunnel to a local file server
 // <NgrokTunnel: "https://<public_sub>.ngrok.io" -> "file:///">
 final CreateTunnel fileserverCreateTunnel = new CreateTunnel.Builder()
         .withAddr("file:///)
         .build();
 final Tunnel fileserverTunnel = ngrokClient.connect(fileserverCreateTunnel);

Tunnel Configurations

It is possible to configure the tunnel when it is created, for instance adding authentication, a subdomain, or other additional tunnel configurations that are supported by ngrok. This is accomplished by using CreateTunnel.Builder to set what properties will be used when the tunnel is created.

Here is an example that opens a tunnel with subdomain foo, requires basic authentication for requests, and defines a circuit breaker.

 final NgrokClient ngrokClient = new NgrokClient.Builder().build();

 final CreateTunnel createTunnel = new CreateTunnel.Builder()
         .withSubdomain("foo")
         .withAuth("username:password"")
         .withCircuitBreaker(50)
         .build();

 final Tunnel tunnel = ngrokClient.connect(createTunnel);

If we already have a tunnel defined in ngrok's config file, we can start it by its name.

 final NgrokClient ngrokClient = new NgrokClient.Builder().build();

 final CreateTunnel createTunnel = new CreateTunnel.Builder()
         .withName("my-config-file-tunnel")
         .build();

 final Tunnel tunnel = ngrokClient.connect(createTunnel);

Integration Examples

java-ngrok is useful in any number of integrations, for instance to test locally without having to deploy or configure. Here are some common usage examples.

Nested Class Summary

Nested Classes
Modifier and Type Class and Description

static class NgrokClient.Builder
Builder for a NgrokClient, see docs for that class for example usage.

Nested Classes
Modifier and Type	Class and Description
`static class`	`NgrokClient.Builder` Builder for a `NgrokClient`, see docs for that class for example usage.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`ApiResponse`	`api(java.util.List<java.lang.String> args)` Run a `ngrok` command against the `api` with the given args.
`Tunnel`	`connect()` See `connect(CreateTunnel)`.
`Tunnel`	`connect(CreateTunnel createTunnel)` Establish a new `ngrok` tunnel for the Tunnel creation request, returning an object representing the connected tunnel.
`void`	`disconnect(java.lang.String publicUrl)` Disconnect the `ngrok` tunnel for the given URL, if open.
`HttpClient`	`getHttpClient()` Get the class used to make HTTP requests to `ngrok`'s APIs.
`JavaNgrokConfig`	`getJavaNgrokConfig()` Get the `java-ngrok` to use when interacting with the `ngrok` binary.
`NgrokProcess`	`getNgrokProcess()` Get the class used to manage the `ngrok` binary.
`java.util.List<Tunnel>`	`getTunnels()` Get a list of active `ngrok` tunnels.
`Version`	`getVersion()` Get the `ngrok` and `java-ngrok` version.
`void`	`kill()` Terminate the `ngrok` processes, if running.
`void`	`refreshMetrics(Tunnel tunnel)` Get the latest metrics for the given `Tunnel` and update its `metrics` attribute.
`void`	`setApiKey(java.lang.String apiKey)` Set the `ngrok` API key in the config file to enable access to more features (for instance, Internal Endpoints).
`void`	`setAuthToken(java.lang.String authToken)` Set the `ngrok` auth token in the config file to streamline access to more features (for instance, multiple concurrent tunnels, custom domains, etc.).
`void`	`update()` Update `ngrok`, if an update is available.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Method Detail
  - connect
```
public Tunnel connect(CreateTunnel createTunnel)
```
    Establish a new ngrok tunnel for the Tunnel creation request, returning an object representing the connected tunnel.
    If a tunnel definition in ngrok's config file matches the given CreateTunnel.Builder.withName(String), it will be loaded and used to start the tunnel. When CreateTunnel.Builder.withName(String) is not set and a "java-ngrok-default" tunnel definition exists in ngrok's config, it will be loaded and used. Any properties defined on CreateTunnel will override properties from the loaded tunnel definition.
    If ngrok is not installed at JavaNgrokConfig's ngrokPath, calling this method will first download and install ngrok.
    java-ngrok is compatible with ngrok v2 and v3, but by default it will install v2. To install v3 instead, set the version with JavaNgrokConfig.Builder.withNgrokVersion(NgrokVersion) and CreateTunnel.Builder.withNgrokVersion(NgrokVersion).
    If ngrok is not running, calling this method will first start a process with JavaNgrokConfig.
    Note: ngrok v2's default behavior for http when no additional properties are passed is to open two tunnels, one http and one https. This method will return a reference to the http tunnel in this case. If only a single tunnel is needed, call CreateTunnel.Builder.withBindTls(BindTls) with BindTls.TRUE and a reference to the https tunnel will be returned.
    
    Parameters:
    
    createTunnel - The tunnel definition.
    
    Returns:
    
    The created Tunnel.
    
    Throws:
    
    JavaNgrokException - The tunnel definition was invalid, or response was incompatible with java-ngrok.
    
    JavaNgrokHTTPException - An HTTP error occurred communicating with the ngrok API.
    
    JavaNgrokSecurityException - The URL was not supported.
  - connect
```
public Tunnel connect()
```
    See connect(CreateTunnel).
  - disconnect
```
public void disconnect(java.lang.String publicUrl)
```
    Disconnect the ngrok tunnel for the given URL, if open.
    If ngrok is not running, calling this method will first start a process with JavaNgrokConfig.
    
    Parameters:
    
    publicUrl - The public URL of the tunnel to disconnect.
    
    Throws:
    
    JavaNgrokHTTPException - An HTTP error occurred communicating with the ngrok API.
    
    JavaNgrokSecurityException - The URL was not supported.
  - getTunnels
```
public java.util.List<Tunnel> getTunnels()
```
    Get a list of active ngrok tunnels.
    If ngrok is not running, calling this method will first start a process with JavaNgrokConfig.
    
    Returns:
    
    The active ngrok tunnels.
    
    Throws:
    
    JavaNgrokException - The response was invalid or not compatible with java-ngrok.
    
    JavaNgrokHTTPException - An HTTP error occurred communicating with the ngrok API.
    
    JavaNgrokSecurityException - The URL was not supported.
  - refreshMetrics
```
public void refreshMetrics(Tunnel tunnel)
```
    Get the latest metrics for the given Tunnel and update its metrics attribute.
    
    Parameters:
    
    tunnel - The Tunnel to update.
    
    Throws:
    
    JavaNgrokException - The API did not return metrics.
    
    JavaNgrokSecurityException - The URL was not supported.
  - kill
```
public void kill()
```
    Terminate the ngrok processes, if running. This method will not block, it will just issue a kill request.
  - setAuthToken
```
public void setAuthToken(java.lang.String authToken)
```
    Set the ngrok auth token in the config file to streamline access to more features (for instance, multiple concurrent tunnels, custom domains, etc.).
    The auth token can also be set in the JavaNgrokConfig that is passed to the NgrokClient.Builder, or use the environment variable NGROK_AUTHTOKEN.
```
 // Setting an auth token allows us to do things like open multiple tunnels at the same time
 final NgrokClient ngrokClient = new NgrokClient.Builder().build();
 ngrokClient.setAuthToken("<NGROK_AUTHTOKEN>")

 // <NgrokTunnel: "https://<public_sub1>.ngrok.io" -> "http://localhost:80">
 final Tunnel ngrokTunnel1 = ngrokClient.connect();
 // <NgrokTunnel: "https://<public_sub2>.ngrok.io" -> "http://localhost:8000">
 final CreateTunnel sshCreateTunnel = new CreateTunnel.Builder()
         .withAddr(8000)
         .build();
 final Tunnel ngrokTunnel2 = ngrokClient.connect(createTunnel);
 
```
    Parameters:
    
    authToken - The auth token.
  - setApiKey
```
public void setApiKey(java.lang.String apiKey)
```
    Set the ngrok API key in the config file to enable access to more features (for instance, Internal Endpoints).
    The API key can also be set in the JavaNgrokConfig that is passed to the NgrokClient.Builder, or use the environment variable NGROK_API_KEY.
```
 // Setting an API key allows us to use things like Internal Endpoints
 final NgrokClient ngrokClient = new NgrokClient.Builder().build();
 ngrokClient.setApiKey("<NGROK_API_KEY>")

 // <NgrokTunnel: "tls://some-endpoint.internal" -> "localhost:9000">
 final CreateTunnel createInternalEndpoint = new CreateTunnel.Builder()
     .withAddr("9000")
     .withProto(Proto.TLS)
     .withDomain("some-endpoint.internal")
     .withPoolingEnabled(true)
     .build();
 final Tunnel internalEndpoint = ngrokClient.connect(createInternalEndpoint);
 
```
    Parameters:
    
    apiKey - The API key.
  - update
```
public void update()
```
    Update ngrok, if an update is available.
  - getVersion
```
public Version getVersion()
```
    Get the ngrok and java-ngrok version.
    
    Returns:
    
    The versions.
  - api
```
public ApiResponse api(java.util.List<java.lang.String> args)
                throws java.io.IOException,
                       java.lang.InterruptedException
```
    Run a ngrok command against the api with the given args. This will use the local agent to run a remote API request for ngrok, which requires that an API key has been set. For a list of available commands, pass Collections.singletonList("--help").
    
    Parameters:
    
    args - The args to pass to the api command.
    
    Returns:
    
    The response from executing the api command.
    
    Throws:
    
    NgrokException - The ngrok process exited with an error.
    
    java.io.IOException - An I/O exception occurred.
    
    java.lang.InterruptedException - The thread was interrupted during execution.
  - getJavaNgrokConfig
```
public JavaNgrokConfig getJavaNgrokConfig()
```
    Get the java-ngrok to use when interacting with the ngrok binary.
  - getNgrokProcess
```
public NgrokProcess getNgrokProcess()
```
    Get the class used to manage the ngrok binary.
  - getHttpClient
```
public HttpClient getHttpClient()
```
    Get the class used to make HTTP requests to ngrok's APIs.

Class NgrokClient

Basic Usage

Open a Tunnel

ngrok's API

ngrok's Edge

Get Active Tunnels

Close a Tunnel

Expose Other Services

Tunnel Configurations

Integration Examples

Nested Class Summary

Method Summary

Methods inherited from class java.lang.Object

Method Detail

connect

connect

disconnect

getTunnels

refreshMetrics

kill

setAuthToken

setApiKey

update

getVersion

api

getJavaNgrokConfig

getNgrokProcess

getHttpClient

`ngrok`'s API

`ngrok`'s Edge