ngrok-go

ngrok is an API gateway cloud service that forwards to applications running anywhere.

ngrok-go is an open source and idiomatic Go package for embedding ngrok networking directly into your Go applications. If you've used ngrok before, you can think of ngrok-go as the ngrok agent packaged as a Go library.

ngrok-go enables you to serve Go apps on the internet in a single line of code without setting up low-level network primitives like IPs, certificates, load balancers and even ports! Applications using ngrok-go listen on ngrok's global cloud service but, they receive connections using the same interface (net.Listener) that any Go app would expect if it listened on a local port.

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

Installation

Install ngrok-go with go get.

go get golang.ngrok.com/ngrok/v2

Documentation

• ngrok-go API Reference on pkg.go.dev.
• ngrok Documentation for what you can do with ngrok.
• Examples are another great way to get started.
• ngrok-go launch announcement for more context on why we built it. The examples in the blog post may be out of date for the new API.

Quickstart

The following example starts a Go web server that receives traffic from an endpoint on ngrok's cloud service with a randomly-assigned URL. The ngrok URL provided when running this example is accessible by anyone with an internet connection.

You need an ngrok authtoken to run the following example, which you can get from the ngrok dashboard.

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/v2"
)

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

func run(ctx context.Context) error {
	// ngrok.Listen uses ngrok.DefaultAgent which uses the NGROK_AUTHTOKEN
	// environment variable for auth
	ln, err := ngrok.Listen(ctx)
	if err != nil {
		return err
	}

	log.Println("Endpoint online", ln.URL())

	// Serve HTTP traffic on the ngrok endpoint
	return http.Serve(ln, http.HandlerFunc(handler))
}

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

Traffic Policy

You can use ngrok's Traffic Policy engine to apply API Gateway behaviors at ngrok's cloud service to auth, route, block and rate-limit the traffic. For example:

tp := `
on_http_request:
  - name: "rate limit by ip address"
    actions:
    - type: rate-limit
      config:
        name: client-ip-rate-limit
        algorithm: sliding_window
        capacity: 30
        rate: 60s
        bucket_key:
          - conn.client_ip
  - name: "federate to google for auth"
    actions:
    - type: oauth
      config:
        provider: google
  - name: "block users without an 'example.com' domain"
    expressions:
      - "!actions.ngrok.oauth.identity.email.endsWith('@example.com')"
    actions:
      - type: custom-response
        config:
          status_code: 403
          content: "${actions.ngrok.oauth.identity.name} is not allowed"
`

ln, err := ngrok.Listen(ctx, ngrok.WithTrafficPolicy(tp))
if err != nil {
	return err
}

Examples

There are many more great examples you can reference to get started:

• Creating a TCP endpoint and handling TCP connections directly.
• Forwarding to another URL instead of handling connections yourself.
• Adding Traffic Policy in front of your app for authentication, rate limiting, etc.

Contributing

If you find bugs or would like to contribute code, please follow the instructions in the contributing guide.

Go Version Policy

We support the current and previous major releases of Go.

Changelog

Changes to ngrok-go are tracked under CHANGELOG.md.

Join the ngrok Community

• Check out our official docs
• Read about updates on our blog
• Open an issue or pull request
• Follow us on X / Twitter (@ngrokHQ)
• Subscribe to our Youtube channel (@ngrokHQ)

License

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

See LICENSE for details.