Skip to main content

ngrok Python SDK Quickstart

The ngrok Python SDK enables you to quickly and efficiently serve Python applications on the internet without the need to configure low-level network primitives like IPs, certificates, load balancers, or ports.

This quickstart uses ngrok's Python SDK to put a Python app running on your local device online and secure it by requiring visitors to log in with a Google account to access it.

What you'll need​

  1. An ngrok account.
  2. Your ngrok auth token, which you can find in the dashboard.
  3. Python installed on your machine. You can check this by running python -v in your terminal.
  4. A domain connected to your ngrok account. We'll refer to this as your-reserved-domain from here on out.

1. Start your app or service​

Start up the app or service you'd like to put online. This is the app that your agent endpoint will forward online traffic to.

If you don't have an app to work with, you can create a minimal a Python app using the following code to set up a basic HTTP server at port 8080.

Loading…

Navigate to the directory where this file is located and run the following command to start the server:

Loading…

2. Install the Python SDK​

Use the following terminal command to install the Python SDK.

note

If your terminal is already running an app or service, you'll need to open a new terminal window or tab to follow this step.

Loading…

3. Create a .env file​

Create a .env file and add your ngrok auth token to it. This file needs to be in the same directory where you'll put the script using ngrok's Python SDK. The following terminal commands will create this directory, navigate into it, and add the .env file there.

Loading…

Next, add your ngrok auth token to the file like this:

Loading…

Finally, you'll need to install the python-dotenv package to access your environment variable from your code.

Loading…
tip

If you don't want to use a .env file, you can instead export your auth token as an environment variable in your terminal session, or call ngrok.set_auth_token("your-token") in your code.

4. Start your endpoint​

Start your agent endpoint, which will forward public traffic to your app.

Create a new file named example.py in the same directory as your .env file and add the following code. This example:

  • Starts an Agent endpoint that forwards from your reserved domain to your service running on port 8080.
    • If your app is running on a different port, change the example code to reflect that.
  • Secures the endpoint with a Traffic Policy that requires authentication via Google OAuth.
    • Traffic policies allow you to control how traffic is handled by your endpoint, including authentication, headers, and more.
note

This example uses ngrok's default Google OAuth application. To use your own, see the OAuth Traffic Policy Action documentation.

Loading…

5. Test your endpoint​

Test your endpoint by running the following terminal command:

Loading…

Assuming everything is set up correctly, this should print your endpoint URL to the terminal. Your app is now live on the internet at this URL, and you can access it from any browser or tool that can make HTTP requests.

When you visit the URL, you should be prompted to log in with Google. After logging in, you will either see your app or service, or, if you used the example app in this quickstart, you'll see "Hello from Python HTTP Server!" displayed in your browser.

What's next?​