The ngrok Agent SDK

Website | API Docs (main)

ngrok is a simplified API-first ingress-as-a-service that adds connectivity, security, and observability to your apps.

ngrok-rs, our native and idiomatic crate for adding a public internet address with secure ingress traffic directly into your Rust apps 🦀. If you’ve used ngrok in the past, you can think of ngrok-rs as the ngrok agent packaged as a Rust crate.

ngrok-rs lets developers serve Rust services on the internet in a single statement without setting up low-level network primitives like IPs, NAT, certificates, load balancers, and even ports! Applications using ngrok-rs listen on ngrok’s global ingress network for TCP and HTTP traffic. ngrok-rs listeners are usable with hyper Servers, and connections implement tokio’s AsyncRead and AsyncWrite traits. This makes it easy to add ngrok-rs into any application that’s built on hyper, such as the popular axum HTTP framework.

See /ngrok/examples/ for example usage, or the tests in /ngrok/src/online_tests.rs.

For working with the ngrok API, check out the ngrok Rust API Client Library.

If you're looking for the agent wrapper, it's over here. See UPGRADING.md for tips on migrating.

Installation

Add ngrok to the [dependencies] section of your Cargo.toml:

...

[dependencies]
ngrok = "0.11"

...

Alternatively, with cargo add:

$ cargo add ngrok

Quickstart

Create a simple HTTP server using ngrok and axum:

Cargo.toml:

[package]
name = "ngrok-axum-example"
version = "0.1.0"
edition = "2021"

[dependencies]
ngrok = { version="0.11", features=["axum"] }
tokio = { version = "1.26", features = ["full"] }
axum = "0.6"
anyhow = "1.0"

src/main.rs:

use std::net::SocketAddr;

use axum::{
    extract::ConnectInfo,
    routing::get,
    Router,
};
use ngrok::prelude::*;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    // build our application with a single route
    let app = Router::new().route(
        "/",
        get(
            |ConnectInfo(remote_addr): ConnectInfo<SocketAddr>| async move {
                format!("Hello, {remote_addr:?}!\r\n")
            },
        ),
    );

    let tun = ngrok::Session::builder()
        // Read the token from the NGROK_AUTHTOKEN environment variable
        .authtoken_from_env()
        // Connect the ngrok session
        .connect()
        .await?
        // Start a tunnel with an HTTP edge
        .http_endpoint()
        .listen()
        .await?;

    println!("Tunnel started on URL: {:?}", tun.url());

    // Instead of binding a local port like so:
    // axum::Server::bind(&"0.0.0.0:8000".parse().unwrap())
    // Run it with an ngrok tunnel instead!
    axum::Server::builder(tun)
        .serve(app.into_make_service_with_connect_info::<SocketAddr>())
        .await
        .unwrap();

    Ok(())
}

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 by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.