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.
Documentation
A quickstart guide and a full API reference are included in the ngrok-python API documentation.
Quickstart
- Install the
ngrok-python
package from PyPI usingpip
:
python -m pip install ngrok
-
After you've installed the package, you'll need an authtoken. Retrieve one on the authtoken page of your ngrok dashboard.
-
Add the following code block using the connect method to expose your python application at port
9000
onlocalhost
:
import ngrok
listener = ngrok.connect(9000, authtoken_from_env=True)
print (f"Ingress established at {listener.url()}")
You can find more examples in the /examples directory.
Authorization
To use most of ngrok's features, you'll need an authtoken. To obtain one, sign up for free at ngrok.com and retrieve it from the authtoken page in your ngrok dashboard. Once you have copied your authtoken, you can reference it in several ways.
You can set it in the NGROK_AUTHTOKEN
environment variable and pass authtoken_from_env=True
to the connect method:
ngrok.connect(authtoken_from_env=True, ...)
Or pass the authtoken directly to the connect method:
ngrok.connect(authtoken=token, ...)
Or set it for all connections with the set_auth_token method:
ngrok.set_auth_token(token)
Connection
The connect method is the easiest way to start an ngrok session and establish a listener to a specified address. If an asynchronous runtime is running, the connect method returns a promise that resolves to the public listener object.
With no arguments, the connect method will start an HTTP listener to localhost
port 80
:
listener = ngrok.connect()
You can pass the port number to forward on localhost
:
listener = ngrok.connect(4242)
Or you can specify the host and port via a string:
listener = ngrok.connect("localhost:4242")
More options can be passed to the connect
method to customize the connection:
listener = ngrok.connect(8080, basic_auth="ngrok:online1line"})
listener = ngrok.connect(8080, oauth_provider="google", oauth_allow_domains="example.com")
The second (optional) argument is the listener type, which defaults to http
. To create a TCP listener:
listener = ngrok.connect(25565, "tcp")
Since the options are kwargs, you can also use the **
operator to pass a dictionary for configuration:
options = {"authtoken_from_env":True, "response_header_add":"X-Awesome:yes"}
listener = ngrok.connect(8080, **options)
See Full Configuration for the list of possible configuration options.
Disconnection
To close a listener use the disconnect method with the url
of the listener to close. If there is an asynchronous runtime running the disconnect method returns a promise that resolves when the call is complete.
ngrok.disconnect(url)
Or omit the url
to close all listeners:
ngrok.disconnect()
The close method on a listener will shut it down, and also stop the ngrok session if it is no longer needed. This method returns a promise that resolves when the listener is closed.
await listener.close()
Listing Listeners
To list all current non-closed listeners use the get_listeners method. If there is an asynchronous runtime running the get_listeners method returns a promise that resolves to the list of listener objects.
listeners = ngrok.get_listeners()
Full Configuration
This example shows all the possible configuration items of ngrok.connect:
listener = ngrok.connect(
# session configuration
addr="localhost:8080",
allow_user_agent="^mozilla.*",
authtoken="<authtoken>",
authtoken_from_env=True,
session_metadata="Online in One Line",
# listener configuration
basic_auth=["ngrok:online1line"],
circuit_breaker=0.1,
compression=True,
deny_user_agent="^curl.*",
domain="<domain>",
ip_restriction_allow_cidrs="0.0.0.0/0",
ip_restriction_deny_cidrs="10.1.1.1/32",
metadata="example listener metadata from python",
mutual_tls_cas=load_file("ca.crt"),
oauth_provider="google",
oauth_allow_domains=["<domain>"],
oauth_allow_emails=["<email>"],
oauth_scopes=["<scope>"],
oauth_client_id="<id>",
oauth_client_secret="<id>",
oidc_issuer_url="<url>",
oidc_client_id="<id>",
oidc_client_secret="<secret>",
oidc_allow_domains=["<domain>"],
oidc_allow_emails=["<email>"],
oidc_scopes=["<scope>"],
proxy_proto="", # One of: "", "1", "2"
request_header_remove="X-Req-Nope",
response_header_remove="X-Res-Nope",
request_header_add="X-Req-Yup:true",
response_header_add="X-Res-Yup:true",
schemes=["HTTPS"],
verify_webhook_provider="twilio",
verify_webhook_secret="asdf",
websocket_tcp_converter=True,
)
ASGI Runner - Listeners 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 Listener used, for instance adding --basic-auth ngrok online1line
will introduce basic authentication to the ingress listener.
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
- AWS App Runner - See the ngrok SDK Serverless Example repository, making the necessary changes to use Python instead of NodeJS
- 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 - Streamlit - Example
- Tornado - Example
- Uvicorn - Example, or use the
ngrok-asgi
ASGI Runner discussed above
Machine Learning
- Gradio - ngrok-asgi Example, gradio CLI Example sharing machine learning apps
- OpenPlayground - Example of an LLM playground you can run on your laptop
- GPT4ALL - Example of running the GPT4All-L Snoozy 13B model with a Gradio frontend
- Stable Diffusion WebUI by AUTOMATIC1111 -
ngrok-python
is now built-in, see the--ngrok
and--ngrok-options
arguments. - Text Generation WebUI by oobabooga -
ngrok-python
is now built-in using the--extension ngrok
argument.
Listener Types
- HTTP - Minimal Example, Full Configuration Example
- Labeled - Example
- TCP - Example
- TLS - Example
TLS Backends
As of version 0.10.0
there is backend TLS connection support, validated by a filepath specified in the SSL_CERT_FILE
environment variable, or falling back to the host OS installed trusted certificate authorities. So it is now possible to do this to connect:
ngrok.connect("https://127.0.0.1:3000", authtoken_from_env=True)
If the service is using certs not trusted by the OS, such as self-signed certificates, add an environment variable like this before running: SSL_CERT_FILE=/path/to/ca.crt
.
Unix Sockets
You may also choose to use Unix Sockets instead of TCP. You can view an example of this here.
A socket address may be passed directly into the listener forward()
call as well by prefixing the address with unix:
, for example unix:/tmp/socket-123
.
Builders
For more control over Sessions and Listeners, the builder classes can be used.
A minimal example using the builder class looks like the following:
async def create_listener():
session = await ngrok.NgrokSessionBuilder().authtoken_from_env().connect()
listener = await session.http_endpoint().listen()
print (f"Ingress established at {listener.url()}")
listener.forward("localhost:9000")
See here for a Full Configuration 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-python, and ngrok-rust 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.
Changelog
Changes are tracked in CHANGELOG.md.
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 ngrok-python 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.12.0-cp37-abi3-win_amd64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 87e8316832e52e61bfbad9bc95da832ab936d47a96376abf8dbcd689aef2186f |
|
MD5 | dcef1a969ddf5ff6e8c7bb9c27854320 |
|
BLAKE2b-256 | 76a9037a780cf25fc52d502553bb1679eac761b3a0895b67852a2093b08b7cb3 |
Hashes for ngrok-0.12.0-cp37-abi3-win32.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 0abc756360fa21d97df440a3f33ba24bce6e5449007b631c87cab41c5838db70 |
|
MD5 | b7da08d88bfefe1d5939425663288b04 |
|
BLAKE2b-256 | 387430f3a633bfe80cef67ac742e2dd0f84f5693c05c6fa031c86150c91b0e81 |
Hashes for ngrok-0.12.0-cp37-abi3-musllinux_1_2_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 4fc466c914fd6724461f4f55ce091ff3b4d4a9fea6ae17f3d7d1b9c10424f3ff |
|
MD5 | 3a7fedf412894eec4b601fc6af882ef6 |
|
BLAKE2b-256 | 952682ef2647232b2c17f5c9cbd28982aa1bac769c5cf5f9cfd343543dd73b07 |
Hashes for ngrok-0.12.0-cp37-abi3-musllinux_1_2_aarch64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | c4a992fc3b28d0f1f80b84da60e367b817fd722b34860404d33526b0474242df |
|
MD5 | f23f2f90009afa55233aaebfa50e9f3a |
|
BLAKE2b-256 | 7f578b6f179fbe8f190e8fe2beff82498b5ff4fb0c17e8f231a0d31a68d89438 |
Hashes for ngrok-0.12.0-cp37-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 20a4d9cd6e800010d28cbb61496e0fc0c8a4b13bc4d639ac53cf68b66262733b |
|
MD5 | 58d071217503a834f4c75e3be2d36917 |
|
BLAKE2b-256 | 42bbda27690170571f21cfdf8a538d305e2d27cf6b3b917af39cc3360ac0938f |
Hashes for ngrok-0.12.0-cp37-abi3-manylinux_2_17_armv7l.manylinux2014_armv7l.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 20d3dc46e53cb663d09b6de26890ca0fcf9214b0a768a58e6c321e9b485ecf4e |
|
MD5 | c060a2b7ef328c1560c0cd3b87d7adc0 |
|
BLAKE2b-256 | 3524b071bd7d99781a7be18f39b5e4e6a44204a53ce8e84c27b859ca5bc4b173 |
Hashes for ngrok-0.12.0-cp37-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 651f5dcb665061b7ce36780c3763cf0ae66bece573aa24fc9a9e92b7bd700bc6 |
|
MD5 | 89b2b2b4c65fcb17c68afe36769ce343 |
|
BLAKE2b-256 | 00e5ea35e60160b986b751036845e06ef052873791fc37b1d8aca409c4631a92 |
Hashes for ngrok-0.12.0-cp37-abi3-macosx_11_0_arm64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 9f166462b653618d200efbc97f0844addb8f0a0519a95dadba367865ec1c7c74 |
|
MD5 | eaa261c3f4996ecf9ae75db5954a0b01 |
|
BLAKE2b-256 | 0023a99b206c99daab6687b1b65b44dce399142b117e58f2043300612889bde6 |
Hashes for ngrok-0.12.0-cp37-abi3-macosx_10_9_x86_64.macosx_11_0_arm64.macosx_10_9_universal2.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 8c8a021466f371ccf0e0bf36f01c8d3e69037f52a9b23226d9d5e50ef5439756 |
|
MD5 | 79d2338b34b8b60a8c28ddd3bc71aff3 |
|
BLAKE2b-256 | ea2335419a2b727870b9a61f1c297bfb95852ac0c45b80c38346c4a8859fac89 |
Hashes for ngrok-0.12.0-cp37-abi3-macosx_10_7_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | ed2a097e8285b5b24a53368dac4baa6548783af5f2e7075f62656fade2984ffd |
|
MD5 | 8345f0d558945f4f17c53b8e2590db09 |
|
BLAKE2b-256 | b2507c32bfc06350d20784ef36151bb1379bab5a2272406ff426abcfd3857451 |