Agent SDKs

Overview

Agent SDKs enable you to embed ngrok directly into your application. They allow you to programmatically create ngrok endpoints. You handle connections from ngrok's edge just as if you opened a socket to listen on a port.

Example Usage

Go SDK

import (
	"context"
	"net"

	"golang.ngrok.com/ngrok"
	"golang.ngrok.com/ngrok/config"
)

func ngrokListener(ctx context.Context) (net.Listener, error) {
	return ngrok.Listen(ctx,
		config.HTTPEndpoint(),
		ngrok.WithAuthtokenFromEnv(),
	)
}

Go Package Docs:

• https://pkg.go.dev/golang.ngrok.com/ngrok/config#HTTPEndpoint

Javascript SDK

const ngrok = require("@ngrok/ngrok");

(async function () {
	const listener = await ngrok.forward({
		addr: 8080,
		authtoken_from_env: true,
	});

	console.log(`Ingress established at: ${listener.url()}`);
})();

Javascript SDK Docs:

• https://ngrok.github.io/ngrok-javascript/classes/HttpListenerBuilder.html
• https://ngrok.github.io/ngrok-javascript/classes/Session.html#httpEndpoint
• https://ngrok.github.io/ngrok-javascript/functions/connect.html

Python SDK

import ngrok

listener = ngrok.forward("localhost:8080", authtoken_from_env=True)

print(f"Ingress established at: {listener.url()}");

Python SDK Docs:

• https://ngrok.github.io/ngrok-python/http_listener_builder.html
• https://ngrok.github.io/ngrok-python/session.html#ngrok.Session.http_endpoint
• https://ngrok.github.io/ngrok-python/module.html#ngrok.connect

Rust SDK

use ngrok::prelude::*;

async fn listen_ngrok() -> anyhow::Result<impl Tunnel> {
    let sess = ngrok::Session::builder()
        .authtoken_from_env()
        .connect()
        .await?;

    let tun = sess
        .http_endpoint()
        .listen()
        .await?;

    println!("Listening on URL: {:?}", tun.url());

    Ok(tun)
}

Rust Crate Docs:

• https://docs.rs/ngrok/latest/ngrok/session/struct.Session.html#method.http_endpoint

Supported Languages

Language	Docs	Quickstart	Repository	Status
Go	ngrok-go docs	ngrok-go quickstart	github.com/ngrok/ngrok-go	Stable
Rust	ngrok-rust docs	ngrok-rust quickstart	github.com/ngrok/ngrok-rust	Stable
Python	ngrok-python docs		github.com/ngrok/ngrok-python	Stable
JavaScript	ngrok-javascript docs		github.com/ngrok/ngrok-javascript	Stable
Java			github.com/ngrok/ngrok-java	Alpha

When should I use Agent SDKs?

Agent SDKs are often a better fit for your use case over using the ngrok agent. This is especially true when running ngrok with production apps. Agent SDKs are a better choice if:

• You don't want to manage the lifetime of a separate agent process
• You don't want to bundle and distribute the ngrok agent
• The ngrok agent doesn't run on your target platform
• The ngrok agent's resource requirements are too high for your target platform
• You want fine-grained programmatic control over the agent's functionality

Pricing

The agent SDKs are available to all ngrok users at no additional charge. You only incur costs if the resources provisioned by the SDKs incur a cost.