Skip to main content

User Agent Filter


The User Agent Filter module enables you to block bots, crawlers, or certain browsers from accessing your web application. It allows or denies traffic based on the User-Agent header of incoming HTTP requests.

The User-Agent header contains information about the requesting browser or application, including its name, version, and operating system.

You define a set of regular expression rules that either allow or deny HTTP requests if they match the User-Agent header.

Example Usage

ngrok http 80 \
--ua-filter-allow="(foo/(\d)+.(\d)+)","(bar/(\d)+.(\d)+)" \


Rule Evaluation

The User Agent Filter module will check each HTTP request's User-Agent header value against the list of defined allow and deny regular expression rules.

  • Requests without the User-Agent header will be denied by default. To allow these requests, you can add an allow rule for empty strings: ^$
  • If a request has multiple User-Agent headers, only the first header will be checked.

Match Behavior

Requests are allowed if they match any allow rule or fail to match all deny rules.

You can override deny rules by defining an allow rule that is more specific, for instance blocking all Google bots except Google Images:

"allow": ["(?i)google-images"]
"deny": ["(?i)google", "[Bb]ing"]



Agent Configuration
User Agent Filter AllowA set of regular expressions used to match User-Agents that will be allowed.
User Agent Filter DenyA set of regular expressions used to match User-Agents that will be denied.

Upstream Headers

This module does not add any upstream headers.


CodeHTTP StatusError
ERR_NGROK_3211403The server does not authorize requests from your user-agent


When the User Agent Filter module is enabled, it populates the following fields in the http_request_complete.v0 event:



This module is available on all plans.

Try it out

Run ngrok with User Agent Filter's allow and deny set to the following:

ngrok http 80 \
--domain \
--ua-filter-allow="(GoingMerry/(\d)+.(\d)+)","(GomuGomu/(\d)+.(\d)+)" \

Then make requests to your ngrok domain with the following:

curl --location -H 'Content-Type: text/plain' -A 'GoingMerry/1.1' --data '' -k -v
curl --location -H 'Content-Type: text/plain' -A 'GomuGomu/1.1' --data '' -k -v
curl --location -H 'Content-Type: text/plain' -A 'Xebec/1.1' --data '' -k -v
curl --location -H 'Content-Type: text/plain' -A '' --data '' -k -v
curl --location -H 'Content-Type: text/plain' -A 'TwitterBot/1.1' --data '' -k -v