{"id":17771929,"url":"https://github.com/probablycorey/tcp-local-tunnel","last_synced_at":"2025-04-01T15:19:07.392Z","repository":{"id":66312386,"uuid":"600230369","full_name":"probablycorey/tcp-local-tunnel","owner":"probablycorey","description":null,"archived":false,"fork":false,"pushed_at":"2023-02-10T22:38:36.000Z","size":4728,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-02-07T09:33:44.463Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/probablycorey.png","metadata":{"files":{"readme":"README.md","changelog":null,"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":"2023-02-10T22:02:16.000Z","updated_at":"2023-02-10T22:02:33.000Z","dependencies_parsed_at":null,"dependency_job_id":"b33f46a4-8e28-4a3f-8f9b-6eec053d4fd5","html_url":"https://github.com/probablycorey/tcp-local-tunnel","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/probablycorey%2Ftcp-local-tunnel","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/probablycorey%2Ftcp-local-tunnel/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/probablycorey%2Ftcp-local-tunnel/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/probablycorey%2Ftcp-local-tunnel/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/probablycorey","download_url":"https://codeload.github.com/probablycorey/tcp-local-tunnel/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246660077,"owners_count":20813338,"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":[],"created_at":"2024-10-26T21:37:25.342Z","updated_at":"2025-04-01T15:19:07.374Z","avatar_url":"https://github.com/probablycorey.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003ch3 align=\"center\"\u003e\n  \u003ccode\u003etcp-local-tunnel\u003c/code\u003e\n\u003c/h3\u003e\n\n\u003cp align=\"center\"\u003e\n  Expose localhost to the Internet using TCP sockets!\n\u003c/p\u003e\n\n---\n\n\u003cimg alt=\"tcp-local-tunnel version\" src=\"https://img.shields.io/npm/v/tcp-local-tunnel\"\u003e \u003cimg alt=\"tcp-local-tunnel license\" src=\"https://img.shields.io/npm/l/tcp-local-tunnel\"\u003e \u003cimg alt=\"tcp-local-tunnel PRs welcome\" src=\"https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square\"\u003e\n\n## About\n\nSimple module that allows to expose server from local network to the Internet.\nIt works similarly to [localtunnel](https://github.com/localtunnel/localtunnel), but is more stable and simpler.\n\nI'm not providing a service where you can access your exposed local server, you will need to have some VPS or another machine connected to the internet with at least two open ports.\n\nModule creates connection from your local server to your remote server via TCP and transmits data in both ways with established tunnel.\n\nThis is extremely useful when you need to access an IoT device (Raspberry PI i.e) running in your home network. For example you can turn off light (that you forgot to turn off, or just to make sure) in home from your workplace or any other place on Earth.\n\nI'm also working on NodeMCU implementation of client side module (ESP8266 devices)\n\nModule supports any protocol that uses TCP, eg. HTTP, Websocket.\n\nThe stability mostly depends on your local internet connection quality.\n\n## Security caveats\n\nIf somebody knows host and port of your remote server which local machine connects to, then he also can creates tunnel and redirect remote requests to his machine instead of yours. \n\nTunnel connection is not encrypted, so potential attacker can read data you are sending.\n\nSee [alternatives](#alternatives) for more secure solutions.\n\n## Basic-usage\n\n`npm install tcp-local-tunnel`\n\nLet's say your local server is listening on `3000`\n\n### Code to run on local machine\n\n```javascript\nconst { client } = require('tcp-local-tunnel');\nclient(\n  {\n    host: '255.255.255.255', // remote server ip or domain\n    port: 8010 // tunnel port\n  },\n  {\n    host: 'localhost',\n    port: 3000\n  }\n);\n```\n\n### Code to run on remote machine\n\n```javascript\nconst { proxyServer } = require('tcp-local-tunnel');\n\nproxyServer({\n  proxyPort: 80, // remote port to access exposed local machine\n  tunnelPort: 8010 // tunnel port\n});\n```\n\n## Run server and expose it immediately (code in `./example`)\n\n### Code to run on local machine\n\n```javascript\nconst fs = require('fs');\nconst express = require('express');\nconst bodyParser = require('body-parser');\n\nconst { client } = require('../index.js');\n\n/* simple express server showcase */\n\nconst serverPort = 3000;\n\nconst server = express();\n\nserver.use(bodyParser.json());\nserver.use(bodyParser.urlencoded());\n\nserver.get('/someurl', function(req, res, next) {\n  res.send('some url page');\n});\nserver.get('/video.mp4', (req, res) =\u003e {\n  res.header('Content-Type', 'video/mp4');\n  fs.createReadStream('neverGonna.mp4').pipe(res);\n});\nserver.get('/long.json', (req, res) =\u003e {\n  const file = fs.readFileSync('long.json');\n  res.header('Content-Length', Buffer.byteLength(file));\n  console.log('contetn length', Buffer.byteLength(file));\n  res.json(file);\n});\nserver.get('/', function(req, res, next) {\n  res.send('Main page');\n});\n\nserver.listen(serverPort);\n\n/* tcp tunnel config */\n\nclient(\n  {\n    host: '255.255.255.255',\n    port: 8010\n  },\n  {\n    host: 'localhost',\n    port: serverPort\n  },\n  40 // number of concurrent open tunnels\n);\n```\n\n### Code to run on remote machine\n\n```javascript\nconst { proxyServer } = require('../index.js');\n\n/* internet server proxy configuration */\n\nproxyServer({\n  proxyPort: 80,\n  tunnelPort: 8010\n});\n```\n\n## API\n\n### Client (local side)\n\n```javascript\nconst { client } = require('tcp-local-tunnel');\n\nclient(\n  {\n    host: '255.255.255', // remote server host or domain\n    port: 8010 // remote server tunnel port\n  },\n  {\n    host: 'localhost', // local server host or ip\n    port: 3000 // local server port\n  },\n  10 // number of concurent open tunnels, default is 10\n);\n```\n\n### ProxyServer (remote side)\n\n```javascript\nconst { proxyServer } = require('tcp-local-tunnel')\n\nproxyServer({\n  proxyPort: 80, // remote port to access exposed local machine\n    tunnelPort: 8010, // tunnel port\n    timeout : 5000 // time after request is rejected when there are no tunnel connections\n})\n```\n\n## Alternatives\n\nYou can use SSH remote port forwarding to achieve the same. It's encrypted and hence more secure.\n\nSee Remote Forwarding chapter [https://www.ssh.com/ssh/tunneling/example](https://www.ssh.com/ssh/tunneling/example)\n\n## Contributing\n\nProject is open to contributions, just rise an issue if you have some ideas about features or you noticed a bug. After discussion we can approach implementation :)\n\n## Made with 🧠 by [@jayu](https://github.com/jayu)\n\nI hope that this small piece of software will help you build fancy IoT systems. If this tool was useful, don't hesitate to give it a 🌟!\n\n## License\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fprobablycorey%2Ftcp-local-tunnel","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fprobablycorey%2Ftcp-local-tunnel","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fprobablycorey%2Ftcp-local-tunnel/lists"}