Skip to main content

Quickstart: ngrok-rust

This quickstart will use the ngrok-rust Agent SDK to put a Rust app on the internet and secure it so that only you can access it.

What is ngrok-rust?​

ngrok-rust is an open-source, idiomatic Rust crate for embedding secure ingress directly into your Rust applications. If you’ve used the ngrok agent before, you can think of ngrok-rust as the agent packaged as a Rust crate.

ngrok-rust enables you to serve Rust services on the internet in a single line of code without setting up low-level network primitives like IPs, certificates, load balancers, and ports. Applications using ngrok-rust listen on ngrok’s global ingress network and your app gets incoming streams with tokio’s AsyncRead and AsyncWrite traits — compatible with axum::Server::builder() and hyper::Server::builder(). This makes it incredibly easy to drop ngrok-rust into any application that uses the popular axum or hyper crates.

You may want to open the ngrok-rust package documentation on docs.rs as you work through this guide.

Step 1: Install ngrok-rust​

First, create a new Rust app and install the ngrok, axum and tokio crates. This guide assumes you already have Rust installed.

mkdir ngrok-rust-quickstart
cd ngrok-rust-quickstart
cargo init
cargo add ngrok -F axum
cargo add axum
cargo add tokio -F rt-multi-thread -F macros

Step 2: Create your app​

In the ngrok-rust-quickstart directory, create the following main.rs file:

use axum::{routing::get, Router};
use ngrok::prelude::*;
use std::error::Error;

#[tokio::main]
async fn main() -> Result<(), Box<dyn Error>> {
    // build our application with a route
    let app = Router::new().route("/", get(|| async { "Hello from ngrok-rust!" }));

    // listen on ngrok ingress (i.e. https://myapp.ngrok.dev)
    let listener = ngrok::Session::builder()
        .authtoken_from_env()
        .connect()
        .await?
        .http_endpoint()
        .listen()
        .await?;
    println!("App URL: {:?}", listener.url());
    axum::Server::builder(listener)
        .serve(app.into_make_service())
        .await?;
    Ok(())
}
In this code
  • Lines 11-17: connect to ngrok and listen for HTTP traffic on a randomly-assigned endpoint URL
  • Line 18: print your app's endpoint url
  • Line 19-21: start an axum web server handling connections from the ngrok listener

Step 3: Run it!​

Copy the ngrok authtoken on your dashboard. You may need to sign up for ngrok if you haven't already.

Run your application with your authtoken in the environment:

NGROK_AUTHTOKEN="<TOKEN>" cargo r

Your terminal will print out your app's URL. Visit the URL in a browser and confirm you see "Hello from ngrok-rust!". Your Rust application is now live on the internet, with a URL that anyone on the internet can access. Test it out by sending it to a friend!

Step 4: Always use the same domain​

If you want to keep the same URL each time you run your app, create a static domain on your dashboard and then update your Session::builder chain to use it. Stop your app with Ctrl+C, update your code and then rerun it:

    let listener = ngrok::Session::builder()
        .authtoken_from_env()
        .connect()
        .await?
        .http_endpoint()
        .domain("jumpy-red-mollusk.ngrok-free.app")
        .listen()
        .await?;

Step 5: Secure your app​

You may not want everyone to be able to access your application. ngrok can quickly add authentication to your app with a few lines of code.

If your Google account is alan@example.com, you can restrict access only for yourself by modifying your main.rs file to:

use axum::{routing::get, Router};
use ngrok::prelude::*;
use ngrok::config::*;
use std::error::Error;

#[tokio::main]
async fn main() -> Result<(), Box<dyn Error>> {
    // build our application with a route
    let app = Router::new().route("/", get(|| async { "Hello World!" }));

    // listen on ngrok ingress (i.e. https://my-rust-app.ngrok.dev)
    let listener = ngrok::Session::builder()
        .authtoken_from_env()
        .connect()
        .await?
        .http_endpoint()
        .oauth(OauthOptions::new("google").allow_email("alan@example.com"))
        .listen()
        .await?;
    println!("App URL: {:?}", listener.url());
    axum::Server::builder(listener)
        .serve(app.into_make_service())
        .await?;
    Ok(())
}
In this code
  • Line 17: Require visitors to authenticate with Google before they access your application. You can choose other providers. Only allow alan@example.com access to the application

Run your app again and visit the URL it prints in the terminal.

Anyone accessing your app will be prompted to log in with Google and only your account will be allowed to access it. Keep in mind that when you restarted ngrok, your app's URL changed, so make sure to visit the new one.

Next Steps​