{"id":13594986,"url":"https://github.com/robbie-cahill/tunnelmole-client","last_synced_at":"2025-08-04T05:39:36.115Z","repository":{"id":91235474,"uuid":"598995344","full_name":"robbie-cahill/tunnelmole-client","owner":"robbie-cahill","description":"Tunnelmole - Connect to local servers from anywhere","archived":false,"fork":false,"pushed_at":"2025-06-24T09:40:43.000Z","size":2609,"stargazers_count":1566,"open_issues_count":15,"forks_count":100,"subscribers_count":9,"default_branch":"main","last_synced_at":"2025-07-25T05:58:51.314Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/robbie-cahill.png","metadata":{"files":{"readme":".github/README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.md","code_of_conduct":"CODE_OF_CONDUCT.md","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,"zenodo":null}},"created_at":"2023-02-08T08:27:57.000Z","updated_at":"2025-07-24T09:35:04.000Z","dependencies_parsed_at":"2023-06-04T12:15:39.259Z","dependency_job_id":"9b730283-91e7-45f5-83f2-a92016ba73b3","html_url":"https://github.com/robbie-cahill/tunnelmole-client","commit_stats":null,"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"purl":"pkg:github/robbie-cahill/tunnelmole-client","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/robbie-cahill%2Ftunnelmole-client","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/robbie-cahill%2Ftunnelmole-client/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/robbie-cahill%2Ftunnelmole-client/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/robbie-cahill%2Ftunnelmole-client/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/robbie-cahill","download_url":"https://codeload.github.com/robbie-cahill/tunnelmole-client/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/robbie-cahill%2Ftunnelmole-client/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":268655153,"owners_count":24285128,"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","status":"online","status_checked_at":"2025-08-04T02:00:09.867Z","response_time":79,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":[],"created_at":"2024-08-01T16:01:41.981Z","updated_at":"2025-08-04T05:39:36.104Z","avatar_url":"https://github.com/robbie-cahill.png","language":"TypeScript","funding_links":[],"categories":["TypeScript","HarmonyOS","others","Development","\u003ca name=\"networking\"\u003e\u003c/a\u003eNetworking"],"sub_categories":["Windows Manager","Public localhost"],"readme":"## Tunnelmole\n![Tunnelmole](https://raw.githubusercontent.com/robbie-cahill/tunnelmole-client/main/docs/img/tunnelmole.png)\n\nTunnelmole is a simple tool to give your locally running HTTP(s) servers a public URL. For example, you could get a public URL for\n- A web server\n- A Docker container\n- An API\n- A React or node application\n- A static website\n\nSo, you could have your application running locally on port `8080`, then by running `tmole 8080` you could have a URL such as `https://df34.tunnelmole.net` routing to your locally running application.\n\n### Quick Demo\n*Getting a Public URL for the Tunnelmole Website, which is running locally*\n![Tunnelmole Example](https://raw.githubusercontent.com/robbie-cahill/tunnelmole-client/main/docs/img/tunnelmole-demo.gif)\n\nTunnelmole has been compared to a similar tool known as `ngrok`, but is open source.\n\nIf you are using the default configuration you will get a HTTPs URL for free.\n\nHeres what you could do with your new public URL\n- Automate your life. With a public URL, IFTTT and other automation services can send you webhooks which your code can then react to\n- Test and debug webhooks locally without stubbing requests. Set a breakpoint, then trigger the webhook provider to hit your URL\n- Use your phone to test the mobile version of your site. A real device will always be better than using an emulator or devtools to do mobile testing\n- Test advanced HTTPs only features such as Web Notifications and PWA's locally\n- Cross device testing with real devices. Hop on another computer or device running the same or a different OS, then hit the public URL Tunnelmole generated for you\n- Share it with anyone over the internet such as a friend, colleague or client to show off your work\n\n### Installation\nThere are a couple of ways to install Tunnelmole.\n\nIf you have **NodeJS 16.10** or later, you can install Tunnelmole by running\n```\nsudo npm install -g tunnelmole\n```\n\nAlternatively you can install the latest precompiled binary for your platform. This has the right version of Node built in. You don't need any specific version of Node installed for this approach\n\n#### Linux, Mac and Windows Subsystem for Linux\nCopy and paste the following into a terminal:\n```\ncurl -O https://install.tunnelmole.com/xD345/install \u0026\u0026 sudo bash install\n```\nThe script will detect your OS and install the right version.\n\n#### Windows\n1. [Download tmole.exe](https://tunnelmole.com/downloads/tmole.exe)\n2. Put it somewhere in your [PATH](https://www.wikihow.com/Change-the-PATH-Environment-Variable-on-Windows).\n\nI'd like to have the install script for Linux and Mac also working in Cygwin and Mingw. Let me know if you're willing to help test!.\n\n#### Install with NPM\nTo install Tunnelmole with NPM you need to have NodeJS installed. If not, get it from (https://nodejs.org/).\n\n`npm install -g tunnelmole`\n\n#### Using Tunnelmole\n- Start your web application locally and note down the port number its listening on\n- Run `tmole \u003cport number\u003e`, replacing `\u003cport number\u003e` with your applications port number. For example, if your application listens on port `8080`, run `tmole 8080`.\n\nHere's what it should look like\n```\n$ tmole 8080\nhttp://evgtkh-ip-49-145-166-122.tunnelmole.net is forwarding to localhost:8080\nhttps://evgtkh-ip-49-145-166-122.tunnelmole.net is forwarding to localhost:8080\n```\n\nNow, just go to either one of the URLs shown with your web browser.\n\nYou can also use another device, for example try hitting one of the URLs with your phones browser or a different computer.\n\nThe URLs are public - this means you can also share them with collaborators and others over the internet.\n\n#### Custom subdomain\nSometimes, it can be useful to have a domain that does not change frequently. To use a custom subdoman run\n`tmole 8080 as \u003cyourdomain\u003e.tunnelmole.net`.\n\nIf you are using the hosted service (which is the default) and you want to use a custom subdomain you'll need to purchase a subscription [Learn More](https://dashboard.tunnelmole.com?utm_source=tunnelmoleClientGithub).\n\nOtherwise, you can self host. To learn more go to the [Tunnelmole Service](https://github.com/robbie-cahill/tunnelmole-service/) GitHub repo.\n\n### Integrating with NodeJS and TypeScript projects with NPM\nTunnelmole is available as an NPM dependency for integration with NodeJS and TypeScript projects.\n\n#### Install as an npm dependency\nTo integrate tunnelmole with your project you first need to install it as an NPM dependency.\n```\nnpm install --save tunnelmole\n```\n\n#### Starting tunnelmole using code\nFirst import `tunnelmole`. Both ES and CommonJS modules are supported.\n\nImporting `tunnelmole` as an ES module\n```javascript\nimport { tunnelmole } from 'tunnelmole';\n```\n\nImporting `tunnelmole` as a CommonJS module\n```javascript\nconst tunnelmole = require('tunnelmole/cjs');\n```\n\nOnce the module is imported you can start tunnelmole with the code below, changing port 3000 to the port your application listens on if it is different.\n```javascript\nconst url = tunnelmole({\n    port: 3000\n});\n// url = https://idsq6j-ip-157-211-195-169.tunnelmole.net\n```\n\nTunnelmole will start in the background and you'll see output in the console log similar to the Tunnelmole command line application which will include the public URLs that now point to your application. The function is `async` and won't block execution of the rest of your code.\n\nIf you want to use a custom subdomain, you could also pass the domain as an option.\n```javascript\nconst url = tunnelmole({\n    port: 3000,\n    domain: '\u003cyour tunnelmole domain e.g. mysite.tunnelmole.net\u003e'\n});\n// url = mydomain.tunnelmole.net\n```\nAgain if you are using the hosted service (which is the default) and you want to use a custom subdomain you'll need to purchase a subscription [Learn More](https://dashboard.tunnelmole.com?utm_source=tunnelmoleClientGithub).\n\nOtherwise, you can self host. To learn more about this option go to the [Tunnelmole Service](https://github.com/robbie-cahill/tunnelmole-service/) GitHub repo.\n#### Suppress output/logs\nTo suppress the initial output with the URLs, set the environment variable `TUNNELMOLE_QUIET_MODE=1` somewhere in your environment. This might be useful in a CI/CD environment or in other scripts.\n\n#### Using Tunnelmole with NPM scripts\nInstalling Tunnelmole as an NPM dependency will make the following executables available in your project:\n```\nnode_modules/.bin/tmole\nnode_modules/.bin/tunnelmole\n```\n\nThey both work identically to the Tunnelmole command line application.\n\nYou can run them manually in the same way as the command line application (for example `node node_modules/.bin/tmole 3000`), but its far more convenient to integrate them with NPM scripts in `package.json`. This way, you can automate starting your application and generating a public URL with a single command. For example:\n```json\n{\n    \"name\": \"myapp\",\n    \"version\": \"0.0.1\",\n    \"scripts\": {\n        \"start\": \"dist/index.js\",\n        \"start-public\": \"npm run start \u0026\u0026 tmole 3000\"\n    }\n}\n```\n\nIn this example, `npm run start-public` will simultaneously start your application and get tunnelmole to generate public URLs tunneling to port 3000. Replace port 3000 with the port your application listens on if it is different. You will see the public URLs in the command line output.\n\nThis allows you to start your application and get a public URL with a single command, instead of needing to run two commands in separate terminals.\n\n### Building from source\n#### Prerequisites\n- TypeScript 4.4 or later\n- Node 15 or later\n\n#### Install the dependencies with `npm`\nRun `npm install`\n\n#### Copy the example config\n`cp config-instance.example.ts config-instance.ts`\n\nThe default settings are fine unless you want to self host your own [tunnelmole service](https://github.com/robbie-cahill/tunnelmole-service/), in which case you'll need to modify the config to point to your server.\n\n#### Start Tunnelmole\nTo start Tunnelmole, run `npm start`. \n\nThis does a few things for you automatically:\n- First, the code will compile\n- Tunnelmole will then start\n- Every time you make changes, the code will recompile and Tunnelmole will automatically restart. This saves you time as you won't need to manually recompile and restart Tunnelmole yourself. This feature is also known as Hot Reload.\n\nAlternatively you can invoke Tunnelmole manually with\n`node dist/bin/tunnelmole.js \u003cport number to forward to\u003e` after compiling the code with `npm run build`.\n\n#### Debugging\nThis project has sourcemaps enabled, so you can set breakpoints in the TypeScript `.ts` files and they should behave normally.\n\nIf Tunnelmole crashes and you get a Stack Trace it will refer to the TypeScript files and line numbers which should make tracking down problematic code easier.\n\nTo set up debugging for Visual Studio Code, copy over the example config.\n```\ncp .vscode/launch.json.example .vscode/launch.json\n```\nOnce this is done, run \"Launch Tunnelmole\" from the Run and Debug menu.\n\nWhile debugging, hot reload is not supported as you'd loose your debug connection each time Tunnelmole restarts. So for every change, you will need to recompile the code (i.e. with `npm run build`) and then restart the debugger.\n\nYou can optionally run `npm run watch` to automatically recompile code as you make changes.\n\nBy default, Launch Tunnelmole invokes Tunnelmole to forward to port 8001 locally. You can change this by changing the port in the `.vscode/launch.json` config under the \"args\" section.\n\n### How it works\n![How Tunnelmole Works](https://raw.githubusercontent.com/robbie-cahill/tunnelmole-client/main/docs/img/how-tunnelmole-works.png)\n\nTunnelmole sets up a persistent Websocket connection between your device and a host machine running the [tunnelmole service](https://github.com/robbie-cahill/tunnelmole-service/). By default, this is the hosted tunnlemole service at [https://tunnelmole.com](https://tunnelmole.com?utm_source=tmoleClientGithubRepo) but you can self host.\n\nAs requests come in to the public URL, these requests are sent back through the Websocket connection to the client running on your machine.\n\nThe client then forwards on the request to your locally running web server.\n\nResponses are handled in reverse. Your client forwards them to the Tunnelmole service, which then serves them up at the public URL.\n\n### Telemetry\nTo help improve the developer experience of Tunnelmole, some anonymized Telemetry data is collected by default.\n\nFor example\n- Your NodeJS version and OS\n- Crash reports which may include stack traces to assist in detecting and debugging unforseen issues that were not detected during testing (especially the \"it worked on my machine\" type).\n\nTo disable the telemetery, add the variable `TUNNELMOLE_TELEMETRY=0` to your environment.\n\nOn Linux and Mac, to opt out for a single run of Tunnelmole you could put this in front of the `tmole` command, for example\n```\nTUNNELMOLE_TELEMETRY=0 tmole 80\n```\n\nTo opt out by default:\n- On Linux or Mac add `export TUNNELMOLE_TELEMETRY=0` to your shells startup script, usually `.bashrc` or `.zshrc` but it will be different if you are not using bash or zsh as your shell. Then log out and back in to apply the changes. \n- On Windows add `TUNNELMOLE_TELEMETRY=0` to your environment variables using the System utility https://www.computerhope.com/issues/ch000549.htm. Then restart your computer to apply the changes.\n\n\n\n### Contributing\nThere is no big company behind Tunnelmole and currently there is only one maintainer so any help is greatly appreciated!.\n\nIf you'd like a bug fixed or missing feature added, the fastest way to make that happen is to implement the changes yourself.\n\nThis repo has a few features to help with your developer experience including sample debugging configuration and hot reload.\n\nHere are some different ways you can help\n- Help with testing Tunnelmole. Install the latest binary or build the latest source release and do your best to break it. If you're able to, create an issue.\n- Spreading the word. As previously mentioned, there is no big company or marketing department. That leaves it up to you to help others by introducing them to Tunnelmole. Sharing Tunnelmole on social media sites and creating blog articles will help you look good and help other developers.\n- Fixing bugs\n- Making feature requests. To do this, create a GitHub issue and describe the feature you think Tunnelmole should have\n- Implementing features\n\nFor any code changes, you will need to fork this repo and submit a PR. If you've never done this before, GitHub has a very good guide [here](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request-from-a-fork).\n\n### FAQs\n\n#### Is Tunnelmole fully open source?\nBoth the Tunnelmole client and server are fully open source. \n\nYou are free to self host or use our hosted service.\n\nWe welcome issue reports and PRs from the community.\n\nFeel free to look over the code and see exactly what Tunnelmole is doing before running it.\n\nThe Tunnelmole client is licensed under the MIT license. The service is licensed under the Gnu Affero General Public License, version 3.\n\n#### Does Tunnemole hide my IP?\nIn the past the Tunnelmole service did hide IP addresses. Unfortunately this encouraged bad actors to use the service. They would tunnel phishing sites through the service, then the abuse reports would get sent to my hosting provider instead of theirs.\n\nBecause of this, Tunnelmole now adds an `X-Forwarded-For` header with your IP in every response. So you can't use the Tunnelmole hosted service to hide your origin server. For the randomly generated URLs your IP is also added to the URL itself.\n\nHowever, you can always self host Tunnelmole and remove the code that adds this header if you want. This would allow you to hide your origin server. You'll then be responsible for securing your service. The IP of the server you self host on will still be visible.\n\n\n#### How can I help\nRead the above \"Contributing\" section to learn how to contribute.\n\n### Links and resources\n- Project Website with guides and documentation: [https://tunnelmole.com](https://tunnelmole.com?utm_source=tmoleClientGithubRepo)\n- A good overview of Websocket: [https://developer.mozilla.org/en-US/docs/Web/API/WebSockets_API](https://developer.mozilla.org/en-US/docs/Web/API/WebSockets_API)\n\n#### Uninstallation\n- If you installed with `npm`, run `npm uninstall -g tunnelmole`\n- On Linux or Mac, run `whereis tmole`, then `whereis tunnelmole` and delete the both files shown\n- On Windows, delete the `tmole.exe` file you downloaded\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frobbie-cahill%2Ftunnelmole-client","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frobbie-cahill%2Ftunnelmole-client","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frobbie-cahill%2Ftunnelmole-client/lists"}