Skip to main content

Cloud Endpoints Quickstart

Cloud Endpoints provide a persistent way to service traffic. Unlike Agent Endpoints, which are ephemeral and run locally, cloud endpoints run on ngrok's cloud service, allowing you to accept public traffic even if your internal apps or services are down.

Cloud endpoints provide an additional layer of traffic management above agent endpoints and can be used to extend their functionality in several key ways. Using a , a cloud endpoint can route traffic to multiple other endpoints based on criteria such as path, header, IP, and more.

A common use case for this pattern is to create a cloud endpoint that accepts public traffic, authenticates it, then routes it to one of several internal agent endpoints running on machines that require privileged access.

This guide walks you through creating cloud endpoints in two ways: first, through the ngrok dashboard, and second, using the Agent CLI to interact with the ngrok API.

What you'll need​

note

This doc assumes you've already completed the Agent CLI Quickstart—if not, you should start there to learn about some of ngrok's fundamental features before continuing here.

Part one: your first cloud endpoint​

The best way to familiarize yourself with cloud endpoints is to create one in your ngrok dashboard.

1. Reserve your domain​

To establish connectivity for the public cloud endpoint you'll create in this guide, you must first reserve a domain.

Navigate to the dashboard, visit the Domains section, and select + New Domain. You can choose a free static domain, or you can use a custom domain you already own. We'll come back to this in later steps.

2. Install the ngrok Agent CLI​

If this is your first time using ngrok, run the command that corresponds to your operating system to install the Agent CLI:

Loading…

Or follow the direct installation guide if you can't use one of the options above.

To test that it's been installed correctly, run the following command in your terminal and confirm that ngrok prints its help text.

Loading…

3. Connect your account​

Connect your agent to your ngrok account by providing your auth token as shown below—replace $YOUR_TOKEN with the string given to you in the dashboard.

Loading…

4. Create your cloud endpoint in the dashboard​

Click here to create a new cloud endpoint in your dashboard.

There are three bindings to choose from: for this example, select Public. In the URL field, enter the domain you reserved in step 1. Then click Create Cloud Endpoint.

This takes you to a page where you can manage your new endpoint's traffic policy. You can leave all of the default settings in place for now.

info

Traffic policies are optional for agent endpoints but required for cloud endpoints, which is why the dashboard generates one for you automatically.

Visit the URL you specified to confirm that it's online. You should see a default landing page that says "This is your new Cloud Endpoint!"

There are many different things you could do with this endpoint from here. Let's put it to work forwarding traffic to an app running on your local device.

5. Start your app or service​

Start up the app or service you'd like to put online.

If you don't have an app to work with, you can create a minimal app in your language of choice using the following code to set up a basic HTTP server at port 8080.

Loading…

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

Loading…

6. Start your agent endpoint​

Start the ngrok agent by running the following command (replace 8080 if your app is running on a different port):

Loading…

The --url flag connects your agent endpoint to your cloud endpoint, so when requests are made to your reserved domain they'll be routed here. The default URL for this is https://default.internal, which was defined in the traffic policy when you created the cloud endpoint in step 4.

7. Test your cloud endpoint​

Your endpoint should now be online. Visit your reserved domain URL to see the app that's running on your local device.

Part two: creating cloud endpoints via the ngrok API​

Now that you're familiar with the key concepts necessary to work with cloud endpoints, let's create another one using the ngrok API, which you can access via the Agent CLI. (You can use any HTTP client you prefer for interacting with the ngrok API, but the Agent CLI provides a simple and direct access point for getting started.)

Keep your local app and agent endpoint from part one running. If you only have one reserved domain to work with, delete the cloud endpoint you created in the dashboard before continuing so you can reuse the domain in the steps below.

1. Create your traffic policy​

Create a policy.yml on your local machine and add the code snippet below. This policy states that incoming HTTP requests should be forwarded to your internal agent endpoint at https://default.internal; if that endpoint's not reachable, then it falls back on a custom response to indicate that the app is offline.

Loading…

2. Create your cloud endpoint​

Create your cloud endpoint by running the following command—replace $YOUR_API_KEY and $YOUR_DOMAIN with their respective values:

Loading…

This command contains all of the configuration steps you worked through in the dashboard to create a cloud endpoint in part one.

3. Test your endpoint​

Your endpoint should now be online. Visit your reserved domain URL to see the app that's running on your local device.

To see the fallback response, terminate your local app or agent endpoint and then visit your cloud endpoint URL again. You should see the custom message defined in policy.yml.

What's next?​

In this guide, you learned how to create a Cloud Endpoint using both the dashboard and the ngrok API. You configured a basic traffic policy to forward requests from one endpoint to another, and you saw how cloud endpoints can be layered on top of agent endpoints to route traffic to different services and fallback responses based on the criteria you define.