Site-to-site installation guide for end customers

Overview

Why am I being asked to install ngrok?

Your vendor wants to create a secure persistent connection between your network and theirs, which allows them to access and take action on your services and data. We call this site-to-site connectivity.

What is ngrok?

ngrok is a universal gateway—an all-in-one reverse proxy, API gateway, Kubernetes ingress, firewall, and global load balancer to deliver apps and APIs.

Why are we using ngrok instead of other solutions, like a VPN or opening ports?

ngrok is simpler and more secure than these other solutions for a few reasons:

• ngrok does not require you to open inbound ports in your network to the public internet.
• ngrok’s agent is infrastructure-agnostic, operating the same way in any cloud, region, or environment.
• The agent is simpler to configure, deploy, and maintain than VPNs or VPC peering by collapsing many networking components, like load balancing, encryption, certificate management, and authentication into a unified platform.
• ngrok’s network includes DDoS protection and global acceleration for all connections through the Global Server Load Balancer (GSLB).

Who else uses ngrok to provide access to private services?

Organizations worldwide trust ngrok for site-to-site connectivity, unified ingress, device gateways, and developer productivity. Our customers include Twilio, Databricks, Okta, Zoom, Microsoft, Zendesk, Cyera and many more.

You can learn more about our customers and read case studies about their successes on our customers page.

Who is ngrok? Where is it based?

ngrok was first released in 2013 as an open-source project by Alan Shreve, who founded ngrok as a company in 2015 and remains our CEO. Our executive team has extensive experience at companies building distributed systems and winning organization cultures.

In December 2022, ngrok closed $50 million in Series A funding with Lightspeed Venture Partners and Coatue.

ngrok is headquartered in San Francisco, and has a remote workforce primarily located in the U.S.

Can I trust ngrok as a company?

More than 7 million developers use ngrok. We’re recommended by category leaders including Twilio, GitHub, Okta, Microsoft, Zoom, and Shopify. We operate a global network and we have handled over 100 trillion total requests.

Databricks, the leading unified lakehouse platform for data, analytics, and AI, uses ngrok for its site-to-site connectivity across all of its customers.

How ngrok works

How does ngrok work?

ngrok has three primitives: the network, the agent, and the dashboard.

• The network is a globally distributed infrastructure that accepts traffic to endpoints, applies policies, and routes connections to the appropriate agent.
• The agent is a lightweight program with zero runtime dependencies, which forwards requests from your vendor to your upstream services and data.
• The dashboard is a SaaS web app for configuring accounts, endpoints, and access policy. Depending on the architecture and arrangement with your vendor, you may or may not have access to an ngrok dashboard.

In a generic site-to-site connectivity architecture, these pieces come together to do the following:

1. The ngrok agent in your network connects to one or more of your upstream services.
2. The ngrok agent connects out to the ngrok network at the default agent ingress address at connect.ngrok-agent.com (or a custom one).
3. The ngrok network creates an endpoint like your-company.your-vendor.com, which then points to your upstream service.
4. Your vendor sends requests from their services to the endpoint, which are then routed through to the agent and finally your upstream service.

What is ngrok’s network architecture?

We run ngrok’s primary network and services on AWS.

This architecture includes multiple Points of Presence (PoPs) worldwide that run our services, route customer traffic, and make up our always-on Global Server Load Balancer (GSLB).

The GSLB, which is active by default for all ngrok endpoints and tunnels, enhances the resiliency of the connection between your services and your vendor’s with DDoS protection and geo-failover that automatically routes traffic to the lowest-latency PoP in the event of downtime or service interruption. If you have specific data residency requirements, like those located in the EU, you and your vendor can configure ngrok to use a specific region in Europe or pin all traffic to a specific PoP.

There are many possible architectures for setting up a site-to-site network based on the shared requirements of you and your vendor. Your vendor will work with you to find a mutually secure and reliable architecture.

How does ngrok handle data residency requests?

ngrok is user-configurable to match your data residency needs.

First, configure the agent to use a PoP in one of our supported regions. Next, work with your vendor to set up appropriate DNS to route all connections through the same data plane.

Our regional data planes are located in Australia (Sydney), Europe (Frankfurt), India (Mumbai), Japan (Tokyo), South America (São Paulo), United States (California and Ohio).

Is ngrok a dedicated instance or multi-tenant?

