ngrok is a globally distributed reverse proxy commonly used for quickly getting a public URL to a service running inside a private network, such as on your local laptop. The ngrok agent is usually deployed inside a private network and is used to communicate with the ngrok cloud service.

This is the ngrok agent in library form, suitable for integrating directly into Go applications. This allows you to quickly build ngrok into your application with no separate process to manage.

See examples/http/main.go for example usage, or the tests in online_test.go.

For working with the ngrok API, check out the ngrok Go API Client Library.

The best way to install the ngrok agent SDK is through go get.

go get golang.ngrok.com/ngrok

A full API reference is included in the ngrok go sdk documentation on pkg.go.dev. Check out the ngrok Documentation for more information about what you can do with ngrok.

For more examples of using ngrok-go, check out the /examples folder.

The following example uses ngrok to start an http endpoint with a random url that will route traffic to the handler. The ngrok URL provided when running this example is accessible by anyone with an internet connection.

The ngrok authtoken is pulled from the NGROK_AUTHTOKEN environment variable. You can find your authtoken by logging into the ngrok dashboard.

You can run this example with the following command:

NGROK_AUTHTOKEN=xxxx_xxxx go run examples/http/main.go

package main

import (
	"context"
	"fmt"
	"log"
	"net/http"

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

func main() {
	if err := run(context.Background()); err != nil {
		log.Fatal(err)
	}
}

func run(ctx context.Context) error {
	tun, err := ngrok.Listen(ctx,
		config.HTTPEndpoint(),
		ngrok.WithAuthtokenFromEnv(),
	)
	if err != nil {
		return err
	}

	log.Println("tunnel created:", tun.URL())

	return http.Serve(tun, http.HandlerFunc(handler))
}

func handler(w http.ResponseWriter, r *http.Request) {
	fmt.Fprintln(w, "Hello from ngrok-go!")
}

The best place to get support using ngrok-go is through the ngrok Slack Community. If you find bugs or would like to contribute code, please follow the instructions in the contributing guide.

ngrok-go is licensed under the terms of the MIT license.

See LICENSE for details.