{"id":13431165,"url":"https://github.com/bubenshchykov/ngrok","last_synced_at":"2025-04-29T18:52:48.984Z","repository":{"id":11798734,"uuid":"14343981","full_name":"bubenshchykov/ngrok","owner":"bubenshchykov","description":"Expose your localhost to the web. Node wrapper for ngrok.","archived":false,"fork":false,"pushed_at":"2024-05-21T23:43:21.000Z","size":28429,"stargazers_count":2326,"open_issues_count":40,"forks_count":317,"subscribers_count":45,"default_branch":"master","last_synced_at":"2024-10-29T14:57:05.642Z","etag":null,"topics":["localhost","ngrok","tunnel","tunneling","webhook"],"latest_commit_sha":null,"homepage":"https://ngrok.com","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":"react-native-community/react-native-video","license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bubenshchykov.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2013-11-12T20:18:22.000Z","updated_at":"2024-10-25T09:43:44.000Z","dependencies_parsed_at":"2024-11-20T13:39:09.413Z","dependency_job_id":null,"html_url":"https://github.com/bubenshchykov/ngrok","commit_stats":{"total_commits":339,"total_committers":59,"mean_commits":5.745762711864407,"dds":0.4926253687315634,"last_synced_commit":"c95c089eab0441c3aad2d4ba6a7c3ca6baaf1d30"},"previous_names":[],"tags_count":15,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bubenshchykov%2Fngrok","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bubenshchykov%2Fngrok/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bubenshchykov%2Fngrok/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bubenshchykov%2Fngrok/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bubenshchykov","download_url":"https://codeload.github.com/bubenshchykov/ngrok/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247953759,"owners_count":21024082,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["localhost","ngrok","tunnel","tunneling","webhook"],"created_at":"2024-07-31T02:01:00.997Z","updated_at":"2025-04-09T01:20:53.618Z","avatar_url":"https://github.com/bubenshchykov.png","language":"JavaScript","funding_links":[],"categories":["JavaScript","\u003ca id=\"1a9934198e37d6d06b881705b863afc8\"\u003e\u003c/a\u003e通信\u0026\u0026代理\u0026\u0026反向代理\u0026\u0026隧道","others","Uncategorized","\u003ca id=\"01e6651181d405ecdcd92a452989e7e0\"\u003e\u003c/a\u003e工具"],"sub_categories":["\u003ca id=\"56acb7c49c828d4715dce57410d490d1\"\u003e\u003c/a\u003e未分类-Proxy","Uncategorized","\u003ca id=\"8ea8f890cf767c3801b5e7951fca3570\"\u003e\u003c/a\u003e公网访问局域网"],"readme":"# ngrok [![Tests](https://github.com/bubenshchykov/ngrok/workflows/Tests/badge.svg)](https://github.com/bubenshchykov/ngrok/actions) ![TypeScript compatible](https://img.shields.io/badge/typescript-compatible-brightgreen.svg) [![npm](https://img.shields.io/npm/v/ngrok.svg)](https://www.npmjs.com/package/ngrok) [![npm](https://img.shields.io/npm/dm/ngrok.svg)](https://www.npmjs.com/package/ngrok)\n\nThis project is the Node.js wrapper for the [ngrok client](https://ngrok.com/download). Version 5 of this project uses ngrok client version 3. For ngrok client version 2, check out version 4.\n\n![alt ngrok.com](https://ngrok.com/static/img/overview.png)\n\n* [Usage](#usage)\n  * [Local install](#local-install)\n  * [Global install](#global-install)\n  * [Auth Token](#auth-token)\n  * [Connect](#connect)\n    * [Options](#options)\n  * [Disconnect](#disconnect)\n  * [Config](#config)\n    * [Updating config for ngrok version 3](#updating-config-for-ngrok-version-3)\n  * [Inspector](#inspector)\n  * [API](#api)\n    * [List tunnels](#list-tunnels)\n    * [Start tunnel](#start-tunnel)\n    * [Get tunnel details](#get-tunnel-details)\n    * [Stop tunnel](#stop-tunnel)\n    * [List requests](#list-requests)\n    * [Replay request](#replay-request)\n    * [Delete all requests](#delete-all-requests)\n    * [Request detail](#request-detail)\n  * [Proxy](#proxy)\n* [How it works](#how-it-works)\n* [ngrok binary update](#ngrok-binary-update)\n* [Using with nodemon](#using-with-nodemon)\n* [Contributors](#contributors)\n* [Upgrading to version 5](#upgrading-to-version-5)\n  * [Config](#config-1)\n  * [Connect options](#connect-options)\n* [Upgrading to version 4](#upgrading-to-version-4)\n  * [TypeScript](#typescript)\n\n## Usage\n\n### Local install\n\nInstall the package with npm:\n\n```bash\nnpm install ngrok\n```\n\nThen use `ngrok.connect()` to start ngrok and open a tunnel.\n\n```javascript\nconst ngrok = require('ngrok');\n(async function() {\n  const url = await ngrok.connect();\n})();\n```\n\nThis module uses `node\u003e=10.19.0` with async/await. For a callback-based version use [2.3.0](https://github.com/bubenshchykov/ngrok/blob/330674233e3ec77688bb692bf1eb007810c4e30d/README.md).\n\n### Global install\n\n```bash\nnpm install ngrok -g\nngrok http 8080\n```\n\nFor global install on Linux, you might need to run `sudo npm install --unsafe-perm -g ngrok` due to the [nature](https://github.com/bubenshchykov/ngrok/issues/115#issuecomment-380927124) of npm postinstall script.\n\n### Auth Token\nYou can create basic http-https-tcp tunnel without an [authtoken](https://ngrok.com/docs#authtoken). For custom subdomains and more you should obtain an authtoken by [signing up at ngrok.com](https://ngrok.com). Once you set the authtoken, it is stored in ngrok config and used for all tunnels. You can set the authtoken directly:\n\n```javascript\nawait ngrok.authtoken(token);\n```\n\nOr pass the authtoken to the `connect` method like so:\n\n```javascript\nawait ngrok.connect({authtoken: token, ...});\n```\n\n### Connect\n\nThere are a number of ways to create a tunnel with ngrok using the `connect` method.\n\nBy default, `connect` will open an HTTP tunnel to port 80\n\n```javascript\nconst url = await ngrok.connect(); // https://757c1652.ngrok.io -\u003e http://localhost:80\n```\n\nYou can pass the port number to `connect` to specify that port:\n\n```javascript\nconst url = await ngrok.connect(9090); // https://757c1652.ngrok.io -\u003e http://localhost:9090\n```\n\nOr you can pass an object of options, for example:\n\n```javascript\nconst url = await ngrok.connect({proto: 'tcp', addr: 22}); // tcp://0.tcp.ngrok.io:48590\nconst url = await ngrok.connect(opts);\n```\n\n#### Options\n\nThere are many options that you can pass to `connect`, here are some examples:\n\n```javascript\nconst url = await ngrok.connect({\n  proto: 'http', // http|tcp|tls, defaults to http\n  addr: 8080, // port or network address, defaults to 80\n  basic_auth: 'user:pwd', // http basic authentication for tunnel\n  subdomain: 'alex', // reserved tunnel name https://alex.ngrok.io\n  authtoken: '12345', // your authtoken from ngrok.com\n  region: 'us', // one of ngrok regions (us, eu, au, ap, sa, jp, in), defaults to us\n  configPath: '~/git/project/ngrok.yml', // custom path for ngrok config file\n  binPath: path =\u003e path.replace('app.asar', 'app.asar.unpacked'), // custom binary path, eg for prod in electron\n  onStatusChange: status =\u003e {}, // 'closed' - connection is lost, 'connected' - reconnected\n  onLogEvent: data =\u003e {}, // returns stdout messages from ngrok process\n});\n```\n\nSee [the ngrok documentation for all of the tunnel definition options](https://ngrok.com/docs/ngrok-agent/config#config-ngrok-tunnel-definitions) including: `name, inspect, host_header, scheme, hostname, crt, key, remote_addr`.\n\nNote on regions:\n\n* The region used in the first tunnel will be used for all the following tunnels\n* If you do not provide a region, ngrok will try to pick the closest one to your location. This will include the region in the URL. To get a URL without a region, set the region to \"us\".\n\n### Disconnect\n\nThe ngrok process and all tunnels will be killed when node process is complete. To stop the tunnels manually use:\n\n```javascript\nawait ngrok.disconnect(url); // stops one\nawait ngrok.disconnect(); // stops all\nawait ngrok.kill(); // kills ngrok process\n```\n\n### Config\n\nYou can use ngrok's [configurations files](https://ngrok.com/docs#config), and pass `name` option when making a tunnel. Configuration files allow to store tunnel options. Ngrok looks for them here:\n\n| System         | Path                                              |\n| -------------- | ------------------------------------------------- |\n| MacOS (Darwin) | `\"~/Library/Application Support/ngrok/ngrok.yml\"` |\n| Linux          | `\"~/.config/ngrok/ngrok.yml\"`                     |\n| Windows        | `\"%HOMEPATH%\\AppData\\Local\\ngrok\\ngrok.yml\"`      |\n\nYou can specify a custom `configPath` when making a tunnel.\n\n#### Updating config for ngrok version 3\n\nWith the upgrade to ngrok version 3, an older config file will no longer be compatible without a few changes. The ngrok agent provides a [command to upgrade your config](https://ngrok.com/docs/ngrok-agent/ngrok#command-ngrok-config-upgrade). On the command line you can run:\n\n```\nngrok config upgrade\n```\n\nThe default locations of the config file have changed too, you can upgrade and move your config file with the command:\n\n```\nngrok config upgrade --relocate\n```\n\nThe library makes this command available as well. To get the same effect you can run:\n\n```js\nawait ngrok.upgradeConfig();\n\n// relocate the config file too:\nawait ngrok.upgradeConfig({ relocate: true });\n```\n\n### Inspector\n\nWhen a tunnel is established you can use the ngrok interface hosted at http://127.0.0.1:4040 to inspect the webhooks made via ngrok.\n\nThe same URL hosts the internal [client api](https://ngrok.com/docs#client-api). This package exposes an API client that wraps the API which you can use to manage tunnels yourself.\n\n```javascript\nconst url = await ngrok.connect();\nconst api = ngrok.getApi();\nconst tunnels = await api.listTunnels();\n```\n\nYou can also get the URL of the internal API:\n\n```javascript\nconst url = await ngrok.connect();\nconst apiUrl = ngrok.getUrl();\n```\n\n### API\n\nThe API wrapper gives access to all the [ngrok client API](https://ngrok.com/docs#client-api) methods:\n\n```javascript\nconst url = await ngrok.connect();\nconst api = ngrok.getApi();\n```\n\n#### [List tunnels](https://ngrok.com/docs#list-tunnels)\n\n```javascript\nconst tunnels = await api.listTunnels();\n```\n\n#### [Start tunnel](https://ngrok.com/docs#start-tunnel)\n\n```javascript\nconst tunnel = await api.startTunnel(opts);\n```\n\n#### [Get tunnel details](https://ngrok.com/docs#tunnel-detail)\n\n```javascript\nconst tunnel = await api.tunnelDetail(tunnelName);\n```\n\n#### [Stop tunnel](https://ngrok.com/docs#stop-tunnel)\n\n```javascript\nawait api.stopTunnel(tunnelName);\n```\n\n#### [List requests](https://ngrok.com/docs#list-requests)\n\n```javascript\nawait api.listRequests(options);\n```\n\n#### [Replay request](https://ngrok.com/docs#replay-request)\n\n```javascript\nawait api.replayRequest(requestId, tunnelName);\n```\n\n#### [Delete all requests](https://ngrok.com/docs#delete-requests)\n\n```javascript\nawait api.deleteAllRequests();\n```\n\n#### [Request detail](https://ngrok.com/docs#request-detail)\n\n```javascript\nconst request = await api.requestDetail(requestId);\n```\n\n### Proxy\n\n- If you are behind a corporate proxy and have issues installing ngrok, you can set `HTTPS_PROXY` env var to fix it. ngrok's postinstall scripts uses the [`got`](https://www.npmjs.com/package/got) module to fetch the binary and the [`hpagent`](https://github.com/delvedor/hpagent) module to support HTTPS proxies. You will need to install the `hpagent` module as a dependency\n- If you are using a CA file, set the path in the environment variable `NGROK_ROOT_CA_PATH`. The path is needed for downloading the ngrok binary in the postinstall script\n\n## How it works\n\n`npm install` downloads the ngrok binary for your platform from the official ngrok hosting. To host binaries yourself set the `NGROK_CDN_URL` environment variable before installing ngrok. To force specific platform set `NGROK_ARCH`, eg `NGROK_ARCH=freebsdia32`.\n\nThe first time you create a tunnel the ngrok process is spawned and runs until you disconnect or when the parent process is killed. All further tunnels are connected or disconnected through the internal ngrok API which usually runs on http://127.0.0.1:4040.\n\n## ngrok binary update\n\nIf you would like to force an update of the ngrok binary directly from your software, you can require the `ngrok/download` module and call the `downloadNgrok` function directly:\n\n```javascript\nconst downloadNgrok = require('ngrok/download');\ndownloadNgrok(myCallbackFunc, { ignoreCache: true });\n```\n\n## Using with nodemon\n\nIf you want your application to restart as you make changes to it, you may use [nodemon](https://nodemon.io/). This blog post shows [how to use nodemon and ngrok together so your server restarts but your tunnel doesn't](https://philna.sh/blog/2021/03/15/restart-app-not-tunnel-ngrok-nodemon/).\n\n## Contributors\n\nPlease run `git update-index --assume-unchanged bin/ngrok` to not override [ngrok stub](https://github.com/bubenshchykov/ngrok/blob/master/bin/ngrok) in your PR. Unfortunately it can't be gitignored.\n\nThe test suite covers the basic usage without an authtoken, as well as features available for free and paid authtokens. You can supply your own tokens as environment variables, otherwise a warning is given and some specs are ignored (locally and in PR builds). GitHub Actions supplies real tokens to master branch and runs all specs always.\n\n## Upgrading to version 5\n\nPlease read the [upgrade notes for the ngrok agent](https://ngrok.com/docs/guides/upgrade-v2-v3). Library specific changes are described below and there is more in the [CHANGELOG](./CHANGELOG.md):\n\n### Config \n\nThe format and default location of the config file has changed. Please see the section on [upgrading your config file](#updating-config-for-ngrok-version-3) for more detail.\n\n### Connect options\n\nThe `bind_tls` option is now `scheme`. When `bind_tls` was true (the default), ngrok agent version 2 would start two tunnels, one on `http` and one on `https`. Now, when `scheme` is set to `https` (the default), only an `https` tunnel will be created. To create both tunnels, you will need to pass `[\"http\", \"https\"]` as the `scheme` option.\n\nThe `auth` option, also available as `httpauth`, is now just `basic_auth`. Note also that the password for `basic_auth` must be between 8 and 128 characters long.\n\n### Using the ngrok static free-domain\n\nIn April 2023, ngrok [introduced the ngrok static free-domain](https://ngrok.com/blog-post/new-ngrok-domains), which brings you a static subdomain even for free accounts. To make use of it, just use the `domain` option when creating a tunnel. Example:\n\n```ts\nngrok.connect({\n  domain: \"xxx.ngrok-free.app\"\n  authtoken: \"YOUR-AUTH-TOKEN\"\n})\n```\n\n__Note__: Please make sure to __either__ use the `subdomain` or the `domain` option. Using both would lead to using the subdomain only.  \n\n## Upgrading to version 4\n\nThe main impetus to update the package was to remove the dependency on the deprecated `request` module. `request` was replaced with `got`. Calls to the main `ngrok` functions, `connect`, `authtoken`, `disconnect`, `kill`, `getVersion` and `getUrl` respond the same as in version 3.\n\nUpdating the HTTP library, meant that the wrapped API would change, so a client class was created with methods for the available API calls. See the documentation above [for how to use the API client](#api).\n\nThe upside is that you no longer have to know the path to the API method you need. For example, to list the active tunnels in version 3 you would do:\n\n```javascript\nconst api = ngrok.getApi();\nconst tunnels = await api.get('api/tunnels');\n```\n\nNow you can call the `listTunnels` function:\n\n```javascript\nconst api = ngrok.getApi();\nconst tunnels = await api.listTunnels();\n```\n\n### TypeScript\n\nFrom version 3 to version 4 the bundled types were also overhauled. Most types live within the `Ngrok` namespace, particularly `Ngrok.Options` which replaces `INgrokOptions`.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbubenshchykov%2Fngrok","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbubenshchykov%2Fngrok","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbubenshchykov%2Fngrok/lists"}