ngrok is a multi-tenant application with services shared across our customer base, including your vendor and your site-to-site architecture.

Security

How can I ensure ngrok does not pose a security risk to my infrastructure?

We recommend you begin by exploring our Security, Privacy, and Compliance page, followed by our Trust Center.

ngrok is deeply configurable to enforce your established security policies, including:

• Prevent unauthorized usage of ngrok outside of the site-to-site connectivity with your vendor.
• Create a single account tenant, enforce Account Domain Controls to route all ngrok users with an email address @your-company.com into it, and enable role-based access controls to limit those accounts.
• Create bot users to create authtokens not tied to any individual user, and use a different, scoped authtoken for each agent.
• Apply Access Control Lists (ACLs) to authtokens to control where ngrok agents can be created within your network.
• Enable the IP restrictions action on your endpoint(s) to allow only trusted connections from your vendor.
• Enforce basic auth, OAuth, OpenID, SAML, JWT, or mTLS authentication on your endpoint(s).

How does ngrok’s traffic encryption work?

The agent always connects to the ngrok network via TLS. We support three encryption models based on where TLS is terminated:

1. TLS termination at the ngrok network. This is the default behavior when using HTTPS tunnels, where ngrok manages TLS certificate generation and renewal for both you and your vendor.
2. TLS termination at the ngrok agent. Often referred to as zero-knowledge TLS, this model encrypts your TLS tunnels end-to-end, using filesystem paths to your TLS certificate and key, without requiring you to reconfigure your upstream service for TLS termination.
3. TLS termination at your upstream service. This model implements end-to-end zero-knowledge encryption, where the ngrok network forwards unterminated connections through to your upstream application.

Is my data end-to-end encrypted?

Yes—if you terminate TLS at the ngrok agent or your upstream service using the second or third models listed above.

Contact your vendor if you’re unsure how TLS termination is managed in your site-to-site connectivity architecture.

Can ngrok see my traffic?

No—if you terminate TLS at the agent or your upstream service.

In all encryption models, the ngrok agent cannot see the traffic it forwards on to your upstream service.

If your vendor requests HTTP tunnels for your site-to-site connectivity use case and also uses the Traffic Inspector feature, then ngrok can see and will store up to 90 days of metadata about each request and response. If your vendor enables Full Capture mode, ngrok also stores the full request and response parameters, headers, and bodies for each traffic event.

Can I set up deep packet inspection or observe what data transmits through ngrok?

Yes.

You can configure the ngrok agent to trust a specific root certificate you own on the host’s OS or a specific PEM file on disk instead of the trusted certificate root for the ngrok network. You can then use a proxy for deep packet inspection. Read our root certificate authority documentation for details.

Alternatively, you can set up a bypass rule for connect.ngrok-agent.com (or a custom agent ingress address) to not perform TLS inspection.

You can also set up software between the ngrok agent and your upstream service, or the ngrok agent and the ngrok network, to see what’s transmitted through ngrok.

Work with your vendor to ensure these inspection and observability strategies work within your site-to-site architecture.

How can I prevent ngrok from being used for any purpose other than in site-to-site connectivity with my vendor?

The best way to disallow other uses of ngrok on your network is working with your vendor to specify a custom agent ingress address.

Your vendor will configure their DNS to issue certificates for the custom address, such as your-company.us.connect.your-vendor.com:443. Then they’ll work with you to reconfigure your ngrok agents to utilize the custom ingress address.

We can also provision dedicated IPs for your custom agent ingress address, allowing you to whitelist addresses unique to your site-to-site configuration. Please reach out to your vendor if you’re interested in dedicated IPs.

At this point, you can block the default agent ingress address at connect.ngrok-agent.com:443, which all agents use by default to connect outbound to ngrok’s network. This address resolves to a dynamic set of IP addresses, and blocking it at your network prevents any usage outside of this site-to-site connectivity use case in partnership with your vendor, such as developers utilizing ngrok to tunnel local development environments to the public internet.

You should also block the ngrok-managed public domains:

• ngrok.app
• ngrok.dev
• ngrok-free.app
• ngrok-free.dev
• ngrok.io
• ngrok.pizza
• ngrok.pro

How can we mitigate the risk of abuse?

ngrok has a multi-pronged strategy for combating malicious use of our network, including automated systems that flag suspicious activity. We also disincentivize abuse through product restrictions on free and unverified ngrok accounts.

