> ## Documentation Index
> Fetch the complete documentation index at: https://ngrok.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Gin Library

> Serve a Gin router through an ngrok endpoint with one call using the ngrok-gin Go library, and configure it with a Traffic Policy or a reserved domain.

[`ngrok-gin`](https://pkg.go.dev/github.com/ngrok-samples/ngrok-gin) serves a Gin router through an ngrok endpoint with one call:

```go theme={null}
ngrokgin.Serve(context.Background(), router, ngrokgin.Config{})
```

The library is built on the [Go SDK](https://ngrok.com/docs/getting-started/go.md).
`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.

> [!NOTE]
>
> `ngrok-gin` is published on the Go module proxy at v0.1.0 and maintained in the [ngrok-samples/ngrok-gin](https://github.com/ngrok-samples/ngrok-gin) repository.

## What you'll need

* An [ngrok account](https://dashboard.ngrok.com/signup).
* Your [ngrok auth token](https://dashboard.ngrok.com/get-started/your-authtoken).
* [Go 1.26 or later](https://go.dev/doc/install) installed on your machine.

## 1. Install the library

In your Go module, run:

```bash theme={null}
go get github.com/ngrok-samples/ngrok-gin
```

## 2. Set your auth token

Export your auth token as an environment variable:

```bash theme={null}
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()`:

```go title="main.go" theme={null}
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:

```bash theme={null}
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](https://ngrok.com/docs/gateway/domains.md#dev-domains).
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:

```go theme={null}
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](https://ngrok.com/docs/gateway/domains.md) for the endpoint. An empty string uses your account's dev domain. |
| `Pooling` | `bool` | Opts in to [endpoint pooling](https://ngrok.com/docs/gateway/endpoints/endpoint-pooling.md) so more than one endpoint can share a URL. |
| `TrafficPolicy` | `string` | A raw [Traffic Policy](https://ngrok.com/docs/gateway/traffic-policy.md) document (YAML or JSON) that the library passes through to ngrok unchanged. Use it for [authentication](https://ngrok.com/docs/gateway/traffic-policy/actions/basic-auth.md), [IP restrictions](https://ngrok.com/docs/gateway/traffic-policy/actions/restrict-ips.md), [webhook verification](https://ngrok.com/docs/gateway/traffic-policy/actions/verify-webhook.md), and any other action. |
| `Binding` | `ngrokgin.Binding` | The endpoint's [binding](https://ngrok.com/docs/gateway/endpoints/bindings.md): `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:

```go theme={null}
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](https://ngrok.com/docs/getting-started/go.md) directly.
* An `internal` binding requires a `URL` that ends in `.internal`.
  ngrok rejects any other URL with [`ERR_NGROK_9029`](https://ngrok.com/docs/errors/err_ngrok_9029).
* A URL that another agent or a Cloud Endpoint already claims fails with [`ERR_NGROK_334`](https://ngrok.com/docs/errors/err_ngrok_334).
* Endpoint counts and domains follow your plan's limits.
  See [free plan limits](https://ngrok.com/docs/pricing-limits/free-plan-limits.md).

## What's next?

* Browse [Traffic Policy examples](https://ngrok.com/docs/gateway/traffic-policy/examples/add-authentication.md) to add authentication, restrict access by IP, or rewrite URLs.
* Read the [Go SDK quickstart](https://ngrok.com/docs/getting-started/go.md) to see what the library does under the hood.
* See the [other framework libraries](https://ngrok.com/docs/agent-sdks/frameworks.md) for Next.js, FastAPI, and Axum.
* Report issues or read the source in the [ngrok-samples/ngrok-gin](https://github.com/ngrok-samples/ngrok-gin) repository, which includes runnable examples for every option.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.