The ngrok Agent SDK for Python
Project description
The ngrok Agent SDK for Python
Note: This is beta-quality software. Interfaces may change without warning.
ngrok is a globally distributed reverse proxy commonly used for quickly getting a public URL to a service running inside a private network, such as on your local laptop. The ngrok agent is usually deployed inside a private network and is used to communicate with the ngrok cloud service.
This is the ngrok agent in library form, suitable for integrating directly into Python applications. This allows you to quickly build ngrok into your application with no separate process to manage.
If you're looking for the previous agent downloader project, it's over here.
Installation
The published library is available on PyPI.
python -m pip install ngrok
ngrok-py officially supports Python 3.7+.
Documentation
A quickstart guide and a full API reference are included in the ngrok-py Python API documentation.
Quickstart
After you've installed the package, you'll need an Auth Token. Retrieve one on the Auth Token page of your ngrok dashboard
There are multiple examples in the /examples directory. A minimal use-case looks like the following:
async def create_tunnel():
session = await ngrok.NgrokSessionBuilder().authtoken_from_env().connect()
tunnel = await session.http_endpoint().listen()
print (f"Ingress established at {tunnel.url()}")
tunnel.forward_tcp("localhost:9000")
ASGI Runner - Tunnels to Uvicorn, Gunicorn, Django and More, With No Code
Prefix the command line which starts up a Uvicorn or Gunicorn web server with either ngrok-asgi
or python -m ngrok
. Any TCP or Unix Domain Socket arguments will be used to establish connectivity automatically. There are many command line arguments to configure the Tunnel used, for instance adding --basic-auth ngrok online1line
will introduce basic authentication to the ingress tunnel.
Uvicorn
Examples:
ngrok-asgi uvicorn mysite.asgi:application
ngrok-asgi uvicorn mysite.asgi:application --host localhost --port 1234
ngrok-asgi uvicorn mysite.asgi:application --host localhost --port 1234 --basic-auth ngrok online1line
ngrok-asgi uvicorn mysite.asgi:application --uds /tmp/uvicorn.sock
# Can use the module name as well, such as:
python -m ngrok uvicorn mysite.asgi:application --oauth-provider google --allow-emails bob@example.com
Gunicorn
Examples:
ngrok-asgi gunicorn mysite.asgi:application -k uvicorn.workers.UvicornWorker
ngrok-asgi gunicorn mysite.asgi:application -k uvicorn.workers.UvicornWorker --webhook-verification twilio s3cr3t
ngrok-asgi gunicorn mysite.asgi:application -k uvicorn.workers.UvicornWorker --bind localhost:1234
ngrok-asgi gunicorn mysite.asgi:application -k uvicorn.workers.UvicornWorker --bind unix:/tmp/gunicorn.sock
# Can use the module name as well, such as:
python -m ngrok gunicorn mysite.asgi:application -k uvicorn.workers.UvicornWorker --response-header X-Awesome True
Examples
Frameworks
- Aiohttp - Example
- Django - Single File Example, Modify manage.py Example, Modify asgi.py Example, or use the
ngrok-asgi
ASGI Runner discussed above - Flask - Example
- Gunicorn - Use the
ngrok-asgi
ASGI Runner discussed above - Uvicorn - Example, or use the
ngrok-asgi
ASGI Runner discussed above
Tunnel Types
- HTTP - Minimal Example, Full Configuration Example
- Labeled - Example
- TCP - Example
- TLS - Example
Platform Support
Pre-built binaries are provided on PyPI for the following platforms:
OS | i686 | x64 | aarch64 | arm |
---|---|---|---|---|
Windows | ✓ | ✓ | * | |
MacOS | ✓ | ✓ | ||
Linux | ✓ | ✓ | ✓ | |
Linux musl | ✓ | ✓ | ||
FreeBSD | * |
ngrok-py, and ngrok-rs which it depends on, are open source, so it may be possible to build them for other platforms.
- Windows-aarch64 will be supported after the next release of Ring.
- FreeBSD-x64 is built by the release process, but PyPI won't accept BSD flavors.
Dependencies
This project relies on PyO3, an excellent system to ease development and building of Rust plugins for Python.
Thank you to OpenIoTHub for handing over the ngrok name on PyPI.
License
This project is licensed under either of
- Apache License, Version 2.0, (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
- MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)
at your option.
Contribution
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in tokio-core by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distributions
Built Distributions
Hashes for ngrok-0.5.0-cp37-abi3-win_amd64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | b3fa69e0a83bae50f2f87857e3177b52f94b45981ffc9170c36cb2978ed8e580 |
|
MD5 | 26f9251e96f1ab21f0f9156022342cd3 |
|
BLAKE2b-256 | dce238394e35034af92f5ef43473fdbb38b0e47cff881af00dadbea30bc8a86b |
Hashes for ngrok-0.5.0-cp37-abi3-musllinux_1_2_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | d019b8e5d90e1492a486f00cb9d1fcb31cd3dbd262e9c070b81ff4f69034ef9a |
|
MD5 | 7fff114b3d886bd7aeca04f7f3f92c26 |
|
BLAKE2b-256 | cbe1ac6755116a51ef7113accd29b8e4162778c9b2959e28a1d06fa439d2c813 |
Hashes for ngrok-0.5.0-cp37-abi3-musllinux_1_2_aarch64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | f4b635701d5e555b923a0d1ffd7efb29f9652b7b8b9b70109f4e371c90af0a05 |
|
MD5 | 256be682ebba95d9fab4860e7841066f |
|
BLAKE2b-256 | 5930cdf0c222b1f0c41b842acbf54f47b93284f6ec39cf967635fd1d719d848f |
Hashes for ngrok-0.5.0-cp37-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | af989408103d3c622f42abbd044afb0fa1eb414c62906f8d34e8bca35b503259 |
|
MD5 | 6c4508ecd697b7c63b15b00044860baa |
|
BLAKE2b-256 | 902d4631f09ab19b35d54c3f0eefdbc9ee6407ee3369e34ea97b93e4eb5f5cbb |
Hashes for ngrok-0.5.0-cp37-abi3-manylinux_2_17_armv7l.manylinux2014_armv7l.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 2fd36ed39e4ad953f3915be28b95708dbb32cb8d8778110ceed94f5341a94435 |
|
MD5 | 5e6cef7c93064207d799f6954f8b8849 |
|
BLAKE2b-256 | 6d6d7cab5af87632142483e4512eb80fedc8cefa1248c95dcfb84c273247e689 |
Hashes for ngrok-0.5.0-cp37-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 550da53e06d3347c4fddbdb417ae37f743979cf4c7d032f21c1c9c51cb43b5e6 |
|
MD5 | c9e01cd976fdfeae69e28aec9f358e3a |
|
BLAKE2b-256 | dc35d0eff8c58b2d44e7c1924cc1dcc94f2c0262e33938232a5812c20ba25476 |
Hashes for ngrok-0.5.0-cp37-abi3-macosx_11_0_arm64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | cc7b49a10923c161a33cd3d6510ba03eae72d59ec3b7b5d86c1223b497ef83ba |
|
MD5 | 661fcd933e6a292283358520c8f2fd0b |
|
BLAKE2b-256 | 910138d083ecabb0e8e4de070933030df5383778b0d0f4c1736278f33862a3af |
Hashes for ngrok-0.5.0-cp37-abi3-macosx_10_9_x86_64.macosx_11_0_arm64.macosx_10_9_universal2.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 1185935577f964abd6478ed79bf87bc356303c97c610976ebd795902815e760d |
|
MD5 | 9df9f5debbb130003168731e13d1eb7e |
|
BLAKE2b-256 | 6c5feba59e5a91a803864012e85d1157f6349b659a2ea5c1408db03c8357f050 |
Hashes for ngrok-0.5.0-cp37-abi3-macosx_10_7_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 2337c7a8b2de8e6b109af347af8887c6b78c97b974a1083da635ce7b7f704b9e |
|
MD5 | 70c95356e1330174bc6eb8a43e567a42 |
|
BLAKE2b-256 | 6958e552fa85603e896c4983fb89ae3c0f8c38ec622303bddc5ea55380a5ba01 |