Skip to main content

ngrok-go Quickstart

ngrok-go is an open-source, idiomatic package that gives you the functionality of the ngrok agent in a Go library. You can use it to embed secure ingress directly into your Go applications.

This quickstart will use the Agent SDK for ngrok-go to put a Go app on the internet and secure it so that only you can access it.

tip

You may want to open the ngrok-go package documentation on pkg.go.dev as you work through this guide.

Why you should use ngrok-go​

With ngrok-go, you can serve Go applications on the internet in a single line of code without configuring low-level network primitives like IPs, certificates, load balancers and even ports. Applications using ngrok-go listen on ngrok’s global network and your app gets the same net.Listener interface it would get if it had listened on a local port. This makes it incredibly simple to drop ngrok-go into any existing Go code.

What you'll need​

  1. An ngrok account.
  2. Your ngrok authtoken, which you can find in the dashboard.
  3. Go installed on your machine. You can check this by running go version in your terminal.

1. Install ngrok-go​

Create a new Go module and install ngrok-go.

Loading…

2. Create your app​

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

In the ngrok-go-quickstart directory, create the following main.go file:

Loading…

3. Run the example​

  1. If you haven't yet, copy your authtoken from the ngrok dashboard.
  2. Run your application with your authtoken in the environment:
Loading…

Your Go application should be live on the internet, with a URL that anyone on the internet can access.

Your app's randomly-assigned URL will be available in the terminal. When you visit the URL, you should see "Hello from ngrok-go!" in your browser. Try sending it to a friend.

Secure your app​

Once you've completed the quickstart, you can explore other features of ngrok with ngrok-go, such as Requiring authentication to access your app. You may not want everyone to be able to access your application. ngrok can quickly add authentication to your app with a few lines of code.

The following example only grants access to users whose email address is alan@example.com.

You can also add authentication directly in your code.

The following example:

  1. Requires visitors to authenticate with Google before they access your application. You can choose other providers.
  2. Only allows alan@example.com access to the application
  3. Prints the authenticated user's email address from a request header.
Loading…

Run your app again and visit the URL it prints in the terminal.

Anyone accessing your app will be prompted to log in with Google and only your account will be allowed to access it. Keep in mind that when you restarted ngrok, your app's URL changed, so make sure to visit the new one.

Next Steps​