Go SDK Quickstart - ngrok documentation

Give this to your AI coding agent to complete the full quickstart automatically.

The ngrok Go SDK is an open-source, idiomatic Go package that enables you to quickly and efficiently serve Go applications on the internet without the need to configure low-level network primitives like IPs, certificates, load balancers, or ports. You can think of it as the ngrok Agent CLI packaged as a Go library. This quickstart uses the ngrok Go SDK to create an Agent Endpoint that forwards traffic from the internet to a Go app running on your local device, then secure it by requiring visitors to log in with a Google account to access it.

If you’d prefer to skip the boilerplate setup, you can clone the complete example from the ngrok-samples collection. In that case, you just need to reserve a domain and add your auth token as described below to get started.

What you’ll need

An ngrok account.
Your ngrok auth token.
Go installed on your machine. You can check this by running go version in your terminal.

Start your app or service

Start up the app or service you’d like to put online. This is the app that your Agent Endpoint forwards online traffic to.If you don’t have an app to work with, you can create a minimal Go app using the following code to set up a basic HTTP server at port 8080.

service.go

package main

import (
	"fmt"
	"net/http"
)

func handler(w http.ResponseWriter, r *http.Request) {
	fmt.Fprintf(w, "Hello from Go HTTP Server!")
}

func main() {
	http.HandleFunc("/", handler)

	fmt.Println("Starting server at http://localhost:8080")
	err := http.ListenAndServe(":8080", nil)
	if err != nil {
		fmt.Println("Server failed:", err)
	}
}

Navigate to the directory where this file is located and run the following command to start the server:

go run service.go

Install the Go SDK

Open a new terminal, then run the following commands to create a new Go module and install the SDK:

mkdir ngrok-go-demo
cd ngrok-go-demo
go mod init ngrok-go-demo
go get golang.ngrok.com/ngrok/v2

Create a .env file

Create a .env file and add your ngrok auth token and reserved domain to it. This file needs to be in the same directory where you initialized your Go module in the previous step. Run the following command to create the .env file:

touch .env

Add your ngrok auth token and reserved domain to this file:

.env

NGROK_AUTHTOKEN=your_actual_auth_token_here
NGROK_DOMAIN=your_actual_domain_here

Finally, install the godotenv package to access your environment variables from your code:

go get github.com/joho/godotenv

If you don’t want to use a .env file, you can instead export your auth token as an environment variable in your terminal session, or call ngrok.WithAuthToken("your-token") in your code.You can set your reserved domain directly in your endpoint file below using ngrok.WithURL().

Create your endpoint

Create your Agent Endpoint, which forwards public traffic to your app.Create a new file named endpoint.go in the same directory as your .env file and add the following code. This example:

Starts an Agent Endpoint that forwards from your reserved domain to your service running on port 8080.
Secures the endpoint with a Traffic Policy that requires authentication via Google OAuth.

This example uses ngrok’s default Google OAuth application. To use your own, see the OAuth Traffic Policy Action documentation.

endpoint.go

package main

import (
	"context"
	"fmt"
	"log"
	"os"

	"github.com/joho/godotenv"
	"golang.ngrok.com/ngrok/v2"
)

func main() {
	if err := godotenv.Load(".env"); err != nil {
		log.Fatal("Error loading .env file", err)
	}
	if err := run(context.Background()); err != nil {
		log.Fatal(err)
	}
}

const trafficPolicy = `
on_http_request:
  - actions:
      - type: oauth
        config:
          provider: google
`
const address = "http://localhost:8080"

func run(ctx context.Context) error {
	agent, err := ngrok.NewAgent(ngrok.WithAuthtoken(os.Getenv("NGROK_AUTHTOKEN")))
	if err != nil {
	    return err
	}

	ln, err := agent.Forward(ctx,
		ngrok.WithUpstream(address),
		ngrok.WithURL(os.Getenv("NGROK_DOMAIN")),
		ngrok.WithTrafficPolicy(trafficPolicy),
	)

	if err != nil {
		fmt.Println("Error", err)
		return err
	}

	fmt.Println("Endpoint online: forwarding from", ln.URL(), "to", address)

	// Explicitly stop forwarding; otherwise it runs indefinitely
	<-ln.Done()
	return nil
}

Test your endpoint

Test your endpoint by running the following terminal command:

go run endpoint.go

This prints your reserved domain URL to the terminal. When you visit the URL, ngrok prompts you to log in with Google. After you log in, you see your app or service.If you used the example app in this quickstart, you see “Hello from Go HTTP Server!” displayed in your browser.

What’s next?

In this guide, you learned how to use the Go SDK to create an Agent Endpoint that forwards traffic to your localhost. You saw one way to implement a Traffic Policy directly in your codebase, including an action that adds authentication to your app with no configuration required. What else can you do with these features?

Dig deeper into Traffic Policies, which enable you to grant conditional access, send custom headers, rewrite URLs, and more with your endpoints.
Learn more about the Agent SDKs to understand how the Go SDK works under the hood.
Building with Gin? Serve your router through ngrok in one call using the Gin library.
Check out the ngrok Go SDK repo for more code examples.
If your use case calls for a centrally managed, always-on endpoint instead of one that’s only available when an agent is running, proceed to getting started with Cloud Endpoints.

​What you’ll need

Start your app or service

Install the Go SDK

Create a .env file

Create your endpoint

Test your endpoint

​What’s next?

What you’ll need

What’s next?