Agent Ingress Address

Overview

The Agent Ingress Address is the network address that the ngrok agent and agent SDKs use to connect to the ngrok service. The default agent ingress address is connect.ngrok-agent.com:443. This is defined in your agent configuration file under the connect_url parameter.

Customize Agent Ingress Address

You can customize the ingress address by creating your own Agent Ingress. You do this by delegating control of a DNS subdomain. ngrok will then populate the A/AAAA records and issue the certificates for your new agent ingress address. Lastly, you must update the ngrok.yml config file to instruct your ngrok agent to connect to the new address. You can use the helper command ngrok config add-connect-url to do this.

Agents authenticating to your agent ingress address must authenticate to your ngrok account. Agents attempting to authenticate with credentials for other accounts through your ingress address are disallowed.

Create the Agent Ingress

When you create a new agent ingress, you specify the domain you wish to use. You must own this domain yourself and have the ability to create NS records on it via your DNS provider.

• Create a new Agent Ingress on the ngrok Dashboard
• Create a new Agent Ingress via API

note

When creating a new custom agent ingress, there is an option to configure the Certificate Issuer from either ngrok or Let's Encrypt. Some networks do not trust traffic encrypted with our privately issued certificate and will require a public issuer such as Let's Encrypt and this allows you to choose which one is needed.

Delegate DNS records

After you create a new Agent Ingress, you will be prompted to create NS records on the domain you chose.

Update agent configuration

Finally, you must reconfigure your ngrok agent or agent SDKs to use your new agent ingress address by adding the connect_url option to your ngrok agent's configuration file. You can use the helper command ngrok config add-connect-url to do this.

For example, if the domain of your custom agent ingress is ingress.example.com then you might add the following line to the agent's configuration file:

Agent CLI

ngrok config add-connect-url tunnel.us.ingress.example.com:443

Agent Config

server_addr: tunnel.us.ingress.example.com:443

SSH

ssh -R 443:localhost:80 v2@tunnel.us.ingress.example.com http

Go

import (
    "context"
    "net"

    "golang.ngrok.com/ngrok"
    "golang.ngrok.com/ngrok/config"
)

func ngrokListener(ctx context.Context) (net.Listener, error) {
	return ngrok.Listen(ctx,
		config.HTTPEndpoint(),
		ngrok.WithServer("tunnel.us.ingress.example.com:443"),
		ngrok.WithAuthtokenFromEnv(),
	)
}

Go Package Docs:

• https://pkg.go.dev/golang.ngrok.com/ngrok#WithServer

Javascript

const ngrok = require("@ngrok/ngrok");

(async function () {
	const session = await new ngrok.SessionBuilder()
		.authtokenFromEnv()
		.serverAddr("tunnel.us.ingress.example.com:443")
		.connect();

	const listener = await session
		.httpEndpoint()
		.listenAndForward("http://localhost:8080");

	console.log(`Ingress established at: ${listener.url()}`);
})();

Javascript SDK Docs:

• https://ngrok.github.io/ngrok-javascript/classes/SessionBuilder.html#serverAddr

Python

import ngrok, asyncio

async def create_listener() -> ngrok.Listener:
    session: ngrok.Session = (
        await ngrok.SessionBuilder()
        .authtoken_from_env()
        .server_addr("tunnel.us.ingress.example.com:443")
        .connect()
    )

    return (await session.http_endpoint()
        .listen_and_forward("http://localhost:8080"))

listener = asyncio.run(create_listener())

print(f"Ingress established at: {listener.url()}");

Python SDK Docs:

• https://ngrok.github.io/ngrok-python/session_builder.html#ngrok.SessionBuilder.server_addr

Rust

use ngrok::prelude::*;

async fn listen_ngrok() -> anyhow::Result<impl Tunnel> {
    let sess = ngrok::Session::builder()
        .authtoken_from_env()
        .server_addr("tunnel.us.ingress.example.com:443")
        .connect()
        .await?;

    let tun = sess
        .http_endpoint()
        .listen()
        .await?;

    println!("Listening on URL: {:?}", tun.url());

    Ok(tun)
}

Rust Crate Docs:

• https://docs.rs/ngrok/latest/ngrok/session/struct.SessionBuilder.html#method.server_addr

Kubernetes Controller

In your Helm values.yaml file, set

serverAddr: "tunnel.us.ingress.example.com:443"

Incompatibility with GSLB

note

Custom agent ingress requires the you choose a particular region that your agent connects to. It does not yet support Global Server Load Balancing which allows the agent to connect to the closest ngrok point of presence.

Endpoints created by agents using custom agent ingress are still delivered with Global Server Load Balancing.

Dedicated IPs

When you create a custom agent ingress, the DNS, certificates and hostnames are all custom branded but your address will still resolve to ngrok's shared set of IP addresses. Dedicated IPs that are unique for your account are also available at additional cost. Contact us to get in touch for additional details.

Certificate Issuer

When you create a custom agent ingress, you have the option to choose between two certificate issuer options: ngrok's internal CA and a public one from Let's Encrypt.

ngrok's Internal CA

With this option, the agent uses a private cert minted from ngrok. This is the default option and the agent trusts automatically. This cert is provisioned immediately, but may require additional configuration if you are using 3rd party security tools as they most likely won't trust the ngrok-issued certificate.

Let's Encrypt Cert Issuer

This option will request a certificate from Let's Encrypt. This is not automatically trusted by the agent and requires the root_cas option to be set to host, or the Let's Encrypt root cert. In most cases, the host that runs the agent will trust a standard set of public CAs. You will also need this when using any ngrok agent SDK or SSH Reverse Tunnel agent.

This certificate is not immediately provisioned and after provision, could take up to 48 hours if propagation is slow. An ngrok certificate is provisioned and used in the meantime to secure any communication. Note that even if the DNS "Check Status" succeeds in the ngrok dashboard, it may not have propagated to Let's Encrypt yet.

This option is useful if getting an outbound proxy to trust ngrok CA is challenging due to either technical or organizational constraints.

If Let's Encrypt is selected, the agent ingress drawer will show the following card while the certificate is provisioning:

Why customize the ingress address?

Branded Connectivity

If you are using ngrok for production connectivity to your devices in the field or APIs inside of your customers' networks, a custom ingress address allows you to brand ngrok's connectivity as your own.

Policy Enforcement

If you are using ngrok for development and testing, you can use your own ingress address to ensure everyone at your org does not use their personal accounts and instead uses a shared ngrok account with appropriate observability and security controls set up. You can do this by blocking ngrok's default ingress address of from your machines and networks, but allowing traffic to your custom ingress address.

Pricing

Creating your own Agent Ingress is not available on any self-serve plan. Contact us to get in touch about using custom agent ingress.