ngrok Documentation

The ngrok agent exposes a local HTTP API that allows you to programmatically manage your running agent. Key capabilities include:

• Metrics & Status: Collect status and metrics information for tunnels and endpoints.
• Request Inspection: Collect and replay captured HTTP requests.
• Dynamic Management: Start, stop, create, or update endpoints and tunnels dynamically.

Note: If you need to programmatically control the ngrok agent, consider using the Agent SDKs instead of the API for a more robust integration.

ngrok provides developer infrastructure to route and secure traffic to apps, APIs, and AI models. The platform is divided into three core products that build upon shared connectivity primitives:

• Gateway: A cloud networking platform used to secure, transform, and route traffic to services across any environment (AWS, Azure, GCP, on-prem, etc.).
• AI Gateway: A specialized gateway to route, secure, and manage traffic to any LLM (cloud or local) through a single endpoint, allowing access to providers like OpenAI and Anthropic without individual sign-ups.
• Share Localhost: A tool to expose services running on localhost to the internet, bypassing the need for port forwarding, DNS changes, or firewall rules.

The ngrok AI Gateway (ngrok.ai) provides a single endpoint to route requests to both hosted AI providers (like OpenAI and Anthropic) and self-hosted models (like Ollama or vLLM).

Key capabilities include:

• No Provider Accounts Required: Use built-in OpenAI and Anthropic models using ngrok.ai access keys and credits, bypassing the need for direct provider signups.
• Automatic Failover: Automatically retry the next model or key if a provider or key fails.
• Self-Hosted Routing: Route requests to models you run yourself.
• Compatibility: Works with official and third-party SDKs by simply pointing the base URL to the ngrok gateway.

Every request consumes credits.

ngrok's Traffic Policy is a configuration language used to filter, match, manage, and orchestrate traffic to your endpoints. It allows you to apply security controls and traffic management directly to any type of ngrok endpoint.

Key capabilities include:

• Traffic Validation & Security: Block malicious traffic, validate JWTs, or restrict access by IP address/Tor exit nodes.
• Traffic Transformation: Rewrite URLs and paths, modify request headers, or transform response bodies.
• Traffic Orchestration: Forward traffic to agents globally and manage flow across your infrastructure.
• Rate Limiting: Protect services by limiting requests based on endpoint, IP address, or API key.

The ngrok Kubernetes Operator allows you to securely expose your Kubernetes services using standard Kubernetes resources such as Ingress or the Gateway API. It enables teams to manage ngrok endpoints for their applications through a shared ngrok account.

Key Capabilities:

• Secure Ingress: Use standard K8s resources to manage secure access to services.
• Bindings: Optionally use bindings to make services running outside the cluster (e.g., on a local machine or in a different cluster) appear as normal Kubernetes Services within your cluster. This facilitates private, cross-cluster connectivity without exposing public URLs.

The ngrok free plan includes several types of restrictions:

1. Monthly usage quotas: Reset each billing cycle.
2. Rate limits: Cap sustained throughput at any given moment.
3. Concurrency and account limits: Apply at all times.

Free endpoints do not have a timeout and can stay online indefinitely. To run an endpoint unattended, you should run ngrok as a background service.

You can monitor your current usage against these limits in the Usage page of your ngrok dashboard.

This architecture enables secure, seamless access to devices and servers within a remote network using a single ngrok Agent.

Key components of the implemented system include:

• Single Agent Deployment: One ngrok agent per remote network, eliminating the need for multiple installations.
• Hybrid Endpoint Access: Devices and servers are available via both cloud endpoints (for remote access) and internal endpoints (for local network access).
• Granular Security: Access is controlled using composable Traffic Policies, providing robust security measures for individual endpoints.
• Security Standards: For information on ngrok's security, trust, compliance, and privacy standards to share with end users, refer to the site-to-site connectivity guide.

The ngrok.ai API allows you to manage your AI Gateway resources programmatically instead of using the dashboard. You can automate the creation of access keys, management of provider credentials, routing configurations, and monitoring of usage and credits.

Important Distinction: The management API (https://api.ngrok.ai) is used for configuration and administration. It does not handle the actual model inference requests. To send requests to AI models through the gateway, you must send them to https://gateway.ngrok.ai using an access key.