ngrok Rust SDK Quickstart
The ngrok Rust SDK is an open-source package that enables you to quickly and efficiently serve Node.js applications on the internet without the need to configure low-level network primitives like IPs, certificates, load balancers, or ports. You can think of it as the ngrok Agent CLI packaged as a Python library.
This quickstart uses the ngrok Rust SDK to create an agent endpoint that forwards traffic from the internet to a Rust app running on your local device, then secure it by requiring visitors to log in with a Google account to access it.
What you'll need
- An ngrok account.
- Your ngrok auth token.
- Rust installed on your machine. You can check this by running
rustc --version
in your terminal.
1. Reserve your domain
A new URL is generated for you every time you start an endpoint. To maintain a consistent URL, you can reserve a free static domain connected to your ngrok account.
Navigate to the dashboard, visit the Domains section, and select + New Domain. You can choose a free static domain, or you can use a custom domain you already own.
2. Start your app or service
Start up the app or service you'd like to put online. This is the app that your agent endpoint will forward online traffic to.
If you don't have an app to work with, you can set up a basic HTTP server at port 8080
.
First, create a directory for your Rust project and navigate into it:
Loading…
Next, create a new Rust project:
Loading…
Replace the contents of src/main.rs
with the following code to set up a basic HTTP server:
Loading…
Navigate to the root directory of the project and run the following command to start the server:
Loading…
3. Install the Rust SDK
Open a new terminal, then run the following commands to create a new Rust project install the Rust SDK:
Loading…
Edit your Cargo.toml
file to include the necessary dependencies:
Loading…
5. Create your endpoint
Create your agent endpoint, which will forward public traffic to your app.
In the ngrok-rust-demo
directory you created in the previous step, add the following code to your src/main.rs
file.
This example:
- Starts an Agent endpoint that forwards from your reserved domain to your service running on port
8080
. - Secures the endpoint with a that requires authentication via Google OAuth.
This example uses ngrok's default Google OAuth application. To use your own, see the OAuth Traffic Policy Action documentation.
Loading…
6. Test your endpoint
Test your endpoint by running the following terminal command, swapping in your auth token:
Loading…
This should print your reserved domain URL to the terminal. When you visit the URL, you should be prompted to log in with Google. After logging in, you'll see your app or service.
If you used the example app in this quickstart, you'll see "Hello from Rust HTTP Server!" displayed in your browser.
What's next?
In this guide, you learned how to use the Rust SDK to an create agent endpoint that forwards traffic to your localhost. You saw one way to implement a traffic policy directly in your codebase, including an action that adds authentication to your app with no configuration required. What else can you do with these features?
- Dig deeper into traffic policies, which enable you to grant conditional access, send custom headers, rewrite URLs, and more with your endpoints.
- Learn more about the Agent SDKs to understand how the Rust SDK works under the hood.
- Check out the ngrok Rust SDK repo for more code examples.
- If your use case calls for a centrally managed, always-on endpoint that isn't tied to the ephemeral lifetime of an agent endpoint, you should proceed to getting started with Cloud Endpoints.