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.
Add ngrok to the [dependencies] section of your Cargo.toml:
...
[dependencies]
ngrok = "0.11"
...Alternatively, with cargo add:
$ cargo add ngrokCreate 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(())
}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.
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.