Work with your vendor to design an architecture that prevents unauthorized use and uses the appropriate encryption model between your services.

See our abuse page for details.

Privacy and compliance

What compliance certifications does ngrok maintain?

ngrok complies with SOC 2, GDPR, EU-US DPF, and CCPA.

You can request our SOC 2 report and view other documents about ngrok’s security measures, like annual penetration testing, on our Trust Center.

What data does ngrok have access to, and how long is it stored?

ngrok’s access to your data depends on the encryption model specified by your site-to-site connectivity architecture—reach out to your vendor for more details.

In all cases, ngrok stores information about the machine where you run your agent, such as its IP address, operating system, CPU architecture, and anonymized details about the environment.

ngrok also logs changes to account configurations, such as agent start/stop, API key creation, and more. You can see the list in our Event Store documentation.

We retain data about your site-to-site connection at the direction of your vendor, who can also delete data at any time.

Read our primer on data at ngrok for more details.

What security practices does ngrok follow?

ngrok uses the shared security responsibility model where we are responsible for the security of our network, and we deliver features you can configure to secure your services. You and your vendor are responsible for securing your site-to-site connectivity architecture.

Our fundamental security practices include access control via an identity provider, change management, full encryption at rest, and much more.

See our Security, Privacy, and Compliance and Trust Center pages for details.

Operations and agent deployment

Where can I run the ngrok agent and what are the ngrok agent’s system requirements?

The ngrok agent runs on Linux, Windows, and macOS systems and most CPU architectures, which you can get from our agent downloads page.

We also distribute the agent as SDKs, a Docker container, and a Kubernetes Operator.

See our supported platforms documentation for details about supported CPU architectures and resource requirements.

How do we manage the lifecycle and maintenance of the agent?

First, we recommend configuring your ngrok agent to run in the background as a native operating system service. This functionality works on all Linux, Windows, and macOS systems, and once installed, the ngrok service starts at boot-time, automatically restarts after crashes, and sends logs to your system’s native logging service.

If you deploy the ngrok agent with Docker, you can utilize Docker’s restart policies or systemd integration; with our Kubernetes Operator, ensure the container restart policy is set to Always.

ngrok releases security and feature updates through all our installation channels and package managers. The process for updating your ngrok agent(s) depends on how you installed them.

• Package manager (brew or apt): Get updated agent versions through the same channel (e.g. brew update && brew upgrade package_name or apt update && apt install ngrok).
• Binary from our downloads page: Follow the same process again or update directly from your CLI with ngrok update.
• Agent SDK: Use the package manager for your language or framework (e.g. go get -u)
• Kubernetes Operator: Use helm upgrade.

Can I run the ngrok agent in a DMZ?

Yes. There are two requirements in this case:

1. The system(s) in your DMZ must support the general system requirements.
2. The upstream service your vendor wants to connect to with ngrok must also be running in your DMZ.

How does the agent connect to the ngrok network?

By default, the ngrok agent attempts to connect to the default agent ingress address at connect.ngrok-agent.com:443, which resolves to a dynamic list of IP addresses. You can view the full list of addresses and IPs available for the agent to connect to in our AWS-hosted tunnel.json file.

This connection includes the following steps:

1. DNS resolution to discover the appropriate connection address.
2. Verification of the TLS certificate returned by the ngrok network, signed by ngrok’s root certificate authority, against the certificate authorities bundled into the agent.
3. A Certificate Revocation List (CRL) check to crl.ngrok-agent.com/ngrok.crl:80 to ensure you never use an ngrok network certificate that has been revoked.

After the agent connects to the network, it also sends heartbeat messages to validate the liveness of the connection, and checks for updates on startup.

How does the agent continue running if my server loses connection or times out?

The ngrok agent utilizes a heartbeat that attempts to reach ngrok’s network every 10 seconds. If the agent doesn’t receive a response within the tolerance window (15 seconds by default), it terminates the existing connection and attempts to reconnect.

This mechanism allows your site-to-site connectivity to automatically reestablish after packet loss, dynamic IP changes, or complete network outages.

You can configure both the heartbeat interval and tolerance per agent.

Who should we contact for support?

If you have trouble installing, updating, or otherwise maintaining the agent process in your network, email our customer success team at support@ngrok.com.

For other issues or concerns around configuring and securing your site-to-site architecture, please contact your vendor.