|
| 1 | +--- |
| 2 | +title: Why Agent SDKs |
| 3 | +description: Learn why ngrok's Agent SDKs let you embed secure connectivity directly into your application without running a separate process. |
| 4 | +--- |
| 5 | + |
| 6 | +ngrok's Agent SDKs embed ngrok directly into your application as a native library. Instead of running a separate agent process, you add ngrok as a dependency and create endpoints in code. |
| 7 | + |
| 8 | +<CodeGroup> |
| 9 | +```go example.go |
| 10 | +fwd, _ := ngrok.Forward(ctx, |
| 11 | + ngrok.WithUpstream("http://localhost:8085"), |
| 12 | +) |
| 13 | +log.Println("Available at:", fwd.URL()) |
| 14 | +``` |
| 15 | + |
| 16 | +```python example.py |
| 17 | +listener = ngrok.forward("localhost:8085", authtoken_from_env=True) |
| 18 | +print(f"Available at: {listener.url()}") |
| 19 | +``` |
| 20 | + |
| 21 | +```javascript example.js |
| 22 | +const listener = await ngrok.forward({ addr: 8085, authtoken_from_env: true }); |
| 23 | +console.log(`Available at: ${listener.url()}`); |
| 24 | +``` |
| 25 | +</CodeGroup> |
| 26 | + |
| 27 | +Your app listens for connections from ngrok's global network the same way it would listen on a local port—a `net.Listener` in Go, a single `forward()` call in Python and JavaScript. TLS, auth, rate limiting, and traffic management are handled at ngrok's edge before requests ever reach your code. |
| 28 | + |
| 29 | +## How it works |
| 30 | + |
| 31 | +When you call `ngrok.Forward()` or `ngrok.forward()`, the SDK establishes a secure, persistent outbound TLS connection to ngrok's nearest Point of Presence. Your app's traffic configuration—domains, auth policies, IP restrictions—is transmitted through that connection and enforced at ngrok's edge. Unauthorized requests are blocked before they reach your application. |
| 32 | + |
| 33 | +There's no inbound port to open, no certificate to manage, no load balancer to configure. |
| 34 | + |
| 35 | +## Networking as a high-level abstraction |
| 36 | + |
| 37 | +Getting an application online typically means managing DNS, TLS certificates, CIDR policies, NATs, reverse proxies, and load balancers—low-level networking details that have nothing to do with your application's business logic. The SDKs abstract all of that into your code. |
| 38 | + |
| 39 | +You define traffic management with ngrok's [Traffic Policy](/traffic-policy/) engine—a portable, YAML/JSON-based rules language that works identically across SDKs, Cloud Endpoints, Agent Endpoints, and the Kubernetes Operator. Pass a Traffic Policy inline to add auth, rate limiting, or routing to any endpoint: |
| 40 | + |
| 41 | +<CodeGroup> |
| 42 | +```go example.go |
| 43 | +fwd, _ := ngrok.Forward(ctx, |
| 44 | + ngrok.WithUpstream("http://localhost:8085"), |
| 45 | + ngrok.WithTrafficPolicy(` |
| 46 | + on_http_request: |
| 47 | + - actions: |
| 48 | + - type: oauth |
| 49 | + config: |
| 50 | + provider: google |
| 51 | + `), |
| 52 | +) |
| 53 | +``` |
| 54 | + |
| 55 | +```python example.py |
| 56 | +listener = ngrok.forward( |
| 57 | + "localhost:8085", |
| 58 | + authtoken_from_env=True, |
| 59 | + traffic_policy=json.dumps({ |
| 60 | + "on_http_request": [ |
| 61 | + {"actions": [{"type": "oauth", "config": {"provider": "google"}}]}, |
| 62 | + ], |
| 63 | + }), |
| 64 | +) |
| 65 | +``` |
| 66 | + |
| 67 | +```javascript example.js |
| 68 | +const listener = await ngrok.forward({ |
| 69 | + addr: 8085, |
| 70 | + authtoken_from_env: true, |
| 71 | + traffic_policy: JSON.stringify({ |
| 72 | + on_http_request: [ |
| 73 | + { actions: [{ type: "oauth", config: { provider: "google" } }] }, |
| 74 | + ], |
| 75 | + }), |
| 76 | +}); |
| 77 | +``` |
| 78 | +</CodeGroup> |
| 79 | + |
| 80 | +Because Traffic Policy is a string validated server-side, new traffic management features are available immediately—without upgrading your SDK version. |
| 81 | + |
| 82 | +## No sidecar, no process management |
| 83 | + |
| 84 | +The SDK is a library, not a binary. Install it with your language's package manager. One process, one deployment artifact, one thing to monitor. |
| 85 | + |
| 86 | +This matters most in environments where a separate process isn't practical—IoT devices, embedded systems, edge runtimes, constrained containers—but it simplifies operations everywhere. No binary distribution, no sidecar orchestration, no agent lifecycle management. |
| 87 | + |
| 88 | +## Portable across environments |
| 89 | + |
| 90 | +When your application uses the SDK, it receives traffic the same way no matter where it runs: bare metal, VMs, AWS, Azure, Kubernetes, serverless platforms, a Raspberry Pi, or your laptop. Ingress is decoupled from the hosting environment—no per-environment networking configuration. |
| 91 | + |
| 92 | +## Dynamic, programmatic control |
| 93 | + |
| 94 | +Config files are static. Code isn't. Create endpoints conditionally from feature flags. Parameterize traffic policies from environment variables. Spin up listeners in response to events and tear them down when you're done. |
| 95 | + |
| 96 | +## Framework support |
| 97 | + |
| 98 | +The SDKs integrate with popular frameworks in each language. In Python, ngrok works with Flask, Django, Uvicorn, Gunicorn, AIOHTTP, and Tornado. In JavaScript, there's support for Express, Next.js, Remix, Svelte, and more. See the examples in each SDK's GitHub repo for integration guides. |
| 99 | + |
| 100 | +## SDK vs. agent |
| 101 | + |
| 102 | +Both connect your app to ngrok's network with the same capabilities. The difference is where ngrok runs. |
| 103 | + |
| 104 | +**Use the SDK when** you're shipping production software, building a platform that needs embedded connectivity, deploying to constrained environments, or managing endpoints dynamically at runtime. |
| 105 | + |
| 106 | +**Use the agent when** you want to expose a running service without modifying its code, or you're doing local development and testing. |
| 107 | + |
| 108 | +## What people build with them |
| 109 | + |
| 110 | +- **Embedded connectivity in developer tools.** Ship secure tunneling as part of your own CLI or platform—no separate ngrok install for your users. |
| 111 | +- **Secure access to APIs in customer networks.** Replace per-customer VPN and firewall configs with a standardized connectivity layer that scales. |
| 112 | +- **IoT and device fleet management.** Reach APIs on devices outside the corporate network at scale, with consistent security policies. |
| 113 | +- **Self-contained production services.** Collapse external reverse proxy and load balancer dependencies into the application itself. |
0 commit comments