Cloud Endpoints provide a persistent way to service traffic. Unlike Agent Endpoints, which are only available as long as the agent is running, 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 Traffic Policy, 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

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. 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: 
brew install ngrok
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. 
ngrok help

​
2. 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. 
ngrok config add-authtoken $YOUR_TOKEN

​
3. 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.
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.

​
4. 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. 
const http = require('http');

const server = http.createServer((req, res) => {
res.writeHead(200, { 'Content-Type': 'text/html' });
const html = `     <html>
    <head><title>Test Page</title></head>
    <body><h1>Hello from Node.js HTTP Server!</h1></body>
    </html>
    `;
res.end(html);
});

const port = 8080;
server.listen(port, () => {
console.log(`Serving custom HTML at http://localhost:${port}`);
});
Navigate to the directory where this file is located and run the following command to start the server:
node service.js

​
5. Start your agent endpoint

Start the ngrok agent by running the following command (replace 8080 if your app is running on a different port): 
ngrok http 8080 --url https://default.internal
The --url flag connects your agent endpoint to your cloud endpoint, so when requests are made to your 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.

​
6. Test your cloud endpoint

Your endpoint should now be online. Visit your 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 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.
policy.yml
on_http_request:
  - actions:
      - type: "forward-internal"
        config:
          url: "https://default.internal"
         on_error: continue
      - type: custom-response
        config:
          status_code: 200
          headers:
            content-type: text/html
          body: |
             <b>Agent offline!</b>
             <p>Run <code>ngrok http 80 --url https://default.internal</code> to put your application online!</p>

​
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: 
ngrok api endpoints create \
 --api-key $YOUR_API_KEY \
 --description "Cloud endpoint for my API" \
 --type cloud \
 --bindings public \
 --url `$YOUR_DOMAIN` \
 --traffic-policy-file policy.yml
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. What else can you do with these features?