{"id":13468174,"url":"https://github.com/alexdlaird/pyngrok","last_synced_at":"2025-05-14T11:08:52.633Z","repository":{"id":33784168,"uuid":"162045773","full_name":"alexdlaird/pyngrok","owner":"alexdlaird","description":"A Python wrapper for ngrok","archived":false,"fork":false,"pushed_at":"2025-05-10T14:32:08.000Z","size":6261,"stargazers_count":438,"open_issues_count":1,"forks_count":58,"subscribers_count":6,"default_branch":"main","last_synced_at":"2025-05-10T15:34:08.259Z","etag":null,"topics":["education","ingress","localhost","localtunnel","ngrok","python","reverse-proxy","tunnel","tunneling","webhook"],"latest_commit_sha":null,"homepage":"https://pyngrok.readthedocs.io","language":"Python","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/alexdlaird.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.rst","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null},"funding":{"github":"alexdlaird","patreon":"alexdlaird","custom":["https://www.paypal.me/alexdlaird"]}},"created_at":"2018-12-16T22:12:33.000Z","updated_at":"2025-05-09T22:02:37.000Z","dependencies_parsed_at":"2023-12-07T16:48:17.810Z","dependency_job_id":"c6d85b11-e4c6-4a7c-9f8f-6bdca71d11c1","html_url":"https://github.com/alexdlaird/pyngrok","commit_stats":{"total_commits":655,"total_committers":10,"mean_commits":65.5,"dds":0.2824427480916031,"last_synced_commit":"79ed5bbd7e9316cdd148c74aceb28efb0dec85de"},"previous_names":[],"tags_count":99,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alexdlaird%2Fpyngrok","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alexdlaird%2Fpyngrok/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alexdlaird%2Fpyngrok/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alexdlaird%2Fpyngrok/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/alexdlaird","download_url":"https://codeload.github.com/alexdlaird/pyngrok/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254129484,"owners_count":22019628,"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":["education","ingress","localhost","localtunnel","ngrok","python","reverse-proxy","tunnel","tunneling","webhook"],"created_at":"2024-07-31T15:01:06.567Z","updated_at":"2025-05-14T11:08:52.619Z","avatar_url":"https://github.com/alexdlaird.png","language":"Python","funding_links":["https://github.com/sponsors/alexdlaird","https://patreon.com/alexdlaird","https://www.paypal.me/alexdlaird"],"categories":["Python","Others","Development Tools"],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\u003cimg alt=\"pyngrok - a Python wrapper for ngrok\" src=\"https://pyngrok.readthedocs.io/en/latest/_images/logo.png\" /\u003e\u003c/p\u003e\n\n[![Version](https://img.shields.io/pypi/v/pyngrok)](https://pypi.org/project/pyngrok)\n[![Python Versions](https://img.shields.io/pypi/pyversions/pyngrok.svg)](https://pypi.org/project/pyngrok)\n[![Coverage](https://img.shields.io/codecov/c/github/alexdlaird/pyngrok)](https://codecov.io/gh/alexdlaird/pyngrok)\n[![Build](https://img.shields.io/github/actions/workflow/status/alexdlaird/pyngrok/build.yml)](https://github.com/alexdlaird/pyngrok/actions/workflows/build.yml)\n[![Code Quality](https://app.codacy.com/project/badge/Grade/b055cf6e3f1745098fab86a2923730b3)](https://app.codacy.com/gh/alexdlaird/pyngrok/dashboard?utm_source=gh\u0026utm_medium=referral\u0026utm_content=\u0026utm_campaign=Badge_grade)\n[![Docs](https://img.shields.io/readthedocs/pyngrok)](https://pyngrok.readthedocs.io/en/latest)\n[![GitHub License](https://img.shields.io/github/license/alexdlaird/pyngrok)](https://github.com/alexdlaird/pyngrok/blob/main/LICENSE)\n\n`pyngrok` is a Python wrapper for `ngrok` that manages its own binary, making `ngrok` available via a convenient Python\nAPI.\n\n[`ngrok`](https://ngrok.com) is a reverse proxy that opens secure tunnels from public URLs to localhost. It's perfect\nfor rapid\ndevelopment (test webhooks, demo local websites, enable SSH access), establishing ingress to external\nnetworks and devices, building production APIs (traffic policies, OAuth, load balancing), and more. And\nit's made even more powerful with native Python integration through the `pyngrok` client.\n\n## Installation\n\n`pyngrok` is available on [PyPI](https://pypi.org/project/pyngrok/) and can be installed\nusing `pip`:\n\n```sh\npip install pyngrok\n```\n\nor `conda`:\n\n```sh\nconda install -c conda-forge pyngrok\n```\n\nThat's it! `pyngrok` is now available as a package to our Python projects, and `ngrok` is now available from\nthe command line.\n\n## Basic Usage\n\n### Open a Tunnel\n\nTo open a tunnel, use the [`connect`](https://pyngrok.readthedocs.io/en/latest/api.html#pyngrok.ngrok.connect) method,\nwhich returns a `NgrokTunnel`, and this returned object has a reference to the public URL generated by `ngrok` in its\n`public_url` attribute.\n\n```python\nfrom pyngrok import ngrok\n\n# Open a HTTP tunnel on the default port 80\n# \u003cNgrokTunnel: \"https://\u003cpublic_sub\u003e.ngrok.io\" -\u003e \"http://localhost:80\"\u003e\nhttp_tunnel = ngrok.connect()\n\n# Open a SSH tunnel\n# \u003cNgrokTunnel: \"tcp://0.tcp.ngrok.io:12345\" -\u003e \"localhost:22\"\u003e\nssh_tunnel = ngrok.connect(\"22\", \"tcp\")\n\n# Open a named tunnel from the config file\nnamed_tunnel = ngrok.connect(name=\"my-config-file-tunnel\")\n\n# Open an Internal Endpoint that's load balanced\n# \u003cNgrokTunnel: \"https://some-endpoint.internal\" -\u003e \"http://localhost:9000\"\u003e\ninternal_endpoint = ngrok.connect(addr=\"9000\",\n                                  domain=\"some-endpoint.internal\",\n                                  pooling_enabled=True)\n```\n\nThe [`connect`](https://pyngrok.readthedocs.io/en/latest/api.html#pyngrok.ngrok.connect) method takes `kwargs` as well,\nwhich allows\nus to pass additional tunnel configurations that are supported by `ngrok` (or the `name` of a tunnel defined in\n`ngrok`'s config file), [as documented here](https://pyngrok.readthedocs.io/en/latest/#tunnel-configurations).\n\n### `ngrok`'s API\n\nThe [`api`](https://pyngrok.readthedocs.io/en/latest/api.html#pyngrok.ngrok.api) method allows us to use the local\n`ngrok` agent to make requests against [the `ngrok` API](https://ngrok.com/docs/agent/cli-api/), if we\nhave [set an API key](https://pyngrok.readthedocs.io/en/latest/#setting-the-authtoken-or-api-key).\nFor example, here we reserve a `ngrok` domain, then create a Cloud Endpoint with an associated traffic policy:\n\n```python\nfrom pyngrok import ngrok\n\ndomain = \"some-domain.ngrok.dev\"\nngrok.api(\"reserved-domains\", \"create\",\n          \"--domain\", domain)\nngrok.api(\"endpoints\", \"create\",\n          \"--bindings\", \"public\",\n          \"--url\", f\"https://{domain}\",\n          \"--traffic-policy-file\", \"policy.yml\")\n```\n\n### `ngrok`'s Edges\n\n\u003e `ngrok` has deprecated Edges and will sunset Labeled Tunnels on December 31st, 2025. See\n\u003e [this issue](https://github.com/alexdlaird/pyngrok/issues/145) for more details.\n\nTo use [`ngrok`'s Edges](https://ngrok.com/docs/universal-gateway/edges/) with `pyngrok`, first [configure an Edge on\n`ngrok`'s dashboard](https://dashboard.ngrok.com/edges) (with at least one Endpoint mapped to the Edge), and define a\nlabeled tunnel in [the `ngrok` config file](https://ngrok.com/docs/agent/config/v2/#define-two-labeled-tunnels)\nthat points to the Edge.\n\n```yaml\ntunnels:\n  some-edge-tunnel:\n    labels:\n      - edge=my_edge_id\n    addr: http://localhost:80\n```\n\nTo start a labeled tunnel in `pyngrok`, pass its `name`\nto [connect](https://pyngrok.readthedocs.io/en/develop/api.html#pyngrok.ngrok.connect).\n\n```python\nfrom pyngrok import ngrok\n\n# Open the Edge tunnel that is defined in the config file\nnamed_tunnel = ngrok.connect(name=\"some-edge-tunnel\")\n```\n\nOnce an Edge tunnel is started, it can be managed through [`ngrok`'s dashboard](https://dashboard.ngrok.com/edges).\n\n### Command Line Usage\n\nThis package puts the default `ngrok` binary on our path, so all features of `ngrok` are\navailable on the command line.\n\n```sh\nngrok http 80\n```\n\nFor details on how to fully leverage `ngrok` from the command line,\nsee [`ngrok`'s official documentation](https://ngrok.com/docs/agent/cli/).\n\n## Documentation\n\nFor more advanced usage, `pyngrok`'s official documentation is available\nat [https://pyngrok.readthedocs.io](https://pyngrok.readthedocs.io).\n\n### Integration Examples\n\n- [Flask](https://pyngrok.readthedocs.io/en/latest/integrations.html#flask)\n- [Django](https://pyngrok.readthedocs.io/en/latest/integrations.html#django)\n- [End-to-End Testing](https://pyngrok.readthedocs.io/en/latest/integrations.html#end-to-end-testing)\n- [Google Colab](https://pyngrok.readthedocs.io/en/latest/integrations.html#google-colaboratory)\n\n## Contributing\n\nIf you would like to get involved, be sure to review\nthe [Contribution Guide](https://github.com/alexdlaird/pyngrok/blob/main/CONTRIBUTING.rst).\n\nWant to contribute financially? If you've found `pyngrok` useful, [sponsorship](https://github.com/sponsors/alexdlaird)\nwould also be greatly appreciated!\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falexdlaird%2Fpyngrok","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Falexdlaird%2Fpyngrok","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falexdlaird%2Fpyngrok/lists"}