ngrok 0.9.0

The ngrok agent SDK
Documentation

The ngrok Agent SDK

Crates.io docs.rs MIT licensed Apache-2.0 licensed Continuous integration

Website | API Docs (unstable)

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 Rust applications. This allows you to quickly build ngrok into your application with no separate process to manage.

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.8"

...

Alternatively, with cargo-edit:

$ cargo add ngrok

Quickstart

Create a simple HTTP server using ngrok and axum:

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

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.