> ## Documentation Index
> Fetch the complete documentation index at: https://ngrok.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Why Your Vendor Uses ngrok

> Why your vendor has requested you install ngrok for site-to-site connectivity, how it works, and why it's secure.

## Overview

### Why you're 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. This is called [**site-to-site connectivity**](https://ngrok.com/use-cases/site-to-site-connectivity).

Your vendor will create the required configuration files and deployment strategy
and share them with you directly. You must contact with your vendor to request
changes to that configuration, including those based on the content of this
document.

### What is ngrok?

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

### Why is ngrok used 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](https://ngrok.com/blog-post/gslb-global-server-load-balancing) (GSLB).

ngrok's solution supports multiple models for TLS encryption, including end-to-end encryption. Learn more about how your vendor can configure ngrok's encryption: [How does ngrok's traffic encryption work?](#ngrok-traffic-encryption)

### 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.
Customers include Twilio, Okta, Zoom, Microsoft, Zendesk, Cyera, and many more.

[Databricks](https://ngrok.com/customers/databricks), the leading unified lakehouse platform for data, analytics, and AI, uses ngrok for its site-to-site connectivity across all of its customers.

You can learn more about customers and read case studies about their successes on the [customers page](https://ngrok.com/customers).

### 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 the CEO. The 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](https://techcrunch.com/2022/12/13/ngrok-a-service-to-help-devs-deploy-sites-services-and-apps-raises-50m/) with [Lightspeed Venture Partners](https://lsvp.com/) and [Coatue](https://www.coatue.com/).

ngrok has a primarily U.S.-based workforce. More information on the geographic
distribution of full time employees and contractors can be found at the [Trust
Center](https://trust.ngrok.com).

### Can ngrok be trusted as a company?

More than 7 million developers use ngrok. It is recommended by category leaders including Twilio, GitHub, Okta, Microsoft, Zoom, and Shopify. ngrok operates a global network and has handled over 100 trillion total requests.

ngrok is SOC 2 Type 2 compliant, which certifies that security processes and
operations meet AICPA's criteria for security. ngrok is also CCPA, EU-US DPF, and
GDPR compliant.

## How ngrok works

### How does ngrok work?

ngrok has three primitives: the **cloud service**, the [**agent**](/agent/), and the [**dashboard**](https://dashboard.ngrok.com/).

* The cloud service is 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 [Connect URL](/agent/connect-url/) 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?

ngrok's primary network and services run on AWS.

This architecture includes multiple [Points of Presence](/gateway/points-of-presence/) (PoPs) worldwide that run services, route customer traffic, and make up the always-on [Global Server Load Balancer](https://ngrok.com/blog-post/gslb-global-server-load-balancing) (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), then 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?

Your vendor can configure your site-to-site architecture to match your data residency needs.

They will first [configure the
agent](/agent/changelog/) to
use a PoP in one of the [supported
regions](/gateway/points-of-presence/), then work with you to set up
appropriate DNS to route all connections through the same data plane.

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 the customer base, including your vendor and your site-to-site architecture.

## Security

### How to ensure ngrok does not pose a security risk to your infrastructure

It is recommended to begin by exploring the [Security, Privacy, and Compliance](https://ngrok.com/security) page, followed by the [Trust Center](https://trust.ngrok.com/).

Your vendor can implement multiple security practices, including:

* [Prevent unauthorized usage of
  ngrok](#how-can-i-prevent-ngrok-from-being-used-for-any-purpose-other-than-in-site-to-site-connectivity-with-my-vendor?)
  outside of the site-to-site connectivity with your vendor.
* Create a single account tenant, enforce [Account Domain
  Controls](https://ngrok.com/blog-post/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 [Service Users](/iam/service-users/) to create authtokens not tied
  to any individual user, and use a different, scoped authtoken for each agent.
* Apply [Access Control
  Lists](/iam/rbac/#additional-restrictions-with-acls) (ACLs) to authtokens
  to control where ngrok agents can be created within your network.
* Enable the [IP restrictions](/traffic-policy/actions/restrict-ips/)
  action on your endpoints to allow only trusted connections from your vendor.
* Enforce [basic auth](/traffic-policy/actions/basic-auth/), [OAuth](/traffic-policy/actions/oauth/),
  [OpenID](/traffic-policy/actions/oidc/),
  [JWT](/traffic-policy/actions/jwt-validation/),
  [SAML](/traffic-policy/actions/saml), or
  [mTLS](/agent/agent-mutual-tls-termination/)
  authentication on your endpoints.

The configuration and operation of these security practices will be handled by
your vendor.

### How does ngrok's traffic encryption work?

The agent always connects to the ngrok network via TLS. Three encryption models are supported 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](/gateway/tls-termination/#end-to-end-encryption), 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](/gateway/tls-termination/#end-to-end-encryption), where the ngrok network forwards unterminated connections through to your upstream application.

### Is data transmitted through ngrok end-to-end encrypted?

Yes—if you vendor configures ngrok to terminate TLS at the 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 the traffic it forwards?

No—if your vendor configures ngrok to 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](/obs/traffic-inspection/#ngrok-traffic-inspector) feature, then
ngrok can [see and will
store](https://ngrok.com/blog-post/data-at-ngrok#traffic-inspector-provides-network-traffic-observability-throughout-the-ngrok-platform)
up to 90 days of metadata about each request and response. If your vendor
enables [Full Capture mode](/obs/traffic-inspection/#full-capture-mode),
ngrok also stores the full request and response parameters, headers, and bodies
for each traffic event.

### Does ngrok support deep packet inspection or observing what data is transmitted through ngrok?

Yes. Your vendor can configure your site-to-site connectivity architecture in a
few ways to enable this functionality. They can:

1. Configure your ngrok agent to trust a [specific
   root certificate](/agent/config/v3/#connect-cas) 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.
2. Require the outbound connection to `connect.ngrok-agent.com:443` go through a
   proxy capable of inspection.
3. Set up a bypass rule for `connect.ngrok-agent.com:443` (or a custom Connect URL
   hostname) to not perform TLS inspection.
4. Help you 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.

In any case, your vendor is responsible for configuring these inspection
strategies for your site-to-site architecture.

### How to prevent ngrok from being used for any purpose other than in site-to-site connectivity with your vendor

The best way to disallow other uses of ngrok on your network is working with your vendor to specify a [custom Connect URL](/agent/connect-url/#custom-connect-url).

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](/agent/connect-url/) to utilize the custom Connect URL.

Your vendor can also work with ngrok to provision dedicated IPs for their custom Connect URL.

At this point, you can block the default Connect URL 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](/gateway/domains/#ngrok-managed-domains), for example, `ngrok.app`, `ngrok.io`, etc.

Work with your vendor to design an architecture that [prevents unauthorized
use](#how-can-i-prevent-ngrok-from-being-used-for-any-purpose-other-than-in-site-to-site-connectivity-with-my-vendor?)
and uses the appropriate [encryption model](#ngrok-traffic-encryption) between
your services.

### How does ngrok mitigate abuse of its platform?

ngrok has a multi-pronged strategy for combating malicious use of the network,
including automated systems that flag suspicious activity in combination with
human moderation.

ngrok works with authorized third-party security vendors, who report suspected
abuse to [abuse@ngrok.com](mailto:abuse@ngrok.com) or the [abuse
API](/api-reference/abusereports/create). The abuse response team investigates
these reports, collaborates with these third parties, and proactively shuts down
attacks.

Various passive abuse prevention techniques are employed, such as restricting
product usage for free and unverified ngrok accounts. The [IP
Intelligence](/traffic-policy/variables/ip-intel/) system is also used to prevent
signups from IPs on trusted blocklists, from specific regions, and those using
anonymous proxies. Finally, global firewalls protect against unauthorized
access and DDoS attacks.

See the [abuse page](https://ngrok.com/abuse) for more details.

## Privacy and compliance

### What compliance certifications does ngrok maintain?

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

You can request the SOC 2 report and view other documents about ngrok's security
measures, like annual penetration testing, on the [Trust
Center](https://trust.ngrok.com/).

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

ngrok's access to your data depends on the [encryption model](#ngrok-traffic-encryption) 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 the [Log Store](/obs/events/reference/) documentation.

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

Read the [primer on data at ngrok](https://ngrok.com/blog-post/data-at-ngrok) for more details.

### Where does data transmitted through ngrok go?

ngrok is split into a control plane and data plane. The control plane is
responsible for handling API requests and is the source of truth for account and
user data. The data planes are responsible for hosting the tunnels and routing
the customer traffic. ngrok also leverages several third party providers when
handling customer data.

Control Plane: Any information stored by ngrok would reside in the control
plane. This is hosted out of a U.S.-based AWS region.

Data Plane: Customer traffic runs through ngrok's regional data planes, located
in Australia (Sydney), Europe (Frankfurt), India (Mumbai), Japan (Tokyo), South
America (São Paulo), United States (California and Ohio)\*.

By default, ngrok will route traffic via the most low latency route. Customers
can control which regional data plane their tunnels connect to via the agent
configuration and which regional data plane their customers connect into via
DNS. If a region is specified, customer traffic will only be routed through that
region.

### What security practices does ngrok follow?

ngrok uses the shared security responsibility model where ngrok is responsible for the security of the network, and delivers features your vendor can use to configure and secure your site-to-site connectivity architecture.

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

See the [Security, Privacy, and Compliance](https://ngrok.com/security) and [Trust Center](https://trust.ngrok.com/) pages for details.

## Operations and Agent deployment

### Where can the ngrok Agent be run and what are the system requirements?

The ngrok agent runs on Linux, Windows, and macOS systems and most CPU
architectures. See the [supported platforms
documentation](/agent/#system-requirements) for details about supported CPU
architectures and resource requirements.

The agent is also distributed as [SDKs](/agent-sdks/), a
[Docker container](https://hub.docker.com/r/ngrok/ngrok), and a [Kubernetes
Operator](/k8s/).

Your vendor will work with you to find the right form factor for your
site-to-site connectivity architecture.

### How to manage the lifecycle and maintenance of the Agent

Your vendor is responsible for helping you configure and maintain your agents.

They might configure your ngrok agent to [run in the background](/agent/#background-service) 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 they suggest deploying with Docker, they will likely recommend Docker's
[restart
policies](https://docs.docker.com/engine/reference/run/#restart-policies-restart)
or [systemd
integration](https://docs.docker.com/engine/install/linux-postinstall/#configure-docker-to-start-on-boot-with-systemd);
with the [Kubernetes Operator](/k8s/), they will recommend the [container
restart
policy](https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle/#restart-policy)
is set to `Always`.

ngrok releases security and feature updates through all installation
channels and package managers. These updates are *not* automatic. Do not update
your ngrok agents manually—your vendor will work with you on when and how
to update your ngrok agents because the process depends on how they asked you
to install them.

* Package manager (`brew` or `apt`): Get updated agent versions through the same channel (for example, `brew update && brew upgrade package_name` or `apt update && apt install ngrok`).
* Binary from the [downloads page](https://download.ngrok.com): Follow the same process again or [update directly from your CLI](/agent/#updates) with `ngrok update`.
* Agent SDK: Use the package manager for your language or framework (for example, `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 systems in your DMZ must support the general [system requirements](#where-can-i-run-the-ngrok-agent-and-what-are-the-ngrok-agent's-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 Connect URL 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 the [AWS-hosted `tunnel.json` file](https://s3.amazonaws.com/dns.ngrok.com/tunnel.json).

This connection includes the following steps:

1. [DNS resolution](/agent/#dns-resolution) to discover the appropriate connection address.
2. [Verification](/agent/#tls-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](/agent/#heartbeats) messages to validate the liveness of the connection, and [checks for updates](/agent/#ngrok-agent-update-check) on startup.

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

The ngrok agent utilizes a [heartbeat](/agent/#heartbeats) 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.

Your vendor can [configure](/agent/config/v3/#heartbeat-interval) both the
heartbeat interval and tolerance per agent.

### How does using ngrok, and the availability of the platform, affect your own?

ngrok is only utilized for connectivity to the agent. It won't affect the rest
of your platform in any way. The ngrok platform is designed for high
availability. It operates out of 8 separate isolated regions and multiple
availability zones in each region within the AWS network. Your traffic will take
the lowest latency path to the ngrok servers and will fail over to a secondary
region in the case of network outages or infrastructure failures.

### Who to contact for support

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