Gin Library - ngrok documentation

ngrok-gin serves a Gin router through an ngrok endpoint with one call:

ngrokgin.Serve(context.Background(), router, ngrokgin.Config{})

The library is built on the Go SDK. Serve opens an endpoint listener and hands it to Gin’s RunListener, so Gin serves ngrok traffic the same way it serves a local port.

ngrok-gin is published on the Go module proxy at v0.1.0 and maintained in the ngrok-samples/ngrok-gin repository.

What you’ll need

An ngrok account.
Your ngrok auth token.
Go 1.26 or later installed on your machine.

1. Install the library

In your Go module, run:

go get github.com/ngrok-samples/ngrok-gin

2. Set your auth token

Export your auth token as an environment variable:

export NGROK_AUTHTOKEN=your_actual_auth_token_here

The library uses the Go SDK’s default agent, which reads NGROK_AUTHTOKEN from the environment.

3. Serve your router

Replace router.Run() with ngrokgin.Serve():

main.go

package main

import (
	"context"
	"log"

	"github.com/gin-gonic/gin"
	ngrokgin "github.com/ngrok-samples/ngrok-gin"
)

func main() {
	router := gin.Default()
	router.GET("/", func(c *gin.Context) {
		c.String(200, "Hello from Gin!")
	})

	if err := ngrokgin.Serve(context.Background(), router, ngrokgin.Config{}); err != nil {
		log.Fatal(err)
	}
}

Serve blocks until the listener closes or a connection error occurs, the same as router.Run().

4. Test your endpoint

Run your app:

go run main.go

The library prints Ingress established at: followed by the public URL. With an empty Config, that URL is your account’s dev domain. Open it in your browser to see your Gin app.

Configuration

Pass a Config to set the URL, add a Traffic Policy, or change the binding:

config := ngrokgin.Config{
	URL: "your-reserved-domain.ngrok.app",
	TrafficPolicy: `
on_http_request:
  - actions:
      - type: basic-auth
        config:
          credentials:
            - "user:password123"
`,
}

ngrokgin.Serve(context.Background(), router, config)

Field	Type	Description
`URL`	`string`	The reserved domain for the endpoint. An empty string uses your account’s dev domain.
`Pooling`	`bool`	Opts in to endpoint pooling so more than one endpoint can share a URL.
`TrafficPolicy`	`string`	A raw Traffic Policy document (YAML or JSON) that the library passes through to ngrok unchanged. Use it for authentication, IP restrictions, webhook verification, and any other action.
`Binding`	`ngrokgin.Binding`	The endpoint’s binding: `ngrokgin.BindingPublic`, `ngrokgin.BindingInternal`, or `ngrokgin.BindingKubernetes`.

Multiple endpoints

ServeMany opens one endpoint per Endpoint, each with its own router and Config, on a single agent:

err := ngrokgin.ServeMany(context.Background(), []ngrokgin.Endpoint{
	{Router: appRouter, Config: ngrokgin.Config{URL: "app.mycompany.ngrok.app"}},
	{Router: apiRouter, Config: ngrokgin.Config{URL: "api.mycompany.ngrok.app"}},
})

Serve is the one-endpoint case of ServeMany. To put one router behind several listeners, reuse the same *gin.Engine in more than one Endpoint. Every endpoint needs its own URL, or Pooling: true on each endpoint that shares one. If two endpoints would share a URL without pooling, including two endpoints that both leave URL empty and land on your dev domain, ServeMany returns a *ngrokgin.CollisionError before opening a session. Without that check, ngrok lets the most recently opened listener win and the other goes unreachable with no error.

Limits and availability

The library opens HTTP endpoints only. For TCP or TLS endpoints, use the Go SDK directly.
An internal binding requires a URL that ends in .internal. ngrok rejects any other URL with ERR_NGROK_9029.
A URL that another agent or a Cloud Endpoint already claims fails with ERR_NGROK_334.
Endpoint counts and domains follow your plan’s limits. See free plan limits.

What’s next?

Browse Traffic Policy examples to add authentication, restrict access by IP, or rewrite URLs.
Read the Go SDK quickstart to see what the library does under the hood.
See the other framework libraries for Next.js, FastAPI, and Axum.
Report issues or read the source in the ngrok-samples/ngrok-gin repository, which includes runnable examples for every option.

​What you’ll need

​1. Install the library

​2. Set your auth token

​3. Serve your router

​4. Test your endpoint

​Configuration

​Multiple endpoints

​Limits and availability

​What’s next?

What you’ll need

1. Install the library

2. Set your auth token

3. Serve your router

4. Test your endpoint

Configuration

Multiple endpoints

Limits and availability

What’s next?