ngrok-fastapi

Bring ngrok Traffic Policy, pooling, and binding config to FastAPI — via FastAPI's own lifespan hook, with one call:

from fastapi import FastAPI
import ngrok_fastapi

app = FastAPI()
ngrok_fastapi.attach(app, ngrok_fastapi.Config(port=8000))

What it is

A small FastAPI-native ngrok library. attach()/attach_many() wrap an app's existing lifespan context manager so an ngrok tunnel opens when the app starts and closes when it stops.

Setup

1. Sign up at ngrok.com and grab an authtoken from the dashboard.
2. Set it as an env var: NGROK_AUTHTOKEN=your_token_here
3. pip install ngrok-fastapi and call attach() — see examples/basic.py.

Config

ngrok_fastapi.attach(app, ngrok_fastapi.Config(
    port=8000,
    url="your-reserved-domain.ngrok.app",  # None = account's default dev domain
    pooling=False,
    traffic_policy="""
on_http_request:
  - actions:
      - type: basic-auth
        config:
          credentials:
            - "user:password123"
""",
    binding=None,  # ngrok_fastapi.Binding.INTERNAL, etc.
))

See examples/with_config.py for a working example.

Multiple endpoints

attach_many(app, configs) opens one endpoint per Config, all on a single session, and ties all of them to the same app's lifespan. attach(app, config) is just attach_many(app, [config]).

ngrok_fastapi.attach_many(app, [
    ngrok_fastapi.Config(port=8000, url="app.mycompany.ngrok.app"),
    ngrok_fastapi.Config(port=8001, url="api.mycompany.ngrok.app"),
])

Development

python3 -m venv venv && source venv/bin/activate
pip install -e ".[dev]"
pytest
python examples/basic.py

See DESIGN.md for the design rationale and everything confirmed empirically along the way.

License

MIT OR Apache-2.0