Axum Library - ngrok documentation

ngrok-axum serves an Axum Router through an ngrok endpoint with one call:

ngrok_axum::serve(app, ngrok_axum::Config::default()).await?;

The crate is built on the Rust SDK. Axum 0.7 removed axum::Server, which took away the one-line way to serve an app on an ngrok listener. serve restores it: it opens the endpoint, accepts connections, and serves each one with Hyper so you don’t write the connection loop yourself.

ngrok-axum is published on crates.io at version 0.1.1 and maintained in the ngrok-samples/ngrok-axum repository.

What you’ll need

An ngrok account.
Your ngrok auth token.
Rust installed on your machine.

1. Install the crate

Add the crate alongside Axum 0.8 and Tokio:

Cargo.toml

[dependencies]
ngrok-axum = "0.1"
axum = "0.8"
tokio = { version = "1", features = ["full"] }

2. Set your auth token

Export your auth token as an environment variable:

export NGROK_AUTHTOKEN=your_actual_auth_token_here

The crate reads NGROK_AUTHTOKEN from the environment when it opens the session.

3. Serve your router

Replace axum::serve with ngrok_axum::serve:

src/main.rs

use axum::{routing::get, Router};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
    let app = Router::new().route("/", get(|| async { "Hello from Axum!" }));
    ngrok_axum::serve(app, ngrok_axum::Config::default()).await?;
    Ok(())
}

serve runs until the listener closes or a connection error occurs.

4. Test your endpoint

Run your app:

cargo run

The crate prints Ingress established at: followed by the public URL. With Config::default(), that URL is your account’s dev domain. Open it in your browser to see your Axum app.

Configuration

Pass a Config to set the URL, add a Traffic Policy, or change the binding:

let config = ngrok_axum::Config {
    url: Some("your-reserved-domain.ngrok.app".to_string()),
    traffic_policy: Some(r#"
on_http_request:
  - actions:
      - type: basic-auth
        config:
          credentials:
            - "user:password123"
"#.to_string()),
    ..Default::default()
};

ngrok_axum::serve(app, config).await?;

Field	Type	Description
`url`	`Option<String>`	The reserved domain for the endpoint. `None` uses your account’s dev domain.
`pooling`	`bool`	Opts in to endpoint pooling so more than one endpoint can share a URL.
`traffic_policy`	`Option<String>`	A raw Traffic Policy document (YAML or JSON) that the crate passes through to ngrok unchanged. Use it for authentication, IP restrictions, webhook verification, and any other action.
`binding`	`Option<Binding>`	The endpoint’s binding: `Binding::Public`, `Binding::Internal`, or `Binding::Kubernetes`.

Multiple endpoints

serve_many opens one endpoint per Endpoint, each with its own Router and Config, on a single session:

use ngrok_axum::{serve_many, Config, Endpoint};

serve_many(vec![
    Endpoint {
        app: app_router,
        config: Config { url: Some("app.mycompany.ngrok.app".into()), ..Default::default() },
    },
    Endpoint {
        app: api_router,
        config: Config { url: Some("api.mycompany.ngrok.app".into()), ..Default::default() },
    },
])
.await?;

serve is the one-endpoint case of serve_many. To put one router behind several listeners, clone the Router into more than one Endpoint. Every endpoint needs its own url, or pooling: true on each endpoint that shares one. If two endpoints would share a URL without pooling, including two endpoints that both leave url as None and land on your dev domain, serve_many returns an error before opening a session. Without that check, ngrok lets the most recently opened listener win and the other goes unreachable with no error.

Limits and availability

The crate opens HTTP endpoints only. For TCP or TLS endpoints, use the Rust SDK directly.
The crate requires Axum 0.8.
An Internal binding requires a url that ends in .internal. ngrok rejects any other URL with ERR_NGROK_9029.
A URL that another agent or a Cloud Endpoint already claims fails with ERR_NGROK_334.
Endpoint counts and domains follow your plan’s limits. See free plan limits.

What’s next?

Browse Traffic Policy examples to add authentication, restrict access by IP, or rewrite URLs.
Read the Rust SDK quickstart to see what the crate does under the hood.
See the other framework libraries for Next.js, Gin, and FastAPI.
Report issues or read the source in the ngrok-samples/ngrok-axum repository, which includes runnable examples for every option.

​What you’ll need

​1. Install the crate

​2. Set your auth token

​3. Serve your router

​4. Test your endpoint

​Configuration

​Multiple endpoints

​Limits and availability

​What’s next?

What you’ll need

1. Install the crate

2. Set your auth token

3. Serve your router

4. Test your endpoint

Configuration

Multiple endpoints

Limits and availability

What’s